Git includeIf: The Config Superpower You Didn’t Know About

If you're like me, you've probably been using Git for years without realizing there's a feature that could make your life significantly easier. Enter includeIf: a powerful Git configuration directive that lets you apply different settings based on your repository's location. Let me show you why this is a game-changer.

The Problem: One Config Doesn't Fit All

Have you ever accidentally committed code using your personal email address in a work repository? Or found yourself constantly switching between different SSH keys for different Git hosts? These are common problems when your Git configuration is one-size-fits-all.

Enter includeIf

The includeIf directive lets you automatically apply different Git configurations based on where your repository is located. Think of it as a way to tell Git: "If you're in this directory, use these special settings."

The Most Common Use Case: Multiple Email Addresses

This is the killer feature that most developers use includeIf for. Here's how to set it up:

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

[includeIf "gitdir:~/personal/"]
    path = ~/.gitconfig-personal

Then in ~/.gitconfig-work:

[user]
    email = firstname.lastname@company.com

And in ~/.gitconfig-personal:

[user]
    email = mypersonal@email.com

Now, Git will automatically use your work email for any repository under your ~/work directory and your personal email for repositories under ~/personal. No more accidentally revealing your "l33tc0der@gmail.com" address in work commits!

Beyond Email: Other Practical Uses

While email configuration is the most common use case, includeIf can do much more. Here are some practical examples:

Different SSH Keys per Git Host

[includeIf "gitdir:~/github/"]
    path = ~/.gitconfig-github
# In .gitconfig-github:
[core]
    sshCommand = "ssh -i ~/.ssh/github_key"

Project-Type Specific Settings

[includeIf "gitdir:~/python-projects/"]
    path = ~/.gitconfig-python
# In .gitconfig-python:
[core]
    hooksPath = ~/.git-hooks/python
    whitespace = trailing-space,space-before-tab

Power User Features

For those who want to take it further, here are some creative uses:

Team-Specific Commit Templates

Different teams might have different requirements for commit messages. With includeIf, you can automatically apply the right template:

[includeIf "gitdir:~/team-a/"]
    path = ~/.gitconfig-team-a
# In .gitconfig-team-a:
[commit]
    template = ~/.gitmessage-team-a

Environment-Specific Configurations

When working with production systems, you might want stricter settings:

[includeIf "gitdir:/production/"]
    path = ~/.gitconfig-prod
# In .gitconfig-prod:
[safe]
    directory = *
[core]
    fileMode = true

Setting It Up

1. First, create your main .gitconfig file with the includeIf directives.
2. Create separate config files for each context (like .gitconfig-work, .gitconfig-personal).
3. Make sure your repository paths match the patterns in your includeIf directives.

Pro Tips

• The path pattern in gitdir: is matched against the repository location, not your current working directory.
• You can use gitdir/i: for case-insensitive matching on Windows.
• Changes to included config files take effect immediately - no need to restart Git.

Common Gotchas

• Make sure your paths end with a trailing slash (~/work/ not ~/work)
• The paths in gitdir: are relative to your home directory
• If multiple includeIf conditions match, all matching configurations are applied in order

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com