In this document, we'll take an in-depth look at the
git config command. We briefly discussed
git config usage on our Setting up a Repository page. The
git config command is a convenience function that is used to set Git configuration values on a global or local project level. These configuration levels correspond to
.gitconfig text files. Executing
git config will modify a configuration text file. We'll be covering common configuration settings like email, username, and editor. We'll discuss Git aliases, which allow you to create shortcuts for frequently used Git operations. Becoming familiar with
git config and the various Git configuration settings will help you create a powerful, customized Git workflow.
The most basic use case for
git config is to invoke it with a configuration name, which will display the set value at that name. Configuration names are dot delimited strings composed of a 'section' and a 'key' based on their hierarchy. For example:
git config user.email
In this example, email is a child property of the user configuration block. This will return the configured email address, if any, that Git will associate with locally created commits.
git config levels and files
Before we further discuss
git config usage, let's take a moment to cover configuration levels. The
git config command can accept arguments to specify which configuration level to operate on. The following configuration levels are available:
git config will write to a local level if no configuration option is passed. Local level configuration is applied to the context repository
git config gets invoked in. Local configuration values are stored in a file that can be found in the repo's .git directory:
Global level configuration is user-specific, meaning it is applied to an operating system user. Global configuration values are stored in a file that is located in a user's home directory.
~ /.gitconfig on unix systems and
C:\Users\ on windows
System-level configuration is applied across an entire machine. This covers all users on an operating system and all repos. The system level configuration file lives in a
gitconfig file off the system root path.
$(prefix)/etc/gitconfig on unix systems. On windows this file can be found at
C:\Documents and Settings\All Users\Application Data\Git\config on Windows XP, and in
C:\ProgramData\Git\config on Windows Vista and newer.
Thus the order of priority for configuration levels is: local, global, system. This means when looking for a configuration value, Git will start at the local level and bubble up to the system level.
Writing a value
Expanding on what we already know about
git config, let's look at an example in which we write a value:
git config --global user.email "email@example.com"
This example writes the value
firstname.lastname@example.org to the configuration name
user.email. It uses the
--global flag so this value is set for the current operating system user.
git config editor - core.editor
Many Git commands will launch a text editor to prompt for further input. One of the most common use cases for
git config is configuring which editor Git should use. Listed below is a table of popular editors and matching
git config commands:
|Sublime Text (Mac)|| |
|Sublime Text (Win, 32-bit install)|| |
|Sublime Text (Win, 64-bit install)|| |
In the event of a merge conflict, Git will launch a "merge tool." By default, Git uses an internal implementation of the common Unix diff program. The internal Git diff is a minimal merge conflict viewer. There are many external third party merge conflict resolutions that can be used instead. For an overview of various merge tools and configuration, see our guide on tips and tools to resolve conflits with Git.
git config --global merge.tool kdiff3
Git supports colored terminal output which helps with rapidly reading Git output. You can customize your Git output to use a personalized color theme. The
git config command is used to set these color values.
This is the master variable for Git colors. Setting it to false will disable all Git's colored terminal output.
$ git config --global color.ui false
color.ui is set to auto which will apply colors to the immediate terminal output stream. The auto setting will omit color code output if the output stream is redirected to a file or piped to another process.
You can set the
color.ui value to always which will also apply color code output when redirecting the output stream to files or pipes. This can unintentionally cause problems since the receiving pipe may not be expecting color-coded input.
Git color values
In addition to
color.ui, there are many other granular color settings. Like
color.ui, these color settings can all be set to false, auto, or always. These color settings can also have a specific color value set. Some examples of supported color values are:
Colors may also be specified as hexadecimal color codes like #ff0000, or ANSI 256 color values if your terminal supports it.
Git color configuration settings
- Configures the output color of the Git branch command
- This value is also applicable to Git branch output. <
slot> is one of the following:
- 1. current: the current branch
- 2. local: a local branch
- 3. remote: a remote branch ref in refs/remotes
- 4. upstream: an upstream tracking branch
- 5. plain: any other ref
- Applies colors to
git log, and
- Configuring a <
slot> value under
color.difftells git which part of the patch to use a specific color on.
- 1. context: The context text of the diff. Git context is the lines of text content shown in a diff or patch that highlights changes.
- 2. plain: a synonym for context
- 3. meta: applies color to the meta information of the diff
- 4. frag: applies color to the "hunk header" or "function in hunk header"
- 5. old: applies a color to the removed lines in the diff
- 6. new: colors the added lines of the diff
- 7. commit: colors commit headers within the diff
- 8. whitespace: sets a color for any whitespace errors in a diff
- Customize the color for
git log --decorateoutput. The supported <
slot> values are:
HEAD. They are respectively applicable to local branches, remote-tracking branches, tags, stashed changes and
- Applies color to the output of git grep.
- Also applicable to git grep. The <
slot> variable specifies which part of the grep output to apply color.
- 1. context: non-matching text in context lines
- 2. filename: filename prefix
- 3. function: function name lines
- 4. linenumber: line number prefix
- 5. match: matching text
- 6. matchContext: matching text in context lines
- 7. matchSelected: matching text in selected lines
- 8. selected: non-matching text in selected lines
- 9. separator: separators between fields on a line (:, -, and =) and between hunks (--)
- This variable applies color for interactive prompts and displays. Examples are
git add --interactiveand
git clean --interactive
- The <
slot> variable can be specified to target more specific "interactive output". The available <
slot> values are: prompt, header, help, error; and each act on the corresponding interactive output.
- Enables or disables colored output when the pager is in use
- Enables or disables color output for the git show branch command
- A boolean value that enables or disables color output for Git status
Used to specify custom color for specified git status elements. <
slot> supports the following values:
- 1. header
- Targets the header text of the status area
- 2. added or updated
- Both target files which are added but not committed
- Targets files that are modified but not added to the git index
- 4. untracked
- Targets files which are not tracked by Git
- 5. branch
- Applies color to the current branch
- 6. nobranch
- The color the "no branch" warning is shown in
- 7. unmerged
- Colors files which have unmerged changes
You may be familiar with the concept of aliases from your operating system command-line; if not, they're custom shortcuts that define which command will expand to longer or combined commands. Aliases save you the time and energy cost of typing frequently used commands. Git provides its own alias system. A common use case for Git aliases is shortening the commit command. Git aliases are stored in Git configuration files. This means you can use the
git config command to configure aliases.
git config --global alias.ci commit
This example creates a ci alias for the
git commit command. You can then invoke
git commit by executing
git ci. Aliases can also reference other aliases to create powerful combos.
git config --global alias.amend ci --amend
This example creates an alias amend which composes the ci alias into a new alias that uses
Formatting & whitespace
Git has several "whitespace" features that can be configured to highlight whitespace issues when using git diff. The whitespace issues will be highlighted using the configured color
The following features are enabled by default:
blank-at-eolhighlights orphan whitespaces at the line endings
space-before-tabhighlights a space character that appears before a tab character when indenting a line
blank-at-eofhighlights blank lines inserted at the end of a file
The following features are disabled by default
indent-with-non-tabhighlights a line that is indented with spaces instead of tabs
tab-in-indenthighlights an initial tab indent as an error
trailing-spaceis shorthand for both blank-at-eol and blank-at-eof
cr-at-eol highlightsa carriage-return at the line endings
tabwidth=defines how many character positions a tab occupies. The default value is 8. Allowed values are 1-63
In this article, we covered the use of the git
config command. We discussed how the command is a convince method for editing raw
git config files on the filesystem. We looked at basic read and write operations for configuration options. We took a look at common config patterns:
- How to configure the Git editor
- How to override configuration levels
- How to reset configuration defaults
- How to customize git colors
git config is a helper tool that provides a shortcut to editing raw
git config files on disk. We covered in depth personal customization options. Basic knowledge of git configuration options is a prerequisite for setting up a repository. See our guide there for a demonstration of the basics.