Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Git config: Aliases, rerere, and Credential Helpers

Five config scopes decide one value at a time. Aliases are user-level shorthand, rerere records conflict resolutions, and credential helpers choose where your secret lives.

~4 min readGit
#Git#Configuration#Aliases#Credentials
3D illustration of a gear panel with shortcut chips wired into a keyring held by a locker

Quick Summary

git config is layered: system, global, local, worktree, and command line, with the last one to define a key winning. The same key can therefore have five values at once, and git config --list --show-origin --show-scope is the only reliable way to see which file actually decided the value in effect.

Aliases turn that layer into a personal shorthand — alias.st "status -sb", and ! aliases for shell one-liners. Because they are just config, they do not travel with the repository; a shared includeIf block is how a team standardises them without writing into every clone.

rerere (reuse recorded resolution) records how you resolved a conflict and replays it when the same conflict appears again, which is what makes a long rebase or a repeated merge tolerable. Credential helpers are the third piece of the same file: they decide whether Git asks for a password once per push, once per hour, or never — and where that secret is stored.

Basic Syntax and Core Signatures

bash
# Scopes and inspection git config --list --show-origin --show-scope # key, file, scope git config --get user.email git config --get-regexp '^alias\.' git config --global --edit # opens ~/.gitconfig # Writing with types git config --global core.editor "code --wait" git config --global --type=bool pull.ff only # --type validates the value git config --global --add include.path ~/.gitconfig-work git config --global --unset alias.st git config --local --fixed-value rerere.enabled true # Aliases: git subcommands and shell git config --global alias.st "status -sb" git config --global alias.lg "log --graph --oneline --decorate --all" git config --global alias.root "rev-parse --show-toplevel" git config --global alias.undo '!f() { git reset --hard HEAD@{1}; }; f' # Configuration that follows the repository git config --global core.sshCommand "ssh -i ~/.ssh/id_work" # Rerere git config --global rerere.enabled true git config --global rerere.autoUpdate true git rerere status git rerere diff git rerere forget path/to/file
ini
# ~/.gitconfig [user] name = Ryu email = dev@example.com [include] path = ~/.gitconfig-aliases [includeIf "gitdir:~/work/"] path = ~/.gitconfig-work [url "git@github.com:"] insteadOf = https://github.com/ [credential] helper = manager [credential "https://git.corp.example"] helper = store
bash
# Credential helpers, per host git config --global credential.helper cache # 15 min, memory git config --global credential.helper 'cache --timeout=3600' git config --global credential.helper store # plaintext file git config --global credential.helper osxkeychain # macOS git config --global credential.helper libsecret # Linux keyring git config --global credential.https://github.com.helper manager

Key Comparison Table

ScopeFileApplies toOverrides
--system/etc/gitconfigEvery user on the machineNothing
--global~/.gitconfig, $XDG_CONFIG_HOME/git/configEvery repository of this userSystem
--local.git/configOne repositoryGlobal
--worktree.git/worktrees/<id>/config.worktreeOne worktreeLocal
-c key=valueNowhere (one process)One commandEverything
Credential helperStoragePersistenceNotes
cacheMemory--timeout seconds, default 900No disk write, lost on reboot
store~/.git-credentials, plaintextUntil deletedMode 600 only; avoid on shared machines
osxkeychain / managerOS keychainUntil removedBest default on macOS and Windows
libsecretSecret ServiceUntil removedNeeds a running keyring
nonePrompt each timeSession onlyUse GIT_TERMINAL_PROMPT=0 in CI

Practical Edge Cases and Deep Dives

1. Conditional includes for work and personal repositories

ini
[includeIf "gitdir:~/work/"] path = ~/.gitconfig-work [includeIf "gitdir/i:~/Clients/"] path = ~/.gitconfig-clients [includeIf "onbranch:release/"] path = ~/.gitconfig-release

gitdir: matches the location of the repository, gitdir/i: ignores case, and a path ending in / matches that directory and everything below it. Values from an included file override the ones before it in the parent file, so the work email replaces the personal one for repositories under ~/work/. This is the practical way to stop committing with a personal address to a company repository without remembering -c user.email on every command.

