maiobarbero.dev

Using Different Git Identities per Folder with includeIf.gitdir

Learn how to configure Git to use different usernames and emails based on the folder or project you're working in, using a custom .gitconfig and the includeIf.gitdir directive.

Using a Custom .gitconfig for Specific Folders in Git

Git is an incredibly powerful version control system, widely used by developers and teams. One of its most useful features is the ability to configure settings, such as your name and email, in a way that fits your workflow. In some situations, you might need to use different Git configurations for different projects or repositories. For instance, you might want to use a personal email address for personal projects and a work email address for work-related repositories. Fortunately, Git allows us to accomplish this with ease using custom .gitconfig files and the includeIf.gitdir directive.

Why Use a Custom .gitconfig for Specific Folders?

There are several reasons you might want to use a different configuration for a specific folder or repository:

  • Personal vs Work Repositories: You may want to use your personal email address and name for your personal repositories and a work email and name for your professional ones.
  • Multiple Accounts: You could be working with multiple GitHub or GitLab accounts, and each one needs to be associated with different credentials.
  • Repository-Specific Settings: Some repositories may require unique configurations such as different merge strategies, commit hooks, or user information.

The includeIf.gitdir Instruction

The includeIf.gitdir instruction allows you to include one Git configuration file from within another based on the directory you’re working in. This means that you can create repository-specific configuration files that override your global .gitconfig settings for specific directories.

Steps to Use a Custom .gitconfig Based on Folder

Here’s how you can set up Git to use different configurations based on the directory of your repository.

1. Set Up Global .gitconfig

First, ensure you have a global .gitconfig file. This is the default configuration file that Git uses for most of your repositories unless a more specific configuration is defined. You can check your current global configuration by running:

bash
git config --global --list

If you need to modify your global settings (for example, setting your default name and email), you can do so:

bash
git config --global user.name "Your Name"
git config --global user.email "yourname@example.com"

2. Create a Custom .gitconfig for Specific Repositories

Next, create a new .gitconfig file for the specific folder or repository you want to configure. You can place this configuration in any directory. For instance, you might create a custom .gitconfig file for work-related repositories.

Let’s say you want to use a different email and name for all repositories inside a ~/Projects/work/ directory. You could create a new .gitconfig file:

ini
# ~/Projects/work/.gitconfig
[user]
    name = Work Name
    email = work@example.com

Now that you have your custom .gitconfig file, you need to tell Git to use it when you’re working inside a specific directory. This is where the includeIf.gitdir directive comes in.

Open your global .gitconfig file, usually located at ~/.gitconfig, and add:

ini
[includeIf "gitdir:~/Projects/work/"]
    path = ~/Projects/work/.gitconfig
  • This tells Git to include the configuration in ~/Projects/work/.gitconfig only when working inside a repository under that path.
  • Wildcards are also supported, such as gitdir:~/Projects/*/.

4. Verify Your Configuration

To verify everything is working, navigate to a repository inside ~/Projects/work/ and check the Git config:

bash
cd ~/Projects/work/my-repo
git config user.name
git config user.email

These should reflect the values from your custom .gitconfig.

5. Optional: Use includeIf.gitdir for Multiple Configurations

If you need configurations for multiple directories, simply add more blocks:

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

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

This lets you maintain clear separation between identities or preferences per project area.

Best Practices

  • Organize by Directory: Use consistent folder structures to make gitdir rules easier to manage.
  • Fallback to Global: Only override settings that truly need to change — let the global .gitconfig handle defaults.
  • Check with git config --show-origin: This command will show where each configuration setting is coming from — very helpful for debugging.

Conclusion

Using the includeIf.gitdir directive in Git is a powerful way to manage different configurations based on your folder structure. Whether you’re juggling personal and professional repositories or working across multiple accounts, this technique helps prevent identity mix-ups and simplifies your Git workflow.

With just a bit of setup, you can enjoy clean, context-aware Git configurations , no manual switching required.