git config

What is git config

The git config command is a command-line utility for reading and writing Git's configuration variables — the settings that control how Git looks and behaves. These variables define your identity (name and email), your preferred text editor, output colors, command shortcuts (aliases), and dozens of other behaviors.

This page covers the configuration levels and their files, how to read and write values, setting your editor and colors, creating aliases, and tuning whitespace handling. Setting user.name and user.email with git config is usually the very first thing you do after installing Git.

The git config levels and files

The git config command accepts arguments to specify on which configuration level to operate. When looking for a configuration value, Git prioritizes the following order (from lowest to highest priority):

1. --system – The system-level configuration includes all users on an operating system and all repositories. The system-level configuration file is located in the Git installation directory.

git config system level

(prefix)/etc/gitconfig - on Unix systems
C:\Documents and Settings\All Users\Application Data\Git\config - Windows XP (deprecated)
C:\ProgramData\Git\config - Windows Vista and newer versions

2. --global – The global-level configuration applies to the current operating system user. Global configuration values are stored in a file in the user's home directory.

git config global level

~/.gitconfig - on Unix systems
C:\Users\<username>\.gitconfig - on Windows

3. --local – When no configuration option is passed, git config writes to the local level by default. The repository's .git directory contains a file that stores local configuration values.

git config local level

.git/config

Note: Local settings override global settings, which in turn override system settings. So a user.email set inside one repository (local) wins over the global value, letting you use a work address in one project and a personal address in another.

How to write a value

To write a value, pass the configuration name followed by the value. The example below writes [email protected] to user.email. The --global flag sets the value for the current operating system user, so it applies to every repository you work in:

git config set user

git config --global user.email "[email protected]"

A typical first-time setup writes both your name and email:

git config --global user.name "Jane Doe"
git config --global user.email "[email protected]"

These two values are stamped onto every commit you create, so set them before your first commit.

How to read a value

The basic use of git config is to retrieve a configuration value by specifying its name. Configuration names consist of a section and a key separated by a dot:

git config user email

git config user.email

Here, email is a child property of the user section. Running this prints the active value — the one that wins after the local → global → system override chain is applied.

Useful inspection commands

Beyond reading a single key, these commands help you see and manage everything Git has configured:

When two levels define the same key, --show-origin is the quickest way to find out which file is responsible for the value Git actually uses.

The git config editor - core.editor

When your identity is set up, Git uses your system’s default editor, which is Vi or Vim. The git config sets up which editor Git will use. Here is the list of most common editors with git config commands:

Colored outputs

Git supports colors thus simplifying the process of reading Git output. You can use your colors for customizing the output. For setting color values git config command is used.

color.ui

Git automatically colors most of its output, but there is also a master variable if you want to set another color. For disabling all Git's colored terminal output you can do the following:

git config set color.ui

git config --global color.ui false

The default setting of color.ui is auto which applies colors directly to the terminal output. It omits color code output when the output is redirected to a pipe or a file.

You can also set the color.ui value to always. It applies color code output when the output is redirected to files or pipes. This can cause problems as the receiving pipe may not be expecting color-coded input.

Git color values

Besides color.ui, there are also other color settings that can be set to false, auto, or always. They can have a specific color value: normal, black, red, green, yellow, blue, magenta, cyan, white. Colors can be specified as hexadecimal color codes like #1c87c9 or ANSI 256 color values if the terminal supports it.

Git color configuration settings

The git config aliases

Aliases are custom shortcuts that expand to longer or combined commands, so you don't have to retype frequently used commands in full. Git's alias system is most often used to shorten common commands. You create aliases with git config:

git config set alias

git config --global alias.ci commit

After this, git ci runs git commit. Because the value contains a space, an alias that maps to a command with flags must be quoted as a single argument:

git config aliases

git config --global alias.amend "commit --amend"

Here, running git amend expands to git commit --amend. An alias can also call out to a shell command by prefixing the value with !, for example git config --global alias.unstage '!git restore --staged'. For a deeper dive, see the dedicated git alias chapter.

Formatting & whitespace

Other common settings

A few configuration values are worth setting on a new machine:

# Name the default branch "main" for every repository you create
git config --global init.defaultBranch main

# Reuse cached credentials so you are not prompted on every push
git config --global credential.helper cache

# Choose how git pull reconciles divergent branches (merge, not rebase)
git config --global pull.rebase false

The init.defaultBranch value is applied by git init when a repository is created. To control which files Git tracks at all, pair your config with a .gitignore file.

Practice