As everybody knows, Git has a lot of obscure commands and options. Today I’d like to write about one of them (which incidentally I mentioned two weeks ago). You can put a file named .mailmap at the top level of your Git repository, and have various names and/or email addresses mapped to a “canonical” names and addresses.
In my experience, people often have their name or email set up incorrectly. Perhaps they switch the email provider mid-project. Perhaps they get married and change their last name. Perhaps they sometimes commit from another machine where hey have their private email set up in Git.
Having commits done by the same person under different email/name combinations is sometimes a pain. I might want to look for something in commits by a given person. (I search Git histories of various repos pretty often, and the --author= option to git log is pretty useful.) I might want to gather statistics about some Git repo.
Every non-empty, non-comment line of the .mailmap file consists of the “canonical” email and/or name followed by the one(s) used in actual commits. It can be either just a “name – email” pair (in that case, the email given is mapped to the name given), or an “email – email” pair (where the second email is mapped to the first one), or an “name – email – email” sequence (where the email at the end is mapped to the name/email pair given first), or finally “name – email – name – email”, where the second pair is mapped to the first one.
See the manpage of gitmailmap to see an example. You can also check whether your .mailmap file does what you think it does using the git check-mailmap command. You can also configure Git to look for the .mailmap file under some other name, though I doubt whether it is a good idea.
And while at that, let me remind you that every Git commit has two people associated with it – the author and the committer, and that distinction can be pretty useful. Both are subject to mappings described in .mailmap, of course.
That’s it for today, see you next time!