2. Aliases that do not behave like subcommands

bash
git config --global alias.root "rev-parse --show-toplevel" # runs as a subcommand git config --global alias.root '!pwd' # runs as a shell command git root # prints the top level

A ! alias runs in a shell at the top level of the repository (or the current directory outside one), with GIT_PREFIX holding the subdirectory you were in. That is why alias.ll '!ls' lists the repo root rather than your current directory. An alias may not shadow a built-in command — alias.commit is ignored with a warning — and an alias cannot take positional arguments other than by appending: git lg -5 works because the arguments are appended, while a shell alias needs a function form ('!f() { …; }; f') to place them.

3. rerere: turning a repeated conflict into a one-time decision

bash
git config --global rerere.enabled true git rebase main # CONFLICT (content): Merge conflict in src/parser.ts # Resolved 'src/parser.ts' using previous resolution. <- second time

rerere stores pre- and post-images keyed by the conflict itself, so the same textual conflict resolves itself on the next rebase, merge, or cherry-pick. rerere.autoUpdate stages the recorded resolution so it is included in the commit. Three practical points: it only helps when the conflict is genuinely identical, it works per-repository (the recordings live in .git/rr-cache), and git rerere forget <path> is the escape when the recorded resolution is wrong — otherwise it will confidently reapply a bad fix.

4. Why the credential helper keeps asking

bash
git config --list --show-origin | grep credential # file:~/.gitconfig credential.helper=manager # file:.git/config credential.helper=store GIT_TRACE=1 GIT_CURL_VERBOSE=1 git fetch # 17:31:02.917 ... run_command: run-command.c:657 trace: run_command: 'git-credential-store get'

Multiple helpers form a list that is asked in order, and an empty value resets the list: helper = manager, then helper = (empty), then helper = store leaves only store. A repository-local helper silently overrides a global one, which is the usual cause of a credential prompt returning after the keychain was configured. git credential fill with a prepared input block shows exactly which helper answered.

5. URL rewriting, and the trap of two insteadOf rules

bash
git config --global url."git@github.com:".insteadOf "https://github.com/" git config --global url."https://github.com/".insteadOf "git@github.com:"

The second rule does not just rewrite your pushes back to HTTPS; it rewrites the rewritten URL, so every operation bounces between the two forms. insteadOf matches prefixes, and the longest matching prefix wins, so a narrower rule (url."ssh://git@github.com:2222/".insteadOf "https://github.com/") beats a broader one. CI systems use this to swap HTTPS for SSH with a deploy key — but the rule is global, so a machine that also needs HTTPS for a public mirror should scope it with includeIf.

6. Checking configuration that a script depends on

bash
git config --type=bool --get pull.rebase || echo "unset" git config --type=int --get gc.auto git config --get-all credential.helper git -c core.pager=cat -c color.ui=false log -1

--type is worth adding to any script that reads config: it rejects yes where a number is expected instead of silently treating the key as unset, and it normalises booleans (true, yes, on, 1) to a single value. git -c applies a setting to one invocation without writing anything, which is how a build script should force -c protocol.version=2 or disable a pager rather than mutating the user's config.

Common Git Operation Mistakes

SymptomCauseFix
Setting has no effectDefined in a higher-precedence scopegit config --list --show-origin
Alias not found after cloningAliases are user config, not repository dataRecreate, or commit an include file
alias.commit ignoredBuilt-in commands cannot be aliasedUse a different name
Credential prompt every pushHelper absent, or reset by an empty valueCheck --get-all credential.helper
Token stored in plaintext unexpectedlycredential.helper store in a lower-precedence fileSwitch to the OS keychain, delete ~/.git-credentials
Wrong author email on a commitConditional include not matchinggit config --show-origin user.email
rerere reapplies a bad resolutionRecorded conflict reusedgit rerere forget <path>
insteadOf loops between two URLsTwo rules rewriting each otherDelete one, use GIT_TRACE to confirm
Script reads yes as a numberNo --type givengit config --type=int --get <key>

Try matching browser tools

All tools

Small utilities that fit Git work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Git guides

More in Git

All Git guides

The guides filed next to this one in Git, in library order.