git config

Layered config: system, global, local, worktree. Learn the layers.

🎯 What & why

git config reads and writes the key/value store that controls every knob in Git, from your name on commits to whether pull rebases. It is the single source of truth for Git's behavior; learn the layers or be confused forever.

🧠 Mental model

Pure text files. Nothing in the working tree, index, objects, or refs is touched. Config lives in plain INI-style files at four scopes (system, global, local, worktree) and is merged with later scopes overriding earlier ones at lookup time.

🛠️ Synopsis

git config [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] name [value [value-pattern]]
git config [<file-option>] [--type=<type>] --add name value
git config [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] --get name [value-pattern]
git config [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] --get-all name [value-pattern]
git config [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] --get-regexp name_regex [value-pattern]
git config [<file-option>] --unset name [value-pattern]
git config [<file-option>] --unset-all name [value-pattern]
git config [<file-option>] --rename-section old_name new_name
git config [<file-option>] --remove-section name
git config [<file-option>] [--show-origin] [--show-scope] [-z|--null] -l | --list
git config [<file-option>] --get-color name [default]
git config [<file-option>] --get-colorbool name [stdout-is-tty]
git config [<file-option>] -e | --edit

🎚️ Switches & options

Flag	What it does
`--system`	Edit `/etc/gitconfig`. Affects every user on the box.
`--global`	Edit `~/.gitconfig` (or `~/.config/git/config`). Per-user, normal default for personal settings.
`--local`	Edit `.git/config`. Per-repo, default if you give no scope flag inside a repo.
`--worktree`	Edit per-worktree config. Requires `extensions.worktreeConfig=true`.
`--add`	Append a new line for a multi-value key instead of replacing it.
`--replace-all`	⚠️ Force a single value for a key that has multiple lines. Will silently nuke the others.
`--get-regexp`	Dump all keys matching a regex. The right tool for finding what's set.

📦 Subcommands

--get <key> — Print the value of <key> (highest-precedence layer wins).

$ git config --get user.email

--set <key> <value> — Implicit form (git config <key> <value>); writes to local scope by default.

$ git config user.email you@example.com

--unset <key> — Remove a single value of <key>.

$ git config --unset user.email

--add <key> <value> — Append another value (for multi-valued keys like remote.<name>.url).

$ git config --add remote.origin.url git@mirror:proj.git

--list [--show-scope] [--show-origin] — Dump all settings; with --show-origin shows which file each came from.

$ git config --list --show-origin

--get-regexp <pattern> — Find all keys matching <pattern>.

$ git config --get-regexp '^alias\.'

--edit — Open the chosen scope's config in $EDITOR.

$ git config --global --edit

--remove-section <section> — Drop a whole [section] block.

$ git config --remove-section alias

💡 Use cases

Set your identity on a fresh machine before the first commit gets blamed on root@hostname.
Define per-repo identity for a work repo while keeping personal email globally.
Audit which scope set a confusing value with --show-origin and --show-scope.
Wire a conditional include so any repo under ~/work/ uses your work email automatically.

🧪 Examples

Set identity globally

$ git config --global user.name "Linus T."
$ git config --global user.email "torvalds@example.org"
$ git config --global init.defaultBranch main
$ git config --global pull.rebase true

Find where a value comes from

$ git config --show-origin --show-scope --get user.email
# global  file:/home/you/.gitconfig    you@personal.tld
$ git config --show-origin --get-all remote.origin.fetch

Conditional include for work repos

# in ~/.gitconfig
[includeIf "gitdir:~/work/"]
    path = ~/.gitconfig-work
# then ~/.gitconfig-work
[user]
    email = you@bigcorp.com

Define an alias

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

🎓 Recommendations

Set user.name, user.email, init.defaultBranch, pull.rebase, and push.default=simple once globally and forget about them.
Use --show-origin --show-scope whenever a setting behaves weirdly. Guessing the scope wastes hours.
Use includeIf for multi-identity setups. Do not script cd hooks to swap identities.

🪤 Common pitfalls

Editing the wrong scope: running git config foo.bar baz inside a repo writes to .git/config, not your global. Be explicit.
Storing secrets (tokens, passwords) in config. They sit in plaintext and end up in backups. Use a credential helper.
Multi-value keys (remote..fetch, http.) silently break when you use plain --set. Use --add, --get-all, --unset-all, or --replace-all deliberately.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.