1If the file `.mailmap` exists at the toplevel of the repository, or at 2the location pointed to by the mailmap.file configuration option, it 3is used to map author and committer names and email addresses to 4canonical real names and email addresses. 5 6In the simple form, each line in the file consists of the canonical 7real name of an author, whitespace, and an email address used in the 8commit (enclosed by '<' and '>') to map to the name. For example: 9-- 10 Proper Name <commit@email.xx> 11-- 12 13The more complex forms are: 14-- 15 <proper@email.xx> <commit@email.xx> 16-- 17which allows mailmap to replace only the email part of a commit, and: 18-- 19 Proper Name <proper@email.xx> <commit@email.xx> 20-- 21which allows mailmap to replace both the name and the email of a 22commit matching the specified commit email address, and: 23-- 24 Proper Name <proper@email.xx> Commit Name <commit@email.xx> 25-- 26which allows mailmap to replace both the name and the email of a 27commit matching both the specified commit name and email address. 28 29Example 1: Your history contains commits by two authors, Jane 30and Joe, whose names appear in the repository under several forms: 31 32------------ 33Joe Developer <joe@example.com> 34Joe R. Developer <joe@example.com> 35Jane Doe <jane@example.com> 36Jane Doe <jane@laptop.(none)> 37Jane D. <jane@desktop.(none)> 38------------ 39 40Now suppose that Joe wants his middle name initial used, and Jane 41prefers her family name fully spelled out. A proper `.mailmap` file 42would look like: 43 44------------ 45Jane Doe <jane@desktop.(none)> 46Joe R. Developer <joe@example.com> 47------------ 48 49Note how there is no need for an entry for `<jane@laptop.(none)>`, because the 50real name of that author is already correct. 51 52Example 2: Your repository contains commits from the following 53authors: 54 55------------ 56nick1 <bugs@company.xx> 57nick2 <bugs@company.xx> 58nick2 <nick2@company.xx> 59santa <me@company.xx> 60claus <me@company.xx> 61CTO <cto@coompany.xx> 62------------ 63 64Then you might want a `.mailmap` file that looks like: 65------------ 66<cto@company.xx> <cto@coompany.xx> 67Some Dude <some@dude.xx> nick1 <bugs@company.xx> 68Other Author <other@author.xx> nick2 <bugs@company.xx> 69Other Author <other@author.xx> <nick2@company.xx> 70Santa Claus <santa.claus@northpole.xx> <me@company.xx> 71------------ 72 73Use hash '#' for comments that are either on their own line, or after 74the email address.