oasis-root

gitmailmap.5 (5309B)

'\" t
.\"     Title: gitmailmap
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
.\"      Date: 2025-03-14
.\"    Manual: Git Manual
.\"    Source: Git 2.49.0
.\"  Language: English
.\"
.TH "GITMAILMAP" "5" "2025-03-14" "Git 2\&.49\&.0" "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 \&.\fBmailmap\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 \&.\fBmailmap\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
Now suppose that Joe wants his middle name initial used, and Jane prefers her family name fully spelled out\&. A \&.\fBmailmap\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
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 \&.\fBmailmap\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
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
A full \&.\fBmailmap\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
.\}
.SH "SEE ALSO"
.sp
\fBgit-check-mailmap\fR(1)
.SH "GIT"
.sp
Part of the \fBgit\fR(1) suite