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