People change their names for all sorts of reasons. They get married, they transition, or they just decide a different name better suits them. When this happens, things break. Recently I talked about how email address changes break things. Today it's how to fix this issue with git.

We use git at work. After I came out at work, it was a game of whack-a-mole to find all the deadname instances. One of my coworkers pointed out that my deadname was all over our commit logs.

All over them.

I have the most lines of code committed in our organization. Many editors show the author and commit message for line that you're on. That means... Deadname, constantly.

YIKES.

In other applications, you can just change your name. In git, the history is meant to be immutable, so a record of old names is just... there. You could rewrite history, but in a team setting that sort of rebasing isn't really tenable. You just cannot stop the world long enough to make it happen.

Fortunately, we can paper over it by using git mailmap¹. This lets you replace the name and email addresses on commits with the correct ones. It's pretty straightforward.

You create a file called .mailmap in the root of your repository. In it, each line says how to remap an email address (blank lines are ignored, and # begins comments). There are a few different ways you can do this, which are provided in the docs. There's one that I think is the most useful, though. You list the correct name, followed by the correct email address inside <>, followed by the email address on the commits to map (also inside <>).

For example, here's a snippet of a mailmap file I setup at work (with a few lines redacted, for reasons):

Nicole Tietz-Sokolskaya <me@ntietz.com> <nicole@remesh.org>
Nicole Tietz-Sokolskaya <me@ntietz.com> <me@ntietz.com>
Nicole Tietz-Sokolskaya <me@ntietz.com> <ntietz@gmail.com>

This standardizes all my commits to display my current name and my current email address, and all the tools seem to pick this up pretty seamlessly.

To find your email addresses to change, you can use grep. I ran something like this, with my deadname subbed in:

git log | grep "Author" | grep DeadFirstName

There was another person in the history with the same first name, but it was easy enough to ignore those entries. Then I wrote the mailmap file you see above (plus a few other lines; why did my config change so many times in 6 years??). The last step was confirming that it worked:

git log | grep "Author" | grep Nicole | sort -u

This comes back with just one line, reflecting my name and email, so everything worked!

We can do better, though. This can be wrapped up in one small script.

#!/bin/bash
# file: mailmap-deadname.sh
set -e

if [ $# -ne 3 ]; then
    echo "Usage: $0 <deadname> <name> <email>"
    exit 1
fi

git log --format="%aN <$3> <%aE>" | grep "$1" | sort -u | sed -e "s/$1/$2/g" >> .mailmap

To use it, you run something like ./mailmap-deadname.sh 'Dead Name' 'Nicole Tietz-Sokolskaya' 'me@ntietz.com' and it appends the lines it needs into the mailmap file, and voila, you're done. Make sure you commit the mailmap file so that it's reflected in your coworkers' git logs, too!