So Someone You Manage Came Out As Trans: Git Edition

2022-01-05

If you manage a software developer who is in the process of coming out as trans, or if you are trans and coming out yourself and looking for advice to give your manager, you might be researching all of the steps you should take to make that process go smoothly. Here's some information and advice that I wish my manager had when I came out.

Some things like email accounts will be very straightforward to switch over and your company's payroll system will have a way to manage the legal name change process. When it comes to the Git software version control system, the available options are less clear.

The benefit of source control systems is that they give you an exact history of the project, which allows you to refer back to old versions as needed. Every commit must have an author with a name and email address provided. This information can help developers identify who to ask questions when making changes. The downside is that they were generally designed without taking into account the fact that people's names and email addresses will occasionally change.

Git Mailmap

To address this, Git added a feature to read from a .mailmap file. This file contains lines of the form

Current Name <current.email@company.biz> <previous.email@company.biz>

This will cause the git log command to display the updated author information when displaying commits. The .mailmap file has support from many editors (including my personal favorite, the Emacs magit extension).

Benefits

Because the .mailmap approach is supported by Git, IDEs and other tools can expect it to be a stable foundation and don't need to design their own, incompatible approaches to this problem. Over time, I expect the majority of developer tooling will likely support .mailmap files.
Checking this file in to the root of the repository means that all of your developers should mostly get the correct information displayed to them without any work on their end. This is important, because your trans team member will likely want to avoid any disruptions to the team. This is also why it is a good idea to have diversity training in place before you have a minority employee on your team, rather than risking the perception of "We're just doing this because of <minority employee>".

Shortcomings

In order for this to work, you have to record the previous email in an easily accessible location. I've worked at places where the pattern was <firstname>.<lastname>@company.biz. Anyone who wanted to find my deadname would only have to look in a .mailmap at the root of the repository to find it.
This solution also only addresses the Git commit author information. There are a number of places where a name might appear in a Git repository. Teammates will occasionally include messages like "Implements the design suggested by <name>" in commits. Your team may cryptographically signs commits to ensure everything added to the repository can be verified. Project manifest files will often include an author or maintainer field that is automatically populated with the information of the user who generated it.

Curating A Healthy Team Culture

Ultimately, one of the core responsibilities of a manager is to ensure a healthy team culture. This takes time, requires a lot of trust from everyone, and is easier to damage than it is to build.

In the context of having a trans member on your team, a healthy team culture involves respecting their name. Things like .mailmap can be a tool in your toolbox, but they are not complete solutions. Your goal should be to foster an environment where the team has healthy boundaries and mutual respect. A team with these qualities won't want to seek out that information and will want to avoid things that will make the trans team member dysphoric.

A Potential Alternative To The `.mailmap` File

This is unlikely to be applicable, but I'm including it here for completeness. This will cause disruption to anyone working in the repository, which goes against the advice I gave in the "Benefits" section.

If the repository has only a small number of people contributing to it and the team can accept a minor inconvenience, a possible solution is to rewrite the entire Git history of the repository via git-filter-repo --mailmap <mailmap file>. This will apply the .mailmap file to the history of the repository, creating an entirely new set of commits. You will need to force-push this to your Git server and then every user will have to hard-reset or re-clone to ensure they have the correct history. This can be a challenge to get right, so further research is advised.