A .git directory template

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 exclude file.

Getting ready

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

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 an 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}

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 except for 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/* .

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

#!/bin/sh
MSG_FILE="$1"
echo "\nHi from the template commit-msg hook" >> $MSG_FILE

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. 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.

How to do it...

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

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

$ git init template-example
$ cd template-example

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.

To test if the commit-msg hook also 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"

We can now check the history with git log:

$ git log -1
commit 1f7d63d7e08e96dda3da63eadc17f35132d24064
Author: Aske Olsson <aske.olsson@switch-gears.dk>
Date: Mon Jan 6 20:14:21 2014 +0100

 Committed something

 Hi from the template commit-msg hook

How it works...

When Git creates a new repository, either via init or clone, it will copy the files from the template directory to the new repository when creating the directory structure. The template directory can be defined either by a command-line argument, environment variable, or 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.

See also

• For more information on hooks in Git, please refer to Chapter 7, Enhancing Your Daily Work with Git Hooks, Aliases, and Scripts