Using a template configuration file for git repos

We need a template configuration file to store in the repo for developers to edit/change in their deployment of the application. Traditional, you would use the .gitignore file. However, as I will explain .gitignore is not suitable for this situation.

Why we can't use .gitignore

Before we talk about the solution, we first need to understand why .gitignore won't work for our situation and more importantly, when would it be appropriate to use .gitignore. The main purpose of the .gitignore file is used to tell git to ignore the untracked files that are specified. Git effectively pretends that the specified files are not part of the repo.

This won't work for our situation because we want to track and maintain a configuration file so that a template exists on the repo. While allowing us to maintain our own local copy of the file for our personal configuration.

A situation where .gitignore would work is if you were wanting a local configuration file without the need to maintain a template copy of the file on the remote repo. A disadvantage of this is that you will need to tell anyone who wants to use the repo, that they will need to create the configuration file themselves, as it wouldn't already exist in the repo.

The solution.

To maintain a template copy of a file on a remote repo, we can't use .gitignore. However, we can use the update-index command to tell git how to treat the configuration file.

Creating the configuration file.

First, we need to start by creating our configuration file. This does not necessarily have to be a configuration file, it can be any file(s) that you want to have a different remote copy to the local copy. Assuming you have initialised your repository, I'm going to start by creating the template configuration file that I want to the remote repo to have.

 {
    "config_id": "development",
    "app_name": "Example Application",
    "app_desc": "This is an application that is used as an example",
    "domain": "localhost:8080",
    "node_port": 8080,
    "host": "localhost",
    "user": "user",
    "password": "password",
    "database": "database",
    "ExampleApiKey": "API KEY"
}

Committing & pushing the template configuration file.

Now you can commit the configuration file as you would any other file.

 git add config.json

 git commit -m "Added template configuration file"

 git push

Setting the skip-work-tree flag for the configuration file.

Now we are going to set the skip-work-tree flag for the configuration file. This will tell git to ignore all future changes to the file that you have specified in the parameter.

 git update-index --skip-worktree config.json
 // syntax: git update-index --skip-worktree <file>

Before we continue, let's find out exactly what this command is doing.

• update-index This git command tells git to update the index for the file specified.
• —skip-worktree This flag tells git to pretend that the specified file is always up to date, even if it has been modified, this is the secret that will allow us to modify the configuration file with our own values without worrying about mistakenly committing them to git.

This command will only affect your local repo, So you will need to execute it on any repo you want the changes to be ignored for.

Populating the configuration file with our values.

Now, git will ignore any other changes we make to the configuration file. This means the template file will remain on the remote repo for other developers to use.

I'm going to go ahead and populate the configuration file with some dummy data:

 {
    "config_id": "development",
    "app_name": "Example Application",
    "app_desc": "This is an application that is used as an example",
    "domain": "example.com",
    "node_port": 8081,
    "host": "exampleHost",
    "user": "exampleUser",
    "password": "examplePass",
    "database": "exampleDatabase",
    "ExampleApiKey": "CF1Bmw*xr5-Example-Key-e4msRhhhF3"
 }

Now, if we run the following git command:

 git status

You will see that the changes we have just made, are not being tracked. This means that we won't run the risk of mistakenly committing our private passwords and API keys to GitHub.

Changing the template

After a while, there may come a time where you want to change the template config on the public git repository. So to tell git to start paying attention to the changes in config.json, we simply need to run the same command again. This will toggle the —skip-worktree flag back off.

 git update-index --skip-worktree config.json

We are then free to make the changes that we want to make and commit the new template config file. Once we're finished updating the template, we can just run the update-index command again, and it will once again stop tracking the changes made to the config file.

Comments

[Rishav Jadon]

Nice tutorial! Any other use case than when sharing the repo ppl can see a template file?

[Leon Wilberforce]

I don't think there are any other main use cases.
I'm sure it would be useful for a few specific situations, but I mostly use it for providing config templates.