Git: Understanding Git Config

The format of Git internal configuration file (.git/config) is very simple: it has multiple sections, each of which contains multiple options. An option is indeed a key-value pair...

Logo Git

Today, let’s take a look in Git configuration file (.git/config). Git config is an INI file, a basic structure composed of sections, properties, and values. After reading this post, you’ll understand: what is the structure of such file; what happens when you read, add, modify, or delete an option from configuration file; the scope of different configuration files.

Now, let’s get started.


"Pro Git (2nd Edition)" contains everything you need to know about Git, written by Scott Chacon and Ben Straub. The print version is available on Amazon: https://amzn.to/31CKi27


Preparation

First of all, create a new project (done in macOS):

$ mkdir demo && cd demo
$ git init
Initialized empty Git repository in /Users/mincong/demo/.git/

Now, the Git configuration file (.git/config) looks like the following:

[core]
  repositoryformatversion = 0
  filemode = true
  bare = false
  logallrefupdates = true
  ignorecase = true
  precomposeunicode = true

Format

The basic element contained in git config is the property. Every property has a name and a value, delimited by an equals sign (=). The name appears to the left of the equals sign.

bare = false

Keys may be grouped into arbitrarily named sections. The section name appears on a line by itself, in square brackets ([ and ]). All keys after the section declaration are associated with that section. There’s no explicit end of section—a section is ended at the next section declaration, or end of file.

[section1]
  a = a
  b = b
[section2]
  c = c

Read an Option

To read an option in Git config, the syntax is:

git config [ --get ] <option>

To read option user.name in Git config, do

$ git config --get user.name
Mincong HUANG

Or your can omit the --get keyword:

$ git config user.name
Mincong HUANG

Add an Option

To add an new option into Git config, the syntax is:

git config <option> <value>

To set the mysection.k to v, do:

$ git config mysection.k v

If the section associated to option does not exist, this section will be added to the configuration file:

[mysection]
  ; mysection is created during the
  ; creation of option "mysection.k"
  k = v

Modify an Option

Same as add an option.

Delete an Option

To delete an option in Git config, the syntax is:

git config --unset <option>

For example, unset the option mysection.a, do

$ git config --unset mysection.a

After having unset the option, the configuration file looks like:

# Empty section: all the keys have been
# removed, but the section remains.
[mysection]

Configuration Scopes

There’re 3 scopes of configuration:

  • local (--local, default)
  • global (--global)
  • system (--system)

Local options are stored in .git/config file. When using command option --local to write, the value will be written into .git/config file, which is the default behavior. When using command option --local to read, only the local configuration properties will be read. This is different from the default behavior, where all available files (local, global, system) are read.

Global options are stored in ~/.gitconfig file. When using command option --global to write, the value will be written into $XDG_CONFIG_HOME/git/config file if this file exists and the ~/.gitconfig file doesn’t. When using command option --global to read, only the global scoped configuration will be read rather than from all available files.

System options are stored in $(prefix)/etc/gitconfig. When using command option --system to write, write to system-wide config file rather than the repository config. When using command option --system to read, read only from the system-wide file rather than from all available files.

References