How (and why!) to use a `.mailmap` file in Git

What is a Git .mailmap file? #

A .mailmap file is a map of names and email addresses that tells Git to display a different user name or email address for the author or committer of commits in a given repo.

Every Commit Has an Author and a Committer #

Recall from the Rewriting Git History to Change the Author and Email of Commits page, Git records two identities on every commit, and each one is a name and email pair:

• the author, the person who originally wrote the change
• the committer, the person who last applied it to the repo

Most of the time these are the same person, and Git shows you only the author, so it is easy to forget the committer exists. They come apart whenever you apply someone else’s patch, cherry-pick, rebase, or accept a squash-merge from a web UI.

This matters here for two reasons: when you create a .mailmap file, you need to map both identities to be complete, and checking the history of a given repo with a plain git log will only show you “half of the picture”.

How is a .mailmap different from using git filter-repo? #

Rewriting with git filter-repo --mailmap actually changes the commits.

Adding a .mailmap file to your repo will change how the identities of authors/committers are displayed.

If this sounds like the option you would like to or need to use, read on for instructions on how to set this up.

Set up the .mailmap file in your repo #

When you want to create a mailmap file and make it a permanent part of a given repository:

1. Create a .mailmap file in the root directory of the repository
   1. Example: repo.git/.mailmap
2. Open the .mailmap file in the plain text editor of your choice
   1. Windows: Notepad works if you don’t have a preferred editor. Watch out for Notepad quietly appending .txt to the filename; put quotes around ".mailmap" in the Save dialog to stop it
   2. Mac: TextEdit works if you don’t have a preferred editor
   3. Linux: your preferred editor, you know which one!
3. Add a mapping of author and committer names and email addresses
4. Commit that file to the repo.

There are four line formats, documented in the gitmailmap(5) manual page, and picking the wrong one is the easiest mistake to make here, because each one changes a different amount:

Names and emails are matched case-insensitively. If several old addresses need to collapse into one new identity, write one line for each old address.

A # character begins a comment that runs to the end of the line, and blank lines are ignored, so you can annotate the file to explain why each mapping is there.

Example of Setting up a .mailmap File in Your Repo #

printf 'New Name <[email protected]> <[email protected]>\n' > .mailmap
git add .mailmap
git commit -m "Use a .mailmap file to work with author identities"

Git now applies that mapping when it displays history.

Viewing Mapped Identities #

There is nothing to turn on. Once the .mailmap file is in the root of the repo, git log, git show, git shortlog, and git blame all display the mapped identities automatically. The log.mailmap setting that controls this is true by default, so no configuration is required.

If you want to build your own output format, note that Git gives you both the mapped and the raw values through separate placeholders:

git log --format='%aN <%aE>'

The case of the letter is what selects the behavior, and it does so on its own; you do not need to pass --use-mailmap alongside %aN/%aE. The --use-mailmap and --no-use-mailmap switches only affect Git’s built-in formats, which is to say the Author: line you see in a plain git log. To see that line unmapped for a moment:

git log --no-use-mailmap

GitHub reads .mailmap too, so contributor listings and similar shortlog-style summaries pick up the corrected identity. It does not change which account a commit links to, because that lookup uses the raw email address recorded in the commit.

Check your repo after making changes #

Reading git log by eye does not scale past a few dozen commits, and the default format shows you the author but not the committer. Ask Git for exactly what you want to check instead:

git log --all --format='%an <%ae> | %cn <%ce>' | sort -u

That prints every distinct author/committer pair in the whole repo, on every branch and tag, using the raw values recorded in the commits. The list should be short, and it should contain only identities you meant to keep. Anything left over is a mapping you missed, so add it to the repo .mailmap file, commit the change and push it to the remote server.

A Personal .mailmap for Repos You Don’t Control #

Committing a .mailmap file to a repo requires being able to commit to that repo. When you can’t, or when a mapping is only useful to you, Git can read an additional mailmap from anywhere on your filesystem via the mailmap.file setting:

git config --global mailmap.file ${HOME}/.mailmap

The repo’s own root .mailmap is loaded first, and the file named here is layered on top of it, so a personal mailmap augments the project’s rather than replacing it. The file uses the same four line formats described above.

Verify the setting resolves:

git config --get mailmap.file

If You Are An Author/Committer: Fix Your Git Config #

If you are an author or committer in a given repo, and you want to use a different identity going forward, make sure you update either the user configuration in the repo itself, or your global user configuration in your home directory.

To set the identity in a given repo:

cd /path/to/your/repo.git
git config user.name "New Name"
git config user.email "[email protected]"

To set the identity globally on a given system:

git config --global user.name "New Name"
git config --global user.email "[email protected]"

Summary #

If you want a Git repo to use a different name and email than the one its commits were made with, you have two options, and they are not the same kind of fix.

When you re-write commits with git filter-repo --mailmap, this actually changes the checksums in the commits. You can see on the Rewriting Git History to Change the Author and Email of Commits page what other possible issues you may encounter by re-writing commits.

Instead of using git filter-repo to change the contents of your repo, you can use a .mailmap file in your repo to change how the identities are displayed in that repo. This is a lighter weight option, and works well with repos that have been made public.

Nothing needs to be turned on for Git to use the file: log.mailmap is true by default, so git log, git show, git shortlog, and git blame pick it up on their own. In your own formats, %aN/%aE are the mapped values and %an/%ae are the raw ones. For a mapping only you need, or for a repo you can’t commit to, point mailmap.file at a .mailmap in your home directory instead.

If you change your identity for some reason, make sure you set or update your user.name and user.email in the repo, otherwise subsequent commits will use your previous identity.

Verify a .mailmap file with git log --all --format='%an <%ae> | %cn <%ce>' | sort -u, which covers both identities across every branch and tag.

Enjoy!

The commands shown were tested against git version 2.55.0.

AI Content Disclosure

This page was mostly written by a human, based on a section on a different page that was written by Claude Opus. Claude Opus also reviewed this page for spelling, grammar, and technical accuracy, and contributed corrections and additional sections in response to that review.