Documentation/mailmap.txt

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