How to tell git to use the correct identity (name and email) for a given project?

Managing Git Identities: How to Use the Correct Name and Email Per Project

Learn how to configure Git to use different user names and email addresses for individual projects, ensuring your commits reflect the correct identity for work, personal, or open-source contributions.

Git is a powerful version control system, and one of its fundamental aspects is tracking who made which changes. Every commit in Git is associated with an author's name and email address. While you can set a global identity for all your Git operations, it's common to need different identities for different projects. For instance, you might use your work email for company projects and a personal email for open-source contributions or personal projects. This article will guide you through configuring Git to use the correct identity for each of your projects.

Understanding Git's Configuration Hierarchy

Git uses a hierarchical configuration system, which allows for flexible settings. Understanding this hierarchy is key to managing your identities effectively. There are three main levels of configuration:

1. System-level: Applies to all users on a system and all their repositories. This is typically found in /etc/gitconfig.
2. Global-level: Applies to a specific user across all their repositories. This is usually located in ~/.gitconfig or ~/.config/git/config.
3. Local-level (Repository-specific): Applies only to the current repository. This configuration is stored in the .git/config file within the repository's directory.

When Git needs a configuration value, it checks these levels in order: local, then global, then system. The most specific setting (local) overrides less specific ones (global, system).

flowchart TD
    A[Git Configuration Request] --> B{Check Local .git/config}
    B -- Found --> C[Use Local Setting]
    B -- Not Found --> D{Check Global ~/.gitconfig}
    D -- Found --> E[Use Global Setting]
    D -- Not Found --> F{Check System /etc/gitconfig}
    F -- Found --> G[Use System Setting]
    F -- Not Found --> H[No Setting Found]

Git Configuration Hierarchy Flow

Setting Your Global Git Identity

Before diving into project-specific configurations, it's a good practice to set a default global identity. This will be used for any repository where a local identity isn't explicitly defined. You can set your global name and email using the git config --global command.

git config --global user.name "Your Global Name"
git config --global user.email "your.global.email@example.com"

Setting your global Git user name and email.

Configuring Project-Specific Git Identity

To set a different identity for a specific project, navigate into the project's root directory and use the git config command without the --global flag. This will write the configuration directly into the .git/config file of that repository, overriding any global settings for that project.

1. Navigate to your project directory

Open your terminal or command prompt and change the directory to the root of your Git project.

2. Set the project-specific user name

Use the git config command to set the user.name for this specific repository. This will override your global name.

3. Set the project-specific user email

Similarly, set the user.email for this repository. This email will be used for all commits made within this project.

4. Verify the local settings

To confirm that your local settings are correctly applied, you can list the configurations for the current repository. Note that this will show both local and inherited global settings, with local ones taking precedence.

cd /path/to/your/project
git config user.name "Project Specific Name"
git config user.email "project.email@work.com"
git config --list

Setting and verifying project-specific Git user name and email.

Advanced: Conditional Includes for Dynamic Configuration

For more advanced scenarios, Git 2.13 introduced conditional includes, allowing you to include different configuration files based on the path of the repository. This is particularly useful if you organize your projects into distinct directories (e.g., ~/work/ for work projects and ~/personal/ for personal projects). You can define different identities for these paths without manually configuring each repository.

# In your global ~/.gitconfig file
[user]
    name = "Your Global Name"
    email = "your.global.email@example.com"

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

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

Using includeIf in ~/.gitconfig to conditionally load configurations.

# Content of ~/.gitconfig-work
[user]
    name = "Your Work Name"
    email = "your.work.email@company.com"

Example content for ~/.gitconfig-work.

# Content of ~/.gitconfig-personal
[user]
    name = "Your Personal Name"
    email = "your.personal.email@gmail.com"

Example content for ~/.gitconfig-personal.

With this setup, any Git repository located under ~/work/ will automatically use the identity defined in ~/.gitconfig-work, while repositories under ~/personal/ will use ~/.gitconfig-personal. Any other repository will fall back to the global settings in ~/.gitconfig.