Introduction

Before your first commit, Git needs to know who you are. git config stores key-value pairs in three scopes: system (all users), global (your user account), and local (a single repository). The global scope lives at ~/.gitconfig on Unix and %USERPROFILE%\.gitconfig on Windows.

Identity

Set your name and email; these are baked into every commit you make:

git config --global user.name "Ada Lovelace"
git config --global user.email "[email protected]"

Editor and pager

Git launches your editor for commit messages and interactive rebases. Pick one you can quit:

git config --global core.editor "nano"
# or
git config --global core.editor "code --wait"
# or
git config --global core.editor "vim"

Default branch name

Since Git 2.28 you can set the default branch for new repositories:

git config --global init.defaultBranch main

Line endings

To prevent CRLF/LF surprises in cross-platform teams:

# Linux, macOS
git config --global core.autocrlf input

# Windows
git config --global core.autocrlf true

Useful aliases

git config --global alias.st status
git config --global alias.co checkout
git config --global alias.lg "log --oneline --graph --decorate --all"

Now git lg gives a compact graph of all branches.

Inspecting configuration

List all config with origin files, useful for debugging surprises:

git config --list --show-origin
git config --get user.email

Pull behaviour

Since Git 2.27 the default pull behaviour requires an explicit choice. Pick one:

git config --global pull.rebase false   # merge (default)
git config --global pull.rebase true    # rebase
git config --global pull.ff only        # fast-forward only

Conditional includes

Git supports per-directory configuration via includeIf. This is the cleanest way to keep work and personal identities separate without remembering to set local config in each clone:

# in ~/.gitconfig
[includeIf "gitdir:~/work/"]
  path = ~/.gitconfig-work

# in ~/.gitconfig-work
[user]
  email = [email protected]
  signingkey = ssh-ed25519 AAAA...

Any repo cloned under ~/work/ automatically picks up the work identity. Combine with onbranch: includes to scope settings to specific branches.

Per-repo overrides

Local configuration in .git/config overrides the global file. This is the right place for project-specific identities, hooks, and signing keys. To audit which scope a setting comes from:

git config --show-origin --get user.email
git config --show-scope --get-all credential.helper

If a value seems wrong, --show-origin tells you exactly which file owns it. Beware: any of system, global, local, or even worktree scope can shadow another. git config --list --show-origin dumps the full picture in one shot.

Common mistakes

Setting user.email to a personal address while committing for work, leaking that on public hosting platforms. Use the local scope inside work repositories to override the global value: git config user.email "[email protected]". Another classic: editing ~/.gitconfig by hand and introducing a syntax error that breaks every Git command. Use git config to write values, and git config --list to verify after each change.