Configuring Git

By Maxime Bréhin • Published on 27 March 2023 • 4 min

Knowing how to configure Git is great! You can customize behaviors, create custom aliases, setup your favorite tools to work with Git, and customize even the colors of Git commands in the console. But configuring Git is also a constraint:

• Git default behavior is not optimized,
• you must create configuration files,
• you have to replicate that configuration on all computers that need to work with Git,
• and you’re seldom aware of the things that can or must be configured.

Basically, it could be better…

Unfortunately, Git is not at its best right out of the box! Some behaviors have to be optimized like the rebase mode for the pull command (rebase = merges, to be precise). You shouldn’t even be worrying about this and yet here you are, having to specify all that in the Git configuration.

There is a reason for that: new Git releases should not change its existing behavior. You shouldn’t see any difference in Git behavior following an update. This approach is rather questionable, but unless you take over the management of Git releases (which might be feasible, as it’s an open-source project), it’s not likely to change anytime soon.

So how can you fix that? It’s quite simple: you can attend our 360° Git training 😁! If you’re not that lucky, then you’ll have to read the docs follow our recommendations. Being the nice folks we are 🤗, we commented each configuration line, so that you have at least some idea of what it’s all about.

Syntactically, it looks like an .ini or TOML file. You have a block with a header defined with square brackets, followed by lines in the key = value format.

[user]
  name = Max Krieger
  email = max.krieger@git.demo

Sometimes you will need to create named blocks to tweak features behaviors for specific commands (sometimes called drivers). Here is an example that customizes status command colors:

[color "status"]
  # Print untracked file names in black on yellow background
  untracked = black yellow
  # Print conflicting files in magenta and italics
  unmerged = magenta italic

Where do I put all this?

There are several options, but the simplest and most effective one is to set the configuration globally for your user account. This will be used for all your projects on your computer. You’ll usually find a .gitconfig file in your home directory (if not, you can create one). If you’re not sure, you can access it from a commandl ine by typing git config --global --edit (be careful, it may open it in vim by default). Some graphical editors also let you edit this configuration, often within their own user interface.

If you are on Windows, be careful if user accounts are stored on a server: if the network goes down, your Git configuration will not be loaded anymore (it is read at each Git command execution). You won’t necessarily notice this because Git won’t report any errors. One solution would then be to change its location by changing the XDG_CONFIG_HOME environment variable.

You can also specify the “local” configuration, as close to the project as possible. This is the .git/config file of your project (yes, it’s not the same name 🤦). It’s useful for clarifying or overwriting the main configuration. For example, when I work on open-source projects, I use my personal email address rather than the professional one (see example farther below). That local configuration also contains the definitions of remote repositories, branches, etc. which are obviously distinct from one project to the next.

How do I set up my configuration?

Aside from copying and pasting our configuration template, you may want to change some things. You can either edit the file by hand, or do it via the command line.

Don’t be afraid of editing a configuration file by hand since Git’s parser will tell you where you have an error.

If you prefer a safer way, you can use the command line following the pattern:

git config --global block-name.key value
# Here is an example: use VSCode as the default editor
# git config --global core.editor 'code --wait'

If you remove the --global flag, it will change the local configuration.

git config user.email my-email@tld.domain

How does Git load my configuration?

The configuration files are read at each Git command. First at the global level, then at the local / project level. The global configuration is then augmented or overwritten by the local definitions.

Finally, depending on what you want to do, you can usually override some options directly from the command line.

# Our custom configuration disables "fast-forward"
# merges (`merge.ff` à `false`). We can override that
# behavior with the merge `ff` option
git merge --ff sub-feature

In summary: the closest configuration to the command wins!

How about sharing?

If you use Git already, you may be familiar with the .gitignore file that you can put at your project’s root to share it. You might naively think that you can do the same with the configuration and create a .gitconfig file in the same location… Except you can’t! Do you really think it would have been that easy?

Basically, configuration is not shared. You could use a few tricks, for example by specifying in your local configuration a path to a third party configuration file.

# ❌ Don't do that, it's useless
git config include.path <path-to-custom-config>

But we’re back to square one: we have to go through the configuration to specify… the path to the configuration (except that here we have to do it on every computer and for every project). It sucks, but we have no choice but to replicate our confs.

It’s no that big a deal tho. We do it once and for all when we setup our computer. And if there’s ever any relevant news, just ask us, we’ll be sure to write an article and produce an episode to explain it all!

More tips and tricks?

We’ve got a whole bunch of existing articles and more to come.