| Junio C Hamano | 7887f9b | 2021-01-25 23:32:33 | [diff] [blame] | 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_TREE/.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 | The '#' character begins a comment to the end of line, blank lines |
| 27 | are ignored. |
| 28 | |
| 29 | In the simple form, each line in the file consists of the canonical |
| 30 | real name of an author, whitespace, and an email address used in the |
| 31 | commit (enclosed by '<' and '>') to map to the name. For example: |
| 32 | -- |
| 33 | Proper Name <commit@email.xx> |
| 34 | -- |
| 35 | |
| 36 | The more complex forms are: |
| 37 | -- |
| 38 | <proper@email.xx> <commit@email.xx> |
| 39 | -- |
| 40 | which allows mailmap to replace only the email part of a commit, and: |
| 41 | -- |
| 42 | Proper Name <proper@email.xx> <commit@email.xx> |
| 43 | -- |
| 44 | which allows mailmap to replace both the name and the email of a |
| 45 | commit matching the specified commit email address, and: |
| 46 | -- |
| 47 | Proper Name <proper@email.xx> Commit Name <commit@email.xx> |
| 48 | -- |
| 49 | which allows mailmap to replace both the name and the email of a |
| 50 | commit matching both the specified commit name and email address. |
| 51 | |
| 52 | Both E-Mails and names are matched case-insensitively. For example |
| Junio C Hamano | a372d5b | 2021-02-26 01:34:37 | [diff] [blame] | 53 | this would also match the 'Commit Name <commit@email.xx>' above: |
| Junio C Hamano | 7887f9b | 2021-01-25 23:32:33 | [diff] [blame] | 54 | -- |
| Junio C Hamano | a372d5b | 2021-02-26 01:34:37 | [diff] [blame] | 55 | Proper Name <proper@email.xx> CoMmIt NaMe <CoMmIt@EmAiL.xX> |
| Junio C Hamano | 7887f9b | 2021-01-25 23:32:33 | [diff] [blame] | 56 | -- |
| 57 | |
| Junio C Hamano | 51a55bc | 2021-05-12 05:22:19 | [diff] [blame] | 58 | NOTES |
| 59 | ----- |
| 60 | |
| 61 | Git does not follow symbolic links when accessing a `.mailmap` file in |
| 62 | the working tree. This keeps behavior consistent when the file is |
| 63 | accessed from the index or a tree versus from the filesystem. |
| 64 | |
| Junio C Hamano | 7887f9b | 2021-01-25 23:32:33 | [diff] [blame] | 65 | EXAMPLES |
| 66 | -------- |
| 67 | |
| 68 | Your history contains commits by two authors, Jane |
| 69 | and Joe, whose names appear in the repository under several forms: |
| 70 | |
| 71 | ------------ |
| 72 | Joe Developer <joe@example.com> |
| 73 | Joe R. Developer <joe@example.com> |
| 74 | Jane Doe <jane@example.com> |
| 75 | Jane Doe <jane@laptop.(none)> |
| 76 | Jane D. <jane@desktop.(none)> |
| 77 | ------------ |
| 78 | |
| 79 | Now suppose that Joe wants his middle name initial used, and Jane |
| 80 | prefers her family name fully spelled out. A `.mailmap` file to |
| 81 | correct the names would look like: |
| 82 | |
| 83 | ------------ |
| 84 | Joe R. Developer <joe@example.com> |
| 85 | Jane Doe <jane@example.com> |
| 86 | Jane Doe <jane@desktop.(none)> |
| 87 | ------------ |
| 88 | |
| Junio C Hamano | a372d5b | 2021-02-26 01:34:37 | [diff] [blame] | 89 | Note that there's no need to map the name for '<jane@laptop.(none)>' to |
| Junio C Hamano | 7887f9b | 2021-01-25 23:32:33 | [diff] [blame] | 90 | only correct the names. However, leaving the obviously broken |
| Junio C Hamano | a372d5b | 2021-02-26 01:34:37 | [diff] [blame] | 91 | '<jane@laptop.(none)>' and '<jane@desktop.(none)>' E-Mails as-is is |
| Junio C Hamano | 7887f9b | 2021-01-25 23:32:33 | [diff] [blame] | 92 | usually not what you want. A `.mailmap` file which also corrects those |
| 93 | is: |
| 94 | |
| 95 | ------------ |
| 96 | Joe R. Developer <joe@example.com> |
| 97 | Jane Doe <jane@example.com> <jane@laptop.(none)> |
| 98 | Jane Doe <jane@example.com> <jane@desktop.(none)> |
| 99 | ------------ |
| 100 | |
| 101 | Finally, let's say that Joe and Jane shared an E-Mail address, but not |
| 102 | a name, e.g. by having these two commits in the history generated by a |
| 103 | bug reporting system. I.e. names appearing in history as: |
| 104 | |
| 105 | ------------ |
| 106 | Joe <bugs@example.com> |
| 107 | Jane <bugs@example.com> |
| 108 | ------------ |
| 109 | |
| 110 | A full `.mailmap` file which also handles those cases (an addition of |
| 111 | two lines to the above example) would be: |
| 112 | |
| 113 | ------------ |
| 114 | Joe R. Developer <joe@example.com> |
| 115 | Jane Doe <jane@example.com> <jane@laptop.(none)> |
| 116 | Jane Doe <jane@example.com> <jane@desktop.(none)> |
| 117 | Joe R. Developer <joe@example.com> Joe <bugs@example.com> |
| 118 | Jane Doe <jane@example.com> Jane <bugs@example.com> |
| 119 | ------------ |
| 120 | |
| 121 | |
| 122 | |
| 123 | SEE ALSO |
| 124 | -------- |
| 125 | linkgit:git-check-mailmap[1] |
| 126 | |
| 127 | |
| 128 | GIT |
| 129 | --- |
| 130 | Part of the linkgit:git[1] suite |
