Skip to content

Git configuration cascading and conditional includes quick reference ​

Configuration hierarchy ​

ScopeLocationFlagPriority
Command-c key=valueN/A1 (Highest)
Worktree.git/worktrees/<name>/config.worktree--worktree2
Local.git/config--local3
Global~/.gitconfig--global4
System/etc/gitconfig--system5 (Lowest)

Conditional include directives (includeIf) ​

1. Match repository directory (gitdir) ​

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

[includeIf "gitdir:~/personal/"]
    path = ~/.gitconfig-personal
  • Use trailing slash ~/work/ to match all subdirectories.
  • Use gitdir/i:~/work/ on macOS and Windows to prevent case-sensitivity mismatches.

2. Match active branch (onbranch) ​

ini
# ~/.gitconfig
[includeIf "onbranch:main"]
    path = ~/.gitconfig-production

[includeIf "onbranch:release/*"]
    path = ~/.gitconfig-release

3. Match remote URL (hasconfig:remote.*.url) ​

ini
# ~/.gitconfig
[includeIf "hasconfig:remote.*.url:https://git.local.sneakysquid.xyz/**"]
    path = ~/.gitconfig-corp

Essential recipes ​

Multi-profile identity template ​

ini
# ~/.gitconfig-work
[user]
    name = Alex Mercer
    email = alex.mercer@enterprise.corp
    signingkey = ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIG...
[gpg]
    format = ssh
[commit]
    gpgsign = true
[core]
    sshCommand = ssh -i ~/.ssh/id_ed25519_work -o IdentitiesOnly=yes

URL rewrites (insteadOf) ​

bash
# Force SSH for all GitHub URLs
git config --global url."git@github.com:".insteadOf "https://github.com/"

# Redirect dependency clones to internal mirror
git config --global url."https://git.local.sneakysquid.xyz/mirror/".insteadOf "https://github.com/vendor/"

Containerized CI safe directory ​

bash
# Whitelist all directories in container
git config --global --add safe.directory "*"

# Whitelist workspace path
git config --global --add safe.directory "$CI_PROJECT_DIR"

Enable per-worktree configuration ​

bash
git config extensions.worktreeConfig true
git config --worktree user.email worktree-agent@corp.internal

Diagnostic commands ​

bash
# Show origin file and scope for all configuration values
git config --list --show-origin --show-scope

# Inspect origin of a specific key
git config --show-origin user.email

# Show all values set across scopes for a key
git config --get-all --show-origin user.name

Git Master — Git Reference for Every Skill Level