Synopsis

git config [--global | --system | --local] <key> [<value>]
git config --list
git config --edit

Description

The git config command reads and writes Git configuration. Settings live in three layers: system-wide (/etc/gitconfig), per-user (~/.gitconfig or ~/.config/git/config), and per-repository (.git/config). More specific layers override more general ones. Many Git behaviors — default editor, push behavior, merge tools, line-ending handling — are tuned via config.

For new users, the essentials are user.name, user.email, init.defaultBranch, and core.editor. Power users build extensive aliases, customize colors, and use conditional includes to apply different settings per project directory.

In day-to-day use, git config integrates closely with shell aliases, editor plugins, and continuous integration. Power users often add aliases that combine flags they always pass, or wrap the command in scripts that enforce team conventions. Output formatting can be customized via Git config — pretty formats, color schemes, and pager behavior are all tunable. When something goes wrong, the first diagnostic step is usually to re-run the command with GIT_TRACE=1 in the environment, which reveals the underlying plumbing calls. For unusual situations, the --help output (git config --help) opens the full manual page with details on every option, including those rarely used in casual workflows but essential for debugging or scripting at scale.

Understanding how git config interacts with the rest of Git's data model — the object database, the index, refs, and the working tree — pays dividends. Each command operates on some subset of these pieces, and knowing which it touches helps predict outcomes and recover from mistakes. Reading the official Git documentation alongside hands-on practice in a throwaway repository is the fastest way to internalize the nuances. Most production issues with Git stem from one of three causes: surprising default behavior, partial network operations, or rewriting history that was already shared. A working mental model of git config's side effects helps avoid all three.

Common Options

Examples

git config --global user.name "Jane Smith"
git config --global user.email "[email protected]"
# Identity for every repo

git config --global init.defaultBranch main
git config --global pull.rebase true
git config --global core.editor "code --wait"
# Sensible modern defaults

git config --global alias.lg "log --oneline --graph --decorate --all"
# Custom alias

git config --list --show-origin
# Audit where each setting comes from

Common Mistakes

Setting global config that's meant to be local (or vice versa) leads to confusing behavior. Forgetting to set user.email on a fresh machine causes every commit to be unattributed. Use conditional includes ([includeIf "gitdir:~/work/"]) to swap identities per directory.

Related Commands

git credential, git init, git remote