1If the file `.mailmap` exists at the toplevel of the repository, or at 2the location pointed to by the mailmap.file or mailmap.blob 3configuration options, it 4is used to map author and committer names and email addresses to 5canonical real names and email addresses. 6 7In the simple form, each line in the file consists of the canonical 8real name of an author, whitespace, and an email address used in the 9commit (enclosed by '<' and '>') to map to the name. For example: 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 there is no need for an entry for `<jane@laptop.(none)>`, because the 51real name of that author is already correct. 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 that looks 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.