| blob | 3437f1da28d1bed91a36bbc6afcd243565d73d2d |
1 '\" t
2 .\" Title: gitmailmap
3 .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
4 .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
5 .\" Date: 2024-09-30
6 .\" Manual: Git Manual
7 .\" Source: Git 2.47.0.rc0.18.ge9356ba3ea
8 .\" Language: English
9 .\"
10 .TH "GITMAILMAP" "5" "2024-09-30" "Git 2\&.47\&.0\&.rc0\&.18\&.ge" "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 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:
125 .sp
126 .if n \{\
127 .RS 4
128 .\}
129 .nf
130 Joe R\&. Developer <joe@example\&.com>
131 Jane Doe <jane@example\&.com>
132 Jane Doe <jane@desktop\&.(none)>
133 .fi
134 .if n \{\
135 .RE
136 .\}
137 .sp
138 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:
139 .sp
140 .if n \{\
141 .RS 4
142 .\}
143 .nf
144 Joe R\&. Developer <joe@example\&.com>
145 Jane Doe <jane@example\&.com> <jane@laptop\&.(none)>
146 Jane Doe <jane@example\&.com> <jane@desktop\&.(none)>
147 .fi
148 .if n \{\
149 .RE
150 .\}
151 .sp
152 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:
153 .sp
154 .if n \{\
155 .RS 4
156 .\}
157 .nf
158 Joe <bugs@example\&.com>
159 Jane <bugs@example\&.com>
160 .fi
161 .if n \{\
162 .RE
163 .\}
164 .sp
165 A full \fB\&.mailmap\fR file which also handles those cases (an addition of two lines to the above example) would be:
166 .sp
167 .if n \{\
168 .RS 4
169 .\}
170 .nf
171 Joe R\&. Developer <joe@example\&.com>
172 Jane Doe <jane@example\&.com> <jane@laptop\&.(none)>
173 Jane Doe <jane@example\&.com> <jane@desktop\&.(none)>
174 Joe R\&. Developer <joe@example\&.com> Joe <bugs@example\&.com>
175 Jane Doe <jane@example\&.com> Jane <bugs@example\&.com>
176 .fi
177 .if n \{\
178 .RE
179 .\}
180 .SH "SEE ALSO"
181 .sp
182 \fBgit-check-mailmap\fR(1)
183 .SH "GIT"
184 .sp
185 Part of the \fBgit\fR(1) suite