A guide on how to configure multiple git identities or accounts

TL;DR

Most guides tell you to hack your .ssh/config to manage multiple Git identities and SSH keys — we strongly advise against this. This guide introduces other superior identity management methods, focusing on two scalable options via core.sshCommand and a powerful, niche shell script for dynamic SSH key switching.

Introduction

A single account on a Git-forge, such as GitLab or GitHub, is quite common and only requires a little configuration. But when your employer or client uses the same forge and requires you to have a second account on that forge, it could become a bit tricky, especially when you have them within the same repository. There are ways to solve this problem. This post will explain four of them.

We’ll start with my least recommended, but obligatory option:

A. Change the remote URI via ssh_config

And by ssh_config, I mean $HOME/.ssh/config.

The idea behind this is that by using .ssh/config, you can create aliases for a GitForge and configure a specific identity for each alias. In this case, you will use clientforge as your client’s host and the original name gitforge.com for your projects. Your .ssh/config will look a little something like this:

Host gitforge.com
   User git
   Hostname gitforge.com
   IdentityFile ~/.ssh/id_rsa

Host clientforge
    User git
    Hostname gitforge.com
    IdentityFile ~/.ssh/id_client

In your project’s repository, you’ll need to change the remote of your liking with the set-url command for remotes:

$ git remote set-url upstream git@clientforge:client/themoneymaker.git

The downside to this approach is that you need to remember which host to use for each project, and you can no longer copy/paste specific commands from the forges after you’ve created a new repository. The upside is that it doesn’t require any additional git configuration changes.

Quick gitconfig recap

Before we head into the other options, it is essential to know that git stores its configuration in several locations. You have a system-wide configuration in /etc/git/config, a global one in $HOME/.gitconfig, and a local one in your repository $GIT_DIR/.git/config. This allows you to hone your configuration from global to very specific at the repository level. There are also several include directives, such as the includeIf directive. Now you can include a separate configuration based on the path of your projects, which we will use in the upcoming methods.

B. Using different sshCommands (or options) for a project

As said, we have a per-repository config. For a single project, you can set a custom core.sshCommand. The core.sshCommand can be either used to replace the full ssh-command or to tweak additional options. This allows you to use the key associated with your work account. You can do this by running the following command:

git config core.sshCommand \
  '-i ~/.ssh/id_client -o IdentityOnly=yes -F /dev/null'

This should result in a line similar to this in $GIT_DIR/.git/config:

[core]
  sshCommand = -i ~/.ssh/id_client -o IdentityOnly=yes -F /dev/null

The identityOnly=yes setting is only there to prevent SSH from looping over all your SSH keys and potentially using a different SSH key. The -F /dev/null disables using your .ssh/config. You could also use a different SSH config for just the sshCommand, e.g., sshCommand = -F ~/.ssh/config-client, and set the correct SSH options in that file. You could also use the entire command here, e.g., ssh -i ~/.ssh/id_client -o IdentityOnly=yes -F /dev/null.

This option only scales well when you have only one or two projects, which leads me to the next option.

C: Using different sshCommands (or options) per project directories

You can use different git configurations depending on the project directory you are in. For this, we use the previously mentioned [includeIf] directive, which allows you to include a separate configuration based on the path of your projects. So all projects in $HOME/work/client share the same git configuration. In your $HOME/.gitconfig, you need to add the following snippet:

[includeIf "gitdir:~/work/client/"]
   path = ~/.config/git/client.config

Now in $HOME/.config/git/client.config, you can configure the core.sshCommand as done in the previous example. You can also use this for configuring other bits of git for your project(s), such as a different e-mail address, name, etc. This way, you can manage multiple projects with ease using a single configuration file.

Custom SSH wrapper script: Dynamic identity switching per remote or username/group

The most niche and flexible of all, and can work as a combination of the last two options. The problem I tried to solve while developing this solution is that I had two accounts on the same GitForge, and I have a ton of repositories. Because the hostnames of the repositories are placed in the myrepos configuration file, I cannot just quickly change the host in .ssh/config. And I also didn’t want to change the host for all my personal projects. In the past, I could use my account to commit to the company’s repos. However, after they underwent ISO certification, we had to log in with SSO, and only those accounts were authorized to make changes. So I had to create two separate accounts with two distinct SSH keys.

