Conditional Includes

The Hook (The "Byte-Sized" Intro)

You've committed to the work repo with your personal email. Again. The PR shows your gaming handle instead of your professional name. includeIf fixes this permanently: repos under ~/work/ automatically use your work config. Repos under ~/personal/ use your personal config. No more mistakes, no manual switching.

📖 What are Conditional Includes?

includeIf directives in .gitconfig load additional config files based on conditions like the repository's directory path, enabling different identities and settings for different contexts.

Conceptual Clarity

includeIf conditions:

Condition	Syntax	Matches
Directory path	`gitdir:~/work/`	Repos inside `~/work/`
Directory (case-insensitive)	`gitdir/i:~/Work/`	Case-insensitive match
Remote URL	`hasconfig:remote..url:github.com*`	Repos with GitHub remotes

Typical setup:

~/.gitconfig          ← Global defaults
~/.gitconfig-work     ← Work overrides (loaded for ~/work/ repos)
~/.gitconfig-personal ← Personal overrides (loaded for ~/personal/ repos)

Real-Life Analogy

Conditional includes are like automatic profile switching. When you walk into the office, your phone switches to the work Wi-Fi, enables Do Not Disturb, and silences notifications. When you get home, it switches back. No manual action needed.

Visual Architecture

flowchart TD GLOBAL["~/.gitconfig<br/>Default identity"] --> CHECK{"Repo location?"} CHECK -->|"~/work/"| WORK["~/.gitconfig-work<br/>work@company.com"] CHECK -->|"~/personal/"| PERSONAL["~/.gitconfig-personal<br/>me@personal.com"] style GLOBAL fill:#0f3460,stroke:#53d8fb,color:#53d8fb style WORK fill:#1a1a2e,stroke:#ffd700,color:#ffd700 style PERSONAL fill:#1b2d1b,stroke:#53d8fb,color:#53d8fb

Why It Matters

Prevents identity mistakes: No more commits with the wrong email.
Automatic: No manual switching required — it's based on directory.
Flexible: Different GPG keys, different editors, different settings per context.
Clean: One global config with conditional overrides.

Code

bash

# ─── Step 1: Organize your repos ───
# ~/work/      ← Company repos
# ~/personal/  ← Personal repos

# ─── Step 2: Create context-specific configs ───
cat > ~/.gitconfig-work << 'EOF'
[user]
    name = Jane Doe
    email = jane.doe@company.com
    signingkey = WORK_GPG_KEY
EOF

cat > ~/.gitconfig-personal << 'EOF'
[user]
    name = JaneCodes
    email = jane@personal.com
EOF

# ─── Step 3: Add includeIf to global config ───
git config --global --add includeIf."gitdir:~/work/".path ~/.gitconfig-work
git config --global --add includeIf."gitdir:~/personal/".path ~/.gitconfig-personal

# ─── Verify ───
cd ~/work/my-project
git config user.email           # jane.doe@company.com ✅

cd ~/personal/side-project
git config user.email           # jane@personal.com ✅

Key Takeaways

includeIf loads different config files based on repo location.
Organize repos by context (~/work/, ~/personal/) for automatic switching.
Prevents committing with the wrong identity — zero manual effort.
Can override any config value: name, email, GPG key, editor, etc.

Interview Prep

Q: How do you use different Git identities for different repos? A: Use includeIf in ~/.gitconfig to conditionally load different config files based on the repo's directory. For example, [includeIf "gitdir:~/work/"] loads a work config with your company email.
Q: What conditions does includeIf support? A: gitdir: matches by repository directory path, gitdir/i: does case-insensitive matching, and hasconfig:remote.*.url: matches by remote URL pattern.
Q: Why is includeIf better than setting local config per repo? A: Because includeIf is automatic — every new repo in the matching directory gets the right config immediately. With local config, you must manually configure each new repo.