(For more resources related to this topic, see here.)
Configuration targets
In this section, we look at the different layers that can be configured. The layers are:
-
SYSTEM: This layer is system-wide and found in /etc/gitconfig
-
GLOBAL: This layer is global for the user and found in ~/.gitconfig
-
LOCAL: This layer is local to the current repository and found in .git/config
Getting ready
We will use the jgit repository for this example, as shown in the following command:
$ git clone https://git.eclipse.org/r/jgit/jgit $ cd jgit
How to do it…
In the previous example, we saw how we could use the command git config –list to list configuration entries. This list is actually made from three different levels of configuration that Git offers: system-wide configuration, SYSTEM; global configuration for the user, GLOBAL; and local repository configuration, LOCAL.
For each of these configuration layers, we can query the existing configuration. On a Windows box with a default installation of the Git extensions, the different configuration layers will look approximately like the following:
$ git config --list --system core.symlinks=false core.autocrlf=true color.diff=auto color.status=auto color.branch=auto color.interactive=true pack.packsizelimit=2g help.format=html http.sslcainfo=/bin/curl-ca-bundle.crt sendemail.smtpserver=/bin/msmtp.exe diff.astextplain.textconv=astextplain rebase.autosquash=true $ git config --list --global merge.tool=kdiff3 mergetool.kdiff3.path=C:/Program Files (x86)/KDiff3/kdiff3.exe diff.guitool=kdiff3 difftool.kdiff3.path=C:/Program Files (x86)/KDiff3/kdiff3.exe core.editor="C:/Program Files (x86)/GitExtensions/
GitExtensions.exe" fileeditor core.autocrlf=true credential.helper=!"C:/Program Files (x86)/GitExtensions/
GitCredentialWinStore/git-credential-winst ore.exe" user.name=Aske Olsson [email protected] $ git config --list --local core.repositoryformatversion=0 core.filemode=false core.bare=false core.logallrefupdates=true core.symlinks=false core.ignorecase=true core.hidedotfiles=dotGitOnly remote.origin.url=https://git.eclipse.org/r/jgit/jgit remote.origin.fetch=+refs/heads/*:refs/remotes/origin/* branch.master.remote=origin branch.master.merge=refs/heads/master
We can also query a single key and limit the scope to one of the three layers, by using the following command:
$ git config --global user.email [email protected]
We can set the e-mail address of the user to a different one for the current repository:
$ git config --local user.email [email protected]
Now, listing the GLOBAL layer user.email will return [email protected], listing LOCAL gives [email protected], and listing user.email without specifying the layer gives the effective value that is used in the operations on this repository, in this case, the LOCAL value [email protected]. The effective value is the value, which takes precedence when needed. When two or more values are specified for the same key, but on different layers, the lowest layer takes precedence. When a configuration value is needed, Git will first look in the LOCAL configuration. If not found here, the GLOBAL configuration is queried. If it is not found in the GLOBAL configuration, the SYSTEM configuration is used. If none of this works, the default value in Git is used.
In the previous example, user.email is specified in both the GLOBAL and LOCAL layers. Hence, the LOCAL layer will be used.
How it works…
Querying the three layers of configuration simply returns the content of the configuration files: /etc/gitconfig for system-wide configuration, ~/.gitconfig for user-specific configuration, and .git/config for repository-specific configuration. When not specifying the configuration layer, the returned value will be the effective value.
There’s more…
Instead of setting all the configuration values on the command line by the key value, it is possible to set them by just editing the configuration file directly. Open the configuration file in your favorite editor and set the configuration you need, or use the built-in git config -e repository to edit the configuration directly in the Git-configured editor. You can set the editor to the editor of your choice either by changing the $EDITOR environment variable or with the core.editor configuration target, for example:
$ git config --global core.editor vim
Querying the existing configuration
In this example, we will look at how we can query the existing configuration and set the configuration values.
Getting ready
We’ll use jgit again by using the following command:
$ cd jgit
How to do it…
To view all the effective configurations for the current Git repository, run the following command:
$ git config --list user.name=Aske Olsson [email protected] core.repositoryformatversion=0 core.filemode=false core.bare=false core.logallrefupdates=true remote.origin.url=https://git.eclipse.org/r/jgit/jgit remote.origin.fetch=+refs/heads/*:refs/remotes/origin/* branch.master.remote=origin branch.master.merge=refs/heads/master
The previous output will of course reflect the user running the command. Instead of Aske Olsson as the name and the e-mail, the output should reflect your settings.
If we are just interested in a single configuration item, we can just query it by its section.key or section.subsection.key:
$ git config user.name Aske Olsson $ git config remote.origin.url https://git.eclipse.org/r/jgit/jgit
How it works…
Git’s configuration is stored in plaintext files, and works like a key-value storage. You can set/query by key and get the value back. An example of the text-based configuration file is shown as follows (from the jgit repository):
$ cat .git/config [core] repositoryformatversion = 0 filemode = false bare = false logallrefupdates = true [remote "origin"] url = https://git.eclipse.org/r/jgit/jgit fetch = +refs/heads/*:refs/remotes/origin/* [branch "master"] remote = origin merge = refs/heads/master
There’s more…
It is also easy to set configuration values. Just use the same syntax as when querying the configuration except add an argument to the value. To set a new e-mail address on the LOCAL layer, we can execute the following command line:
git config user.email [email protected]
The LOCAL layer is the default if nothing else is specified. If you require whitespaces in the value, you can enclose the string in quotation marks, as you would do when configuring your name:
git config user.name "Aske Olsson"
You can even set your own configuration, which does not have any effect on the core Git, but can be useful for scripting/builds and so on:
$ git config my.own.config "Whatever I need"
List the value
$ git config my.own.config Whatever I need
It is also very easy to delete/unset configuration entries:
$ git config --unset my.own.config
List the value
$ git config my.own.config
Templates
In this example, we will see how to create a template commit message that will be displayed in the editor when creating a commit. The template is only for the local user and not distributed with the repository in general.
Getting ready
In this example, we will use the example repository:
$ git clone https://github.com/dvaske/data-model.git $ cd data-model
We’ll use the following code as a commit message template for commit messages:
Short description of commit Longer explanation of the motivation for the change Fixes-Bug: Enter bug-id or delete line Implements-Requirement: Enter requirement-id or delete line
Save the commit message template in $HOME/.gitcommitmsg.txt. The filename isn’t fixed and you can choose a filename of your liking.
How to do it…
To let Git know about our new commit message template, we can set the configuration variable commit.template to point at the file we just created with that template; we’ll do it globally so it is applicable to all our repositories:
$ git config --global commit.template $HOME/.gitcommitmsg.txt
Now, we can try to change a file, add it, and create a commit. This will bring up our preferred editor with the commit message template preloaded:
$ git commit Short description of commit Longer explanation of the motivation for the change Fixes-Bug: Enter bug-id or delete line Implements-Requirement: Enter requirement-id or delete line # Please enter the commit message for your changes. Lines starting # with '#' will be ignored, and an empty message aborts the commit. # On branch master # Changes to be committed: # (use "git reset HEAD <file>..." to unstage) # # modified: another-file.txt # ~ ~ ".git/COMMIT_EDITMSG" 13 lines, 396 characters
We can now edit the message according to our commit and save to complete the commit.
How it works…
When commit.template is set, Git simply uses the content of the template file as a starting point for all commit messages. This is quite convenient if you have a commit-message policy as it greatly increases the chances of the policy being followed. You can even have different templates tied to different repositories, since you can just set the configuration at the local level.
A .git directory template
Sometimes, having a global configuration isn’t enough. You will also need to trigger the execution of scripts (aka 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 us 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 <[email protected]> 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.
