How to create a git directory template

Jul 21, 2020

Sometimes, having a global configuration isn't enough. You will also need to trigger the execution of scripts (also known as Git hooks), exclude files, and so on. It is possible to achieve this with the template option set to git init. It can be given as a command-line option to git clone and git init, or as the $GIT_TEMPLATE_DIR environment variable, or as the configuration option init.templatedir. It defaults to /usr/share/git-core/templates. The template option works by copying files in the template directory to the .git ($GIT_DIR) folder after it has been created. The default directory contains sample hooks and some suggested exclude patterns. In the following example, we'll see how we can set up a new template directory, and add a commit message hook and an exclude file.

Step 1 : First, we will create the template directory. We can use any name we want, and we'll use ~/.git_template, as shown in the following command:

mkdir ~/.git_template

Step 2 : Now, we need to populate the directory with some template files. This could be a hook or an exclude file. We will create one hook file and one exclude file. The hook file is located in .git/hooks/name-of-hook and the exclude file in .git/info/exclude. Create the two directories needed, hooks and info, as shown in the following command:

mkdir ~/.git_template/{hooks,info}

Step 3 : To keep the sample hooks provided by the default template directory (the Git installation), we copy the files in the default template directory to the new one. When we use our newly created template directory, we'll override the default one. So, copying the default files to our template directory will make sure that, excepting our specific changes, the template directory is similar to the default one, as shown in the following command:

cd ~/.git_template/hooks
cp /usr/share/git-core/templates/hooks/* .

Step 4 : We'll use the commit-msg hook as the example hook

Step 5 : The hook is very simple and will just add Hi from the template commit-msg hook to the end of the commit message. Save it as commit-msg in the ~/.git_template/hooks directory and make it executable by using the following command:

chmod +x ~/.git_template/hooks/commit-msg

Now that the commit message hook is done, let's also add an exclude file to the example. The exclude file works like the .gitignore file, but is not tracked in the repository.

Step 6 : We'll create an exclude file that excludes all the *.txt files, as follows:

echo "*.txt" > ~/.git_template/info/exclude

Now, our template directory is ready for use.

Step 7 : Our template directory is ready, and we can use it, as described earlier, as a command-line option, an environment variable or, as in this example, to be set as a configuration:

git config --global init.templatedir ~/.git_template

Step 8 : Now, all Git repositories we create using init or clone will have the default files of the template directory. We can test whether it works by creating a new repository as follows:

git init template-example
cd template-example

Step 9 : Let's try to create a .txt file and see what git status tells us. It should be ignored by the exclude file from the template directory:

echo "this is the readme file" > README.txt
git status 

The exclude file worked! You can put in the file endings yourself, or just leave it blank and keep to the .gitignore files.

Step 10 : To test whether the commit-msg hook works, let's try to create a commit. First, we need a file to commit. So, let's create that and commit it as follows:

echo "something to commit" > somefile
git add somefile
git commit -m "Committed something"

Step 11 : We can now check the history with git log:

git log -1

When Git creates a new repository, either via init or clone, it will copy the files from the template directory (the default location is /usr/share/git-core/templates) to the new repository when creating the directory structure. The template directory can be defined either by a command-line argument, an environment variable, or a configuration option. If nothing is specified, the default template directory will be used (distributed with the Git installation). By setting the configuration as a --global option, the template directory defined will apply to all of the user's (new) repositories. This is a very nice way to distribute the same hooks across repositories, but it also has some drawbacks. As the files in the template directory are only copied to the Git repositories, updates to the template directory do not affect the existing repositories. This can be solved by running git init in each existing repository to reinitialize the repository, but this can be quite cumbersome. Also, the template directory can enforce hooks on some repositories where you don't want them. This is quite easily solved by simply deleting the hook files in .git/hooks of that repository.