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:

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 <>
33 Pavel Šaman <>
6 Pavel Saman <>
3 Pavel Saman <>

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 as an email. Then I’d create a .mailmap with these rows:

Pavel Saman <> <>
Pavel Saman <> Pavel Šaman <>
Pavel Saman <> <>

Let’s take the first line as an example:

Pavel Saman <> <>

I’m basically saying: “If you find email, use email 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:

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.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store