As I was already using the includeIf directives for various directories, I wanted to be able to select a different SSH key for specific remotes. Now there is an includeIf directive that supports including a configuration when a remote has a specific endpoint:

[includeIf "hasconfig:remote.*.url:https://example.com/**"]

This approach will not work as expected because it includes the configuration, regardless of where you push your changes. So we will use an SSH-wrapper script and configure it as the core.sshCommand command.

First, you need to know how git sends its SSH command. You can test this by making a script and printing the things to STDERR or using set -x. Printing to STDOUT from within the script will issue warnings:

protocol error: bad line length character: git@

You can also use GIT_TRACE=1 while issuing a command that triggers something on your remote (git fetch, git pull, git push, etc). Git has several options on how and what it sends to SSH. You can change these options by setting the ssh.variant option. I started by setting it to simple, changed it to ssh, and now it is back to the default auto.

A small script like this will do the job for testing purposes:

set -x

echo $@ >&2
ssh $*

And you issue the command:

git config --local core.sshCommand /path/to/wrapper-script.sh

After which you run git fetch:

+ echo -o SendEnv=GIT_PROTOCOL git@gitlab.com git-upload-pack 'waterkip/themoneymaker.git'
-o SendEnv=GIT_PROTOCOL git@gitlab.com git-upload-pack 'waterkip/themoneymaker.git'
+ ssh -o SendEnv=GIT_PROTOCOL git@gitlab.com git-upload-pack 'waterkip/themoneymaker.git'

As you can see, the last bit of the parameters is what we are interested in. It has the repository, and we can select the correct ssh-key based on that. We can do that in two ways:

1. We define the sshIdentityFile on the remote itself, which is hostname and repo gnostic: git@gitlab.com:waterkip/repo.git
2. We define the sshIdentityFile more global and it depends on just the owner of the repo: waterkip

git config --set remote.upstream.sshIdentityFile ~/.ssh/id_client

Or we do it solely based on the username:

git config --set local.sshIdentityFile.client ~/.ssh/id_client

The wrapper script:

#!/usr/bin/env zsh

# $@ = -o params=foo host 'command \'user/repo.git\''
host=${@[$(($# - 1))]}

# repo = 'command \'user/repo.git\''
repo=${@[$#]}
# strip ' from the line
repo=${repo//\'/}
# repo = ( user repo.git )
repo=("${(@s: :)repo}")
# repo = repo.git
repo=$repo[2];
remote=($(git config --get-regexp "remote.*" $host:$repo))
# split on .: remote = (foo bar baz file)
remote=("${(@s:.:)remote}")

identity=$(git config --get "remote.$remote[2].sshIdentityFile")

if [ -z "$identity" ]
then
  name=("${(@s:/:)repo}")
  identity=$(git config --get "local.sshIdentityFile.$name[1]")
fi

ssh_opts=""
[ -n "$identity" ] && ssh_opts="-i $identity -o IdentitiesOnly=yes -F /dev/null"

eval ssh $ssh_opts $*

This allows me to use different accounts for each remote within the same repository. And adding a second account becomes dead easy:

git config --set remote.clientb.sshIdentityFile ~/.ssh/id_clientb

git config --set local.sshIdentityFile.clientb ~/.ssh/id_clientb

Conclusion

These are the four ways to configure multiple identities and SSH keys for git. Most developers will want to choose either option B or C, depending on the number of repositories they maintain. A few, like myself, will use option D for specific repositories where path based logic cannot be applied. All methods except for option A have been in use by the author for at least three years. The choice ultimately depends on your repository organization and workflow constraints, rather than which method is considered “best”. Although I would still strongly advise against using SSH configuration changes for things that can be solved natively in git by using option B or C.

A note on an ingenious alternative

I do want to point out one particular use case for

[includeIf "hasconfig:remote.*.url:https://example.com/**"]
  path = ~/.config/git/example.config

Ingo Richter’s post Manage Multiple Git Identities With Conditional Includes showcases a lovely way to include gitconfigs based on remotes. While I can’t use the solution, I do find the method ingenious.

Comparison table