Keep Git Authors in Order With Gitmailmap

Gitmailmap is a good way to keep the git authors in order.

The official git documentation says:

If the file .mailmap exists at the toplevel of the repository, or at the location pointed to by the mailmap.file or mailmap.blob configuration options (see git-config[1]), it is used to map author and committer names and email addresses to canonical real names and email addresses.

In other words, imagine you want to check git history with shortlog, something like:

$ git shortlog -nse

which will give you overal stats about authors and their number of commits. If you don’t use .mailmap, chances are, it will return a similar output:

69 Pavel Saman <pavelsam@example.cz>
33 Pavel Šaman <pavelsaman@users.noreply.github.com>
 6 Pavel Saman <samanpavel@example.com>
 3 Pavel Saman <pavel.saman@example.cz>

I have done 111 commits in this repository, but I appear to be four different people. Kind of weird. It’d be better to tell git that these four identities belong to only one person, that is to use only one identity.

.mailmap to the rescue.

Let’s say that I always want to use Pavel Saman as a name and samanpavel@example.com as an email. Then I’d create a .mailmap with these rows:

Pavel Saman <samanpavel@example.com> <pavelsam@example.cz>
Pavel Saman <samanpavel@example.com> Pavel Šaman <pavelsaman@users.noreply.github.com>
Pavel Saman <samanpavel@example.com> <pavel.saman@example.cz>

Let’s take the first line as an example:

Pavel Saman <samanpavel@example.com> <pavelsam@example.cz>

I’m basically saying: “If you find email pavelsam@example.cz, use email samanpavel@example.com and name Pavel Saman instead.”

Emails and names on the right side are substituted for emails and names on the left side.

I save this .mailmap to the root dir of the project. When I run the shortlog command again, I can see a different output this time:

$ git shortlog -nse
111 Pavel Saman <samanpavel@example.com>

That looks much better, I don’t appear to have a split personality anymore :)

This is a small think, but can make a project look a bit more clean and professional.

If you like my posts, please follow me to get notified when I write a new post. Thank you.