Using mailmap to fix authors list in git

Jan 6, 2013

I love doing git shortlog -sne to get number of commits by each author in a git repo ( don’t aske me why!)

One problem with running it on git repos of long running projects is that authors may change their name or email or both during the course of the project due to many reasons ( most of the times, I have seen people realize few commits into the project that they were using a wrong / personal / professional email id or username. Other times, it is because, being complete newbies to git, they did not configure the username and email and the default ones generated by git were being used.)

When that happens, you can’t get proper counts from the git shortlog output. Here’s a sample output from a dummy repo with two commits. Both are by me, but with different names:

C:\projects\test.git [master]> git shortlog -sne
     1  Manoj <manojlds@gmail.com>
     1  Manojlds <manojlds@gmail.com>

Eventhough I have made 2 commits (yay!), I have 1 commit assigned to each of my names.

How do I fix this and make the git shortlog output more meaningful?

This is where a .mailmap file comes into the picture. It contains the mapping from the “wrong” email ids and / or names to the right ones:

Proper Name <proper@email.xx> Commit Name <commit@email.xx>

The above maps the Commit Name <commit@email.xx> to the Proper Name <proper@email.xx> ( wasn’t that obvious? Yeah, but I had to make it explicit, weren’t I?) There are multiple forms for specifying the correct user name and email in a mailmap. Learn more about git shortlog and .mailmap at the manpage for shortlog

You can just specify the correct name for the email address in the below form:

Proper Name <commit@email.xx>

This is what I need ,as both my commits have the correct email address, but use different user names, and I want to specify the canonical user name. To fix the authors list in my dummy repo and make sure that the 1 commit is also attributed correctly to me, I can write a .mailmap file with the following contents:

Manoj <manojlds@gmail.com>

You can place the file with that name at the root of your repo and the run git shortlog -sne to see that authors list is like we want. You can also set the config mailmap.file with the path to the mailmap file and git will pick up the file from that location if the .mailmap is not found at the root of the repo. You can use this when you don’t want mailmap to be part of your repo.

Comments