Skip to content

How to Put Docker Compose Files Under Git Version Control


Consider an application that consists of many individual projects. The frontend and backend are separate. The backend splits into many parts, like API and services. And the docker-compose.yml file lives inside the root directory of all these projects.

├─ api
├─ service-one
├─ service-two
├─ client
├─ docker-compose.yml

Each individual part — api, client, and others — is a Git repository. The root directory itself is not, so changes to the Compose file are not tracked.

How do you version control your docker-compose.yml file in such layout?

The short answer is to set up a Git repository for Compose files and use a symbolic link.

ln -s /path/to/repository/app-compose.yml /path/to/app/docker-compose.yml

Continue reading for more details.

Step 1 — Creating a Repository for Compose Files

Set up a Git repository where you will keep all your Compose files for each application you work on.

cd ~/Projects
mkdir docker-compose-files
cd docker-compose-files
git init

This will create a new directory in ~/Projects/docker-compose-files and initialize a new Git repository.

You are ready to track changes to your Compose files.

Step 2 — Adding Compose File to Version Control

Move your current project’s Compose file to the newly created Git repository.

mv ~/Projects/my-project/docker-compose.yml ./my-project-compose.yml
git add .
git commit -m "Add my-project-compose.yml"

The docker-compose-files repository you just created will now track changes to your Compose files.

But, now you need to get the version-controlled Compose file back into your project.

Now create a reference of the version-controlled Compose file to your application directory.

You need to first specify a path to the Compose file in your version control repository. Then, specify a path to your application’s root directory, where you would like to keep the Compose file.

ln -s $PWD/my-project-compose.yml ~/Projects/my-project/docker-compose.yml

This command creates a link from your application’s root to the Compose file under version control.

You can use $PWD environment variable to reference your current working directory.

The -s argument is what creates a symbolic link, omitting it would create a hard link.


Projects folder structure should look something like this.

├─ docker-compose-files
│  ├─ my-project-compose.yml
├─ my-project
│  ├─ api
│  ├─ service-one
│  ├─ service-two
│  ├─ client
│  ├─ docker-compose.yml

Making changes to my-project-compose.yml or docker-compose.yml will reflect in the other file.

The docker-compose-files repository will track any changes you make to these files.

While working on your application, you can edit the docker-compose.yml file. But, after doing so, you must commit your changes of my-project-compose.yml file inside the docker-compose-files repository.

When you start a new project, create a Compose file in docker-compose-files repository. After that, create a link to your project’s root directory, and you’re done.