Managing Multiple Git Identities with Conditional Includes

9 May 2025

If you contribute to both internal and client Git repositories - or juggle multiple client projects - keeping your commit authors and SSH credentials in order can get messy fast. Thankfully, Git offers a powerful feature to help with that: conditional includes.

In this post, I’ll walk through how I use this approach to keep my Git identity and credentials scoped correctly depending on the project folder.

Why Use Conditional Includes?

By default, Git uses global config settings from ~/.gitconfig, which applies to every repo. But when working across multiple organisations or contexts, you often need different:

  • Commit author name and email
  • GPG/SSH signing keys
  • SSH command settings (e.g. using a different key for GitHub)

Using includeIf blocks in .gitconfig, you can automatically load extra config only when working in specific folders.

The Setup

Global .gitconfig

Here’s what my base ~/.gitconfig looks like:

[user]
	name = Mike Houston
	email = [email protected]

[init]
	defaultBranch = main

[pull]
	rebase = true

[core]
	autocrlf = input
	excludesfile = /Users/Michael.Houston/.gitignore_global

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

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

The key part is this block:

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

This tells Git:

“If I’m working in a repo under ~/acme-team/, also load settings from ~/.gitconfig-acme-team.”

Repeat that pattern for other directories where you need distinct settings.

Team-Specific Config

Here’s what I’ve got in ~/.gitconfig-acme-team:

[user]
	name = Mike Houston
	email = [email protected]
	signingkey = ~/.ssh/acme-github-signing-key

[core]
	sshCommand = ssh -i ~/.ssh/id_ecdsa_acme

[commit]
	gpgsign = true

[gpg]
	format = ssh

This sets:

  • My name and Acme team email
  • The GPG signing key to use (backed by SSH)
  • A custom sshCommand so the right key is used when authenticating with remote repos
  • Ensures commits in these repos are signed

Best Practices

  • Paths matter: The gitdir: value must end with a slash and point to a parent directory, not a specific repo. e.g. ~/acme-team/, not ~/acme-team/my-repo
  • Use ~ safely: Git expands ~ correctly in paths
  • Keep configs modular: One include file per context is cleanest
  • Version control them (carefully): You might want to keep these in a dotfiles repo - just avoid committing anything sensitive like private key paths

Final Thoughts

This pattern has saved me tons of context switching headaches and reduced the risk of pushing commits with the wrong author info or SSH key. It’s flexible, clean, and just works.

If you frequently shift between clients or internal repos, setting this up is well worth the few minutes of config fiddling.