| blob | 3c907597d2b484b73f231b8d5a58cc69cff4fdda |
1 '\" t
2 .\" Title: gitmailmap
3 .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
5 .\" Date: 2024-02-19
6 .\" Manual: Git Manual
7 .\" Source: Git 2.44.0.rc2
8 .\" Language: English
9 .\"
10 .TH "GITMAILMAP" "5" "2024\-02\-19" "Git 2\&.44\&.0\&.rc2" "Git Manual"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 gitmailmap \- Map author/committer names and/or E\-Mail addresses
32 .SH "SYNOPSIS"
33 .sp
34 $GIT_WORK_TREE/\&.mailmap
35 .SH "DESCRIPTION"
36 .sp
37 If the file \fB\&.mailmap\fR exists at the toplevel of the repository, or at the location pointed to by the \fBmailmap\&.file\fR or \fBmailmap\&.blob\fR configuration options (see \fBgit-config\fR(1)), it is used to map author and committer names and email addresses to canonical real names and email addresses\&.
38 .SH "SYNTAX"
39 .sp
40 The \fI#\fR character begins a comment to the end of line, blank lines are ignored\&.
41 .sp
42 In the simple form, each line in the file consists of the canonical real name of an author, whitespace, and an email address used in the commit (enclosed by \fI<\fR and \fI>\fR) to map to the name\&. For example:
43 .sp
44 .if n \{\
45 .RS 4
46 .\}
47 .nf
48 Proper Name <commit@email\&.xx>
49 .fi
50 .if n \{\
51 .RE
52 .\}
53 .sp
54 The more complex forms are:
55 .sp
56 .if n \{\
57 .RS 4
58 .\}
59 .nf
60 <proper@email\&.xx> <commit@email\&.xx>
61 .fi
62 .if n \{\
63 .RE
64 .\}
65 .sp
66 which allows mailmap to replace only the email part of a commit, and:
67 .sp
68 .if n \{\
69 .RS 4
70 .\}
71 .nf
72 Proper Name <proper@email\&.xx> <commit@email\&.xx>
73 .fi
74 .if n \{\
75 .RE
76 .\}
77 .sp
78 which allows mailmap to replace both the name and the email of a commit matching the specified commit email address, and:
79 .sp
80 .if n \{\
81 .RS 4
82 .\}
83 .nf
84 Proper Name <proper@email\&.xx> Commit Name <commit@email\&.xx>
85 .fi
86 .if n \{\
87 .RE
88 .\}
89 .sp
90 which allows mailmap to replace both the name and the email of a commit matching both the specified commit name and email address\&.
91 .sp
92 Both E\-Mails and names are matched case\-insensitively\&. For example this would also match the \fICommit Name <commit@email\&.xx>\fR above:
93 .sp
94 .if n \{\
95 .RS 4
96 .\}
97 .nf
98 Proper Name <proper@email\&.xx> CoMmIt NaMe <CoMmIt@EmAiL\&.xX>
99 .fi
100 .if n \{\
101 .RE
102 .\}
103 .SH "NOTES"
104 .sp
105 Git does not follow symbolic links when accessing a \fB\&.mailmap\fR file in the working tree\&. This keeps behavior consistent when the file is accessed from the index or a tree versus from the filesystem\&.
106 .SH "EXAMPLES"
107 .sp
108 Your history contains commits by two authors, Jane and Joe, whose names appear in the repository under several forms:
109 .sp
110 .if n \{\
111 .RS 4
112 .\}
113 .nf
114 Joe Developer <joe@example\&.com>
115 Joe R\&. Developer <joe@example\&.com>
116 Jane Doe <jane@example\&.com>
117 Jane Doe <jane@laptop\&.(none)>
118 Jane D\&. <jane@desktop\&.(none)>
119 .fi
120 .if n \{\
121 .RE
122 .\}
123 .sp
124 .sp
125 Now suppose that Joe wants his middle name initial used, and Jane prefers her family name fully spelled out\&. A \fB\&.mailmap\fR file to correct the names would look like:
126 .sp
127 .if n \{\
128 .RS 4
129 .\}
130 .nf
131 Joe R\&. Developer <joe@example\&.com>
132 Jane Doe <jane@example\&.com>
133 Jane Doe <jane@desktop\&.(none)>
134 .fi
135 .if n \{\
136 .RE
137 .\}
138 .sp
139 .sp
140 Note that there\(cqs no need to map the name for \fI<jane@laptop\&.(none)>\fR to only correct the names\&. However, leaving the obviously broken \fI<jane@laptop\&.(none)>\fR and \fI<jane@desktop\&.(none)>\fR E\-Mails as\-is is usually not what you want\&. A \fB\&.mailmap\fR file which also corrects those is:
141 .sp
142 .if n \{\
143 .RS 4
144 .\}
145 .nf
146 Joe R\&. Developer <joe@example\&.com>
147 Jane Doe <jane@example\&.com> <jane@laptop\&.(none)>
148 Jane Doe <jane@example\&.com> <jane@desktop\&.(none)>
149 .fi
150 .if n \{\
151 .RE
152 .\}
153 .sp
154 .sp
155 Finally, let\(cqs say that Joe and Jane shared an E\-Mail address, but not a name, e\&.g\&. by having these two commits in the history generated by a bug reporting system\&. I\&.e\&. names appearing in history as:
156 .sp
157 .if n \{\
158 .RS 4
159 .\}
160 .nf
161 Joe <bugs@example\&.com>
162 Jane <bugs@example\&.com>
163 .fi
164 .if n \{\
165 .RE
166 .\}
167 .sp
168 .sp
169 A full \fB\&.mailmap\fR file which also handles those cases (an addition of two lines to the above example) would be:
170 .sp
171 .if n \{\
172 .RS 4
173 .\}
174 .nf
175 Joe R\&. Developer <joe@example\&.com>
176 Jane Doe <jane@example\&.com> <jane@laptop\&.(none)>
177 Jane Doe <jane@example\&.com> <jane@desktop\&.(none)>
178 Joe R\&. Developer <joe@example\&.com> Joe <bugs@example\&.com>
179 Jane Doe <jane@example\&.com> Jane <bugs@example\&.com>
180 .fi
181 .if n \{\
182 .RE
183 .\}
184 .sp
185 .SH "SEE ALSO"
186 .sp
187 \fBgit-check-mailmap\fR(1)
188 .SH "GIT"
189 .sp
190 Part of the \fBgit\fR(1) suite