Documentation/gitmailmap.txt

   1 gitmailmap(5)
   2 =============
   3
   4 NAME
   5 ----
   6 gitmailmap - Map author/committer names and/or E-Mail addresses
   7
   8 SYNOPSIS
   9 --------
  10 $GIT_WORK_DIR/.mailmap
  11
  12
  13 DESCRIPTION
  14 -----------
  15
  16 If the file `.mailmap` exists at the toplevel of the repository, or at
  17 the location pointed to by the `mailmap.file` or `mailmap.blob`
  18 configuration options (see linkgit:git-config[1]), it
  19 is used to map author and committer names and email addresses to
  20 canonical real names and email addresses.
  21
  22
  23 SYNTAX
  24 ------
  25
  26 In the simple form, each line in the file consists of the canonical
  27 real name of an author, whitespace, and an email address used in the
  28 commit (enclosed by '<' and '>') to map to the name. For example:
  29 --
  30         Proper Name <commit@email.xx>
  31 --
  32
  33 The more complex forms are:
  34 --
  35         <proper@email.xx> <commit@email.xx>
  36 --
  37 which allows mailmap to replace only the email part of a commit, and:
  38 --
  39         Proper Name <proper@email.xx> <commit@email.xx>
  40 --
  41 which allows mailmap to replace both the name and the email of a
  42 commit matching the specified commit email address, and:
  43 --
  44         Proper Name <proper@email.xx> Commit Name <commit@email.xx>
  45 --
  46 which allows mailmap to replace both the name and the email of a
  47 commit matching both the specified commit name and email address.
  48
  49
  50 EXAMPLES
  51 --------
  52
  53 Example 1: Your history contains commits by two authors, Jane
  54 and Joe, whose names appear in the repository under several forms:
  55
  56 ------------
  57 Joe Developer <joe@example.com>
  58 Joe R. Developer <joe@example.com>
  59 Jane Doe <jane@example.com>
  60 Jane Doe <jane@laptop.(none)>
  61 Jane D. <jane@desktop.(none)>
  62 ------------
  63
  64 Now suppose that Joe wants his middle name initial used, and Jane
  65 prefers her family name fully spelled out. A proper `.mailmap` file
  66 would look like:
  67
  68 ------------
  69 Jane Doe         <jane@desktop.(none)>
  70 Joe R. Developer <joe@example.com>
  71 ------------
  72
  73 Note how there is no need for an entry for `<jane@laptop.(none)>`, because the
  74 real name of that author is already correct.
  75
  76 Example 2: Your repository contains commits from the following
  77 authors:
  78
  79 ------------
  80 nick1 <bugs@company.xx>
  81 nick2 <bugs@company.xx>
  82 nick2 <nick2@company.xx>
  83 santa <me@company.xx>
  84 claus <me@company.xx>
  85 CTO <cto@coompany.xx>
  86 ------------
  87
  88 Then you might want a `.mailmap` file that looks like:
  89 ------------
  90 <cto@company.xx>                       <cto@coompany.xx>
  91 Some Dude <some@dude.xx>         nick1 <bugs@company.xx>
  92 Other Author <other@author.xx>   nick2 <bugs@company.xx>
  93 Other Author <other@author.xx>         <nick2@company.xx>
  94 Santa Claus <santa.claus@northpole.xx> <me@company.xx>
  95 ------------
  96
  97 Use hash '#' for comments that are either on their own line, or after
  98 the email address.
  99
 100
 101 SEE ALSO
 102 --------
 103 linkgit:git-check-mailmap[1]
 104
 105
 106 GIT
 107 ---
 108 Part of the linkgit:git[1] suite