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