Configuring Git/GitHub credentials for different folders

The premise

I work with multiple repositories in different contexts (personal, work, client projects) and need Git to automatically use the correct user name, email and SSH key depending on which repository I'm in.

In my Home folder I have a Source folder structured like this:

Source
├── davenicoll
│   └── personal repo
├── company
│   └── work repo
└── clients
    ├── client1
    │   ├── client1 repo
    │   └── client1 repo
    └── client2
        └── client2 repo

Git allows conditional includes in .gitconfig, enabling it to load different configurations based on the directory I'm working in. Conveniently, SSH supports hostname aliases, which allows me to specify an SSH key to use per parent folder.

Benefits

Prevents conflicts when using multiple GitHub accounts.
Automates SSH key selection instead of needing to manually ssh-add different keys each time.
Allows you to use multiple GitHub accounts on the same machine without issues.

Setup

Set Up Global Git Config

Edit (or create) your global Git config at ~/.gitconfig:

nano ~/.gitconfig

Add the following base configuration:

# [user] is the default git user
[user]
    name = Your Name
    email = [email protected]

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

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

[includeIf "gitdir:~/Source/clients/client1"]
    path = ~/.gitconfig-clients1

Create Context-Specific Git Config Files

Personal Config (~/.gitconfig-personal)

[user]
    name = Your Name
    email = [email protected]

Work Config (~/.gitconfig-work)

[user]
    name = Your Name
    email = [email protected]

Clients Config (~/.gitconfig-client1)

[user]
    name = Your Name
    email = [email protected]

Test the Configuration

Navigate to different directories and run:

git config --get user.email

This should return the correct email for each folder.

Setup SSH to use different keys

To set up multiple SSH keys for personal, work, and client use, and configure your system to use them based on custom hostnames (e.g., work.github.com), follow these steps:

Generate SSH keys:

ssh-keygen -t ed25519 -C "[email protected]" -f ~/.ssh/id_personal

ssh-keygen -t ed25519 -C "[email protected]" -f ~/.ssh/id_work

ssh-keygen -t ed25519 -C "[email protected]" -f ~/.ssh/id_client1

Add SSH Keys to ssh-agent:

Start the ssh-agent:

eval "$(ssh-agent -s)"

Add your keys

ssh-add ~/.ssh/id_personal
ssh-add ~/.ssh/id_work
ssh-add ~/.ssh/id_client1

Configure SSH for Custom Hostnames:

Edit (or create) your SSH config file at ~/.ssh/config:

nano ~/.ssh/config

When working with multiple accounts (e.g., personal, work, and client accounts), Git only allows one SSH key per account. This means if you try to use multiple SSH keys for different accounts without any extra configuration, Git may pick the wrong one.

To solve this, we modify the SSH configuration file (~/.ssh/config) to create custom aliases (like work.github.com instead of github.com). This lets us tell SSH which key to use depending on the alias.

Host <alias>
HostName <actual hostname>
User <SSH user>
IdentityFile <path to your private SSH key>

Host personal.github.com → Creates an alias personal.github.com for GitHub.
HostName github.com → Tells SSH that personal.github.com is actually github.com.
User git → The username for GitHub SSH authentication (always git).
IdentityFile ~/.ssh/id_personal → Specifies the SSH key to use when connecting.

Add the following configuration:

# Personal GitHub
Host personal.github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_personal

# Work GitHub
Host work.github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_work

# Client GitHub
Host client1.github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_client1

Add Public Keys to GitHub Accounts:

Copy your public keys to the clipboard:

cat ~/.ssh/id_personal.pub
cat ~/.ssh/id_work.pub
cat ~/.ssh/id_client.pub

Navigate to Settings > SSH and GPG keys > New SSH key.
Paste the key and provide an appropriate title.

Clone Repositories Using Custom Hostnames: When cloning repositories, replace github.com with your custom hostname:

Personal

git clone [email protected]:account/repo-name.git

Work

git clone [email protected]:account/repo-name.git

Clients

git clone [email protected]:account/repo-name.git

How This Works in Practice

When cloning a repository, instead of running:

git clone [email protected]:account/repo-name.git

You'll use one of these commands instead:

git clone [email protected]:account/repo-name.git
git clone [email protected]:account/repo-name.git
git clone [email protected]:account/repo-name.git

SSH automatically replaces personal.github.com with github.com and ensures the correct key (id_personal) is used.
You never have to manually switch SSH keys; the correct one is picked based on the alias.

Custom GitHub notification routing (bonus)

GitHub's Custom Email Routing feature allows you to direct notifications from different organizations to specific email addresses, helping you manage communications more effectively.

Setting Up Custom Email Routing:

Add Additional Email Addresses:
- Navigate to your GitHub Email Settings.
- Add and verify the email addresses you want to associate with your account.
Configure Custom Routing:
- Go to Notification Settings.
- Scroll to the "Custom routing" section.
- For each organization, select the desired email address for notifications.

This setup ensures that notifications from different organizations are sent to their respective email addresses, keeping your inbox organized.

For more detailed guidance, refer to GitHub's official documentation on setting up notifications.