| '\" t |
| .\" Title: gitmailmap |
| .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author] |
| .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> |
| .\" Date: 05/06/2022 |
| .\" Manual: Git Manual |
| .\" Source: Git 2.36.1.19.ge8005e4871 |
| .\" Language: English |
| .\" |
| .TH "GITMAILMAP" "5" "05/06/2022" "Git 2\&.36\&.1\&.19\&.ge8005e4" "Git Manual" |
| .\" ----------------------------------------------------------------- |
| .\" * Define some portability stuff |
| .\" ----------------------------------------------------------------- |
| .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| .\" http://bugs.debian.org/507673 |
| .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html |
| .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| .ie \n(.g .ds Aq \(aq |
| .el .ds Aq ' |
| .\" ----------------------------------------------------------------- |
| .\" * set default formatting |
| .\" ----------------------------------------------------------------- |
| .\" disable hyphenation |
| .nh |
| .\" disable justification (adjust text to left margin only) |
| .ad l |
| .\" ----------------------------------------------------------------- |
| .\" * MAIN CONTENT STARTS HERE * |
| .\" ----------------------------------------------------------------- |
| .SH "NAME" |
| gitmailmap \- Map author/committer names and/or E\-Mail addresses |
| .SH "SYNOPSIS" |
| .sp |
| $GIT_WORK_TREE/\&.mailmap |
| .SH "DESCRIPTION" |
| .sp |
| 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\&. |
| .SH "SYNTAX" |
| .sp |
| The \fI#\fR character begins a comment to the end of line, blank lines are ignored\&. |
| .sp |
| 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: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| Proper Name <commit@email\&.xx> |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| The more complex forms are: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| <proper@email\&.xx> <commit@email\&.xx> |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| which allows mailmap to replace only the email part of a commit, and: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| Proper Name <proper@email\&.xx> <commit@email\&.xx> |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| which allows mailmap to replace both the name and the email of a commit matching the specified commit email address, and: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| Proper Name <proper@email\&.xx> Commit Name <commit@email\&.xx> |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| which allows mailmap to replace both the name and the email of a commit matching both the specified commit name and email address\&. |
| .sp |
| Both E\-Mails and names are matched case\-insensitively\&. For example this would also match the \fICommit Name <commit@email\&.xx>\fR above: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| Proper Name <proper@email\&.xx> CoMmIt NaMe <CoMmIt@EmAiL\&.xX> |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .SH "NOTES" |
| .sp |
| 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\&. |
| .SH "EXAMPLES" |
| .sp |
| Your history contains commits by two authors, Jane and Joe, whose names appear in the repository under several forms: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| Joe Developer <joe@example\&.com> |
| Joe R\&. Developer <joe@example\&.com> |
| Jane Doe <jane@example\&.com> |
| Jane Doe <jane@laptop\&.(none)> |
| Jane D\&. <jane@desktop\&.(none)> |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .sp |
| 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: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| Joe R\&. Developer <joe@example\&.com> |
| Jane Doe <jane@example\&.com> |
| Jane Doe <jane@desktop\&.(none)> |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .sp |
| 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: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| Joe R\&. Developer <joe@example\&.com> |
| Jane Doe <jane@example\&.com> <jane@laptop\&.(none)> |
| Jane Doe <jane@example\&.com> <jane@desktop\&.(none)> |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .sp |
| 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: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| Joe <bugs@example\&.com> |
| Jane <bugs@example\&.com> |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .sp |
| A full \fB\&.mailmap\fR file which also handles those cases (an addition of two lines to the above example) would be: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| Joe R\&. Developer <joe@example\&.com> |
| Jane Doe <jane@example\&.com> <jane@laptop\&.(none)> |
| Jane Doe <jane@example\&.com> <jane@desktop\&.(none)> |
| Joe R\&. Developer <joe@example\&.com> Joe <bugs@example\&.com> |
| Jane Doe <jane@example\&.com> Jane <bugs@example\&.com> |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .SH "SEE ALSO" |
| .sp |
| \fBgit-check-mailmap\fR(1) |
| .SH "GIT" |
| .sp |
| Part of the \fBgit\fR(1) suite |
