Appearance
Git Config for Daily Development
Git's behavior is controlled by configuration. The defaults work for basic use, but a few settings make daily development faster, safer, and less annoying. This guide covers the configuration every developer should set, useful aliases, and how to manage different identities across projects.
Where config lives
Git loads settings from four scopes, in order:
| Scope | File | Sets with |
|---|---|---|
| System | /etc/gitconfig | git config --system |
| Global | ~/.gitconfig or ~/.config/git/config | git config --global |
| Local | .git/config | git config (no flag) |
| Worktree | .git/worktrees/<name>/config.worktree | git config --worktree |
Values in a higher-precedence scope override lower ones. Local overrides global, command-line -c overrides everything.
bash
# See what is set and where it came from
git config --list --show-origin --show-scope
# Query a single value
git config user.email
# List all values for a key across scopes
git config --get-all --show-origin user.nameEssential settings
Your identity
Set these globally, then override per repo when needed:
bash
git config --global user.name "Jane Doe"
git config --global user.email "jane@example.com"For a work repo with a different email:
bash
cd ~/projects/work-repo
git config user.email "jane.doe@company.com"Git stamps every commit with author and committer name/email. Forgetting to set these produces a warning on first commit and defaults to your system username and hostname, which is rarely what you want.
Default branch name
bash
git config --global init.defaultBranch mainWithout this, git init creates a branch called master. Setting it to main is a small courtesy that avoids the "why is it called master?" conversation and matches modern hosting platforms.
Editor
bash
git config --global core.editor nano
# Or for VS Code users:
git config --global core.editor "code --wait"Git opens your editor for commit messages, interactive rebase, and conflict resolution. --wait tells VS Code to block until you close the file. Without it, Git thinks you finished immediately.
Line endings
bash
git config --global core.autocrlf inputOn macOS and Linux, input tells Git to convert CRLF to LF on commit but leave files alone on checkout. On Windows, set true to convert to CRLF on checkout and back to LF on commit. Pair this with a .gitattributes file at the repo root for explicit per-file control:
text
# .gitattributes
* text=auto
*.sh text eol=lf
*.bat text eol=crlf
*.png binaryPull behavior
bash
git config --global pull.rebase trueThis makes git pull rebase your local commits on top of the fetched changes instead of creating a merge commit. The result is a linear history. If you prefer merge commits on pull (or want to decide per operation), leave this unset and use git pull --rebase manually.
Diff and merge tools
bash
git config --global diff.tool vimdiff
git config --global merge.tool vimdiff
git config --global merge.conflictstyle zdiff3zdiff3 adds the common ancestor section to conflict markers. Seeing what both sides started from makes conflicts much easier to resolve. Set it. You will thank yourself the first time you hit a 50-line merge conflict.
Safety nets
bash
# Prevent accidental pushes to shared branches
git config --global push.default current
# Keep reflog entries longer (default 90 days)
git config --global gc.reflogExpire 180.days
# Auto-set up remote tracking
git config --global branch.autoSetupMerge truepush.default current means git push without arguments pushes the current branch to a remote branch of the same name. Without it, the old default pushed all matching branches, which could push branches you did not intend to share.
Aliases: save one keystroke at a time
Aliases let you define shortcuts for long commands. They live in [alias] section of your config.
ini
[alias]
st = status -s
co = checkout
br = branch
ci = commit
cia = commit --amend
lg = log --oneline --graph --decorate --all
lgs = log --oneline --graph --decorate --all --simplify-by-decoration
unstage = reset HEAD --
undo = reset --soft HEAD~1
last = log -1 --stat
who = shortlog -sne
pending = !git log --oneline --branches --not --remotesAdd them with:
bash
git config --global alias.st "status -s"
git config --global alias.lg "log --oneline --graph --decorate --all"A few to consider:
| Alias | Expansion | What it does |
|---|---|---|
st | status -s | Short status output |
lg | log --oneline --graph --decorate --all | Full commit graph |
cia | commit --amend | Amend the last commit |
unstage | reset HEAD -- | Unstage a file |
undo | reset --soft HEAD~1 | Undo the last commit but keep changes |
pending | !git log --oneline --branches --not --remotes | Show unpushed commits |
The ! prefix in pending tells Git to run the rest as a shell command. Use it for aliases that pipe or combine multiple Git commands.
Per-repo identity with conditional includes
When you work on personal and corporate projects on the same machine, use conditional includes to switch identities automatically.
ini
# ~/.gitconfig
[includeIf "gitdir:~/work/"]
path = ~/.gitconfig-work
[includeIf "gitdir:~/opensource/"]
path = ~/.gitconfig-ossThen create ~/.gitconfig-work:
ini
[user]
name = Jane Doe
email = jane.doe@company.com
[core]
sshCommand = ssh -i ~/.ssh/id_ed25519_workAnd ~/.gitconfig-oss:
ini
[user]
name = jane-dev
email = jane@example.comAny repo under ~/work/ uses the work identity and SSH key. Repos under ~/opensource/ use your personal identity. Everything else falls through to the global defaults.
Config that travels with the repo
Some settings belong in the repo, not your global config. These go in .git/config (set without --global):
bash
# Per-repo insteadOf to rewrite remote URLs
git config url."https://github.com/".insteadOf "gh:"
# Now you can clone with: git clone gh:user/repo.gitBut some things belong in a file that is checked into the repo and shared with the team:
bash
git config --local core.hooksPath .githooksThis points Git at a version-controlled hooks directory. Add it to your project's setup docs so every contributor gets the same hooks.
When to change each scope
| You want to... | Use | Example |
|---|---|---|
| Set your name globally | --global | git config --global user.name "Jane" |
| Override email for one repo | (no flag) | git config user.email "jane@corp.com" |
| Set a team-wide default | --system | git config --system core.hooksPath /etc/git-hooks |
| Try something once | -c flag | git -c core.pager=cat log |
| Switch identity by directory | includeIf in global config | See conditional includes above |
Pitfalls
| Mistake | What happens | How to fix |
|---|---|---|
--global in a CI script | The runner's global config affects all repos on that machine. | Use -c flags or local config. |
user.email not set | Git uses username@hostname. | Set it globally on every new machine. |
core.autocrlf mismatch across the team | Every pull shows whitespace diffs. | Agree on a setting and add .gitattributes. |
Forgetting --wait with VS Code as editor | Git thinks you closed the file immediately. | Run git config --global core.editor "code --wait". |
| Aliases shadowing Git commands | git stash works, git st does something else. | Check existing commands before naming aliases. |
Setting pull.rebase without understanding it | Merge commits disappear from your history. | Read Rebase vs Merge. |
Key commands reference
| Command | What it does |
|---|---|
git config --list | Show all config |
git config --list --show-origin | Show config with file locations |
git config user.name | Query a single value |
git config --global alias.lg "log --oneline" | Create an alias |
git config --global --unset user.email | Remove a setting |
git config -c core.pager=cat log | Override a setting for one command |
Related guides
- Conditional Config & Includes — advanced includeIf patterns
- Credential Helpers & Tokens — managing authentication
- Git Switch & Restore — modern alternatives to checkout