Using git while trans

Published on 2026-02-27 by Brooke Hart

Git is the version control system. Yes, others exist, but if you're writing code you're probably using git.

Git was not designed with people's names changing in mind. This is a problem, because people's names do change for many reasons. The most common one many people will be familiar with is women changing their surname when marrying a man.

The one I am concerned about is the name change that trans people go through as part of a social transition. Unlike changing a surname at marriage, in which a person's "maiden name" can remain common knowledge, changing your name during a transition leaves behind what we commonly call a "deadname".

Revealing a trans person's deadname is a safety issue, which is a problem when working with git.

Removing your deadname from displayed logs

There is a built-in utility in git that allows displaying commits with an updated name. That is git mailmap. It allows you to create a `.mailmap` file in the root of a git repository that contains lines like this:

Correct Name <correct.email@company.tld> <commit.email@company.tld>

With a .mailmap file in place, git tools such as git log and git blame will display names found in a .mailmap file for commits that used an email address identified in there.

In order to find out what email addresses might exist against your deadname, you can run this command to see what commit authors exist in a repo's history:

git shortlog --summary --email

This will display an alphabetical list of commit author names and their associated email addresses, with the number of commits listed to the left. The same name with a different email address is treated as a different commit author.

Adding a .mailmap file is a useful way to effectively update the name against all your old commits without having to rewrite git history. This is useful because rewriting history is often not an option, especially in work environments.

However, this approach has some downsides as well:

• If the email address used for your commits contains your deadname, as is common in work environments, then it will be exposed to anyone viewing the .mailmap file.
• GitHub, by far the most commonly used git hosting platform, at the time of writing does not support .mailmap and will still display your deadname against your old commits.
• The original log, including your deadname, still exists and can be revealed by modifying or removing the .mailmap file.

These shortcomings are only surmountable by rewriting history.

Removing your deadname from commit author data

Git does have a built-in feature called filter-branch that can be used for rewriting history, but for years now it's been recommended against. Instead, the git documentation now officially recommends the use of an external Python script called git-filter-repo.

You can use git-filter-repo to rewrite the history of a git repository. It expects to always be run against a fresh clone of your repo, so before using it you should create a fresh clone to work in. Using git-filter-repo will also remove your repo's remotes, this is intentionally added friction to encourage verifying your changes before force pushing them to the remote.

You can use git-filter-repo to modify author information against commits based on the contents of a .mailmap file:

git filter-repo --use-mailmap

If you want to use an external file (e.g. because a .mailmap file already exists for this repo and you only want to rewrite _your_ commits) you can also use an external file like this:

git filter-repo --mailmap <filename>

Note that, because git-filter-repo expects to work on a fresh clone, you'll want your external file to exist outside your repo's root directory.

Once you've done this, you can re-check the list of commit authors using git shortlog like in the example above. Make sure to remove any of your lines in a .mailmap file first, so you don't accidentally obscure any commits under your deadname at this point.

Once confirmed, you can add your remote back and force push your changes, e.g.

git remote add origin <url-to-origin>
git push --all --force

Removing your deadname from committed files

Rewriting history like this won't remove a .mailmap file. If you don't want that file in your repo's git history either because it reveals your deadname then you'll need to remove it. If you want it removed from the history itself, you can also use the sensitive data removal feature git-filter-repo to rewrite history in a way that removes a file completely.

Remember, you'll need a (new) fresh clone to do this.

git filter-repo --sensitive-data-removal --invert-paths --path .mailmap

If you have other files that may have once contained your deadname, such as a package.json file, you can also use the sensitive data removal tool to change these.

First, you'll need to create an expressions file defining what text to replace. For example:

Deadname==>My Name

Then you can run a history-rewriting find and replace using that file by running this command:

git filter-repo --sensitive-data-removal --replace-text <path-to-expressions-file>

Be very careful with this step, as a global find and replace could result in unanticipated changes.

Once you're finished removing this sensitive data and you've verified that it worked as expected, you can force push your changes to update the history on the remote.

git push --all --force

Feedback

If you know of any other tips for removing your deadname from a git repo, I'd like to hear them! Please email me your feedback.