<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect2 SYSTEM "../../../dtd/dblite.dtd">

<sect2 lang="en" id="gitmailmap(5)">
    <title>gitmailmap(5)</title>
    <date>2024-07-02</date>
<revhistory><revision><date>2024-07-02</date></revision></revhistory>
<indexterm>
<primary>gitmailmap(5)</primary>
</indexterm>
<simplesect id="gitmailmap(5)__name">
<title>NAME</title>
<simpara>gitmailmap - Map author/committer names and/or E-Mail addresses</simpara>
</simplesect>
<simplesect id="gitmailmap(5)__synopsis">
<title>SYNOPSIS</title>
<simpara>$GIT_WORK_TREE/.mailmap</simpara>
</simplesect>
<simplesect id="gitmailmap(5)__description">
<title>DESCRIPTION</title>
<simpara>If the file <emphasis>.mailmap</emphasis> exists at the toplevel of the repository, or at
the location pointed to by the <emphasis>mailmap.file</emphasis> or <emphasis>mailmap.blob</emphasis>
configuration options (see <xref linkend="git-config(1)" />), it
is used to map author and committer names and email addresses to
canonical real names and email addresses.</simpara>
</simplesect>
<simplesect id="gitmailmap(5)__syntax">
<title>SYNTAX</title>
<simpara>The <emphasis>#</emphasis> character begins a comment to the end of line, blank lines
are ignored.</simpara>
<simpara>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 <emphasis>&lt;</emphasis> and <emphasis>&gt;</emphasis>) to map to the name. For example:</simpara>
<literallayout class="monospaced">Proper Name &lt;commit@email.xx&gt;</literallayout>
<simpara>The more complex forms are:</simpara>
<literallayout class="monospaced">&lt;proper@email.xx&gt; &lt;commit@email.xx&gt;</literallayout>
<simpara>which allows mailmap to replace only the email part of a commit, and:</simpara>
<literallayout class="monospaced">Proper Name &lt;proper@email.xx&gt; &lt;commit@email.xx&gt;</literallayout>
<simpara>which allows mailmap to replace both the name and the email of a
commit matching the specified commit email address, and:</simpara>
<literallayout class="monospaced">Proper Name &lt;proper@email.xx&gt; Commit Name &lt;commit@email.xx&gt;</literallayout>
<simpara>which allows mailmap to replace both the name and the email of a
commit matching both the specified commit name and email address.</simpara>
<simpara>Both E-Mails and names are matched case-insensitively. For example
this would also match the <emphasis>Commit Name &lt;commit&#64;email.xx&gt;</emphasis> above:</simpara>
<literallayout class="monospaced">Proper Name &lt;proper@email.xx&gt; CoMmIt NaMe &lt;CoMmIt@EmAiL.xX&gt;</literallayout>
</simplesect>
<simplesect id="gitmailmap(5)__notes">
<title>NOTES</title>
<simpara>Git does not follow symbolic links when accessing a <emphasis>.mailmap</emphasis> file in
the working tree. This keeps behavior consistent when the file is
accessed from the index or a tree versus from the filesystem.</simpara>
</simplesect>
<simplesect id="gitmailmap(5)__examples">
<title>EXAMPLES</title>
<simpara>Your history contains commits by two authors, Jane
and Joe, whose names appear in the repository under several forms:</simpara>
<screen>Joe Developer &lt;joe@example.com&gt;
Joe R. Developer &lt;joe@example.com&gt;
Jane Doe &lt;jane@example.com&gt;
Jane Doe &lt;jane@laptop.(none)&gt;
Jane D. &lt;jane@desktop.(none)&gt;</screen>
<simpara>Now suppose that Joe wants his middle name initial used, and Jane
prefers her family name fully spelled out. A <emphasis>.mailmap</emphasis> file to
correct the names would look like:</simpara>
<screen>Joe R. Developer &lt;joe@example.com&gt;
Jane Doe &lt;jane@example.com&gt;
Jane Doe &lt;jane@desktop.(none)&gt;</screen>
<simpara>Note that there's no need to map the name for <emphasis>&lt;jane&#64;laptop.(none)&gt;</emphasis> to
only correct the names. However, leaving the obviously broken
<emphasis>&lt;jane&#64;laptop.(none)&gt;</emphasis> and <emphasis>&lt;jane&#64;desktop.(none)&gt;</emphasis> E-Mails as-is is
usually not what you want. A <emphasis>.mailmap</emphasis> file which also corrects those
is:</simpara>
<screen>Joe R. Developer &lt;joe@example.com&gt;
Jane Doe &lt;jane@example.com&gt; &lt;jane@laptop.(none)&gt;
Jane Doe &lt;jane@example.com&gt; &lt;jane@desktop.(none)&gt;</screen>
<simpara>Finally, let's 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:</simpara>
<screen>Joe &lt;bugs@example.com&gt;
Jane &lt;bugs@example.com&gt;</screen>
<simpara>A full <emphasis>.mailmap</emphasis> file which also handles those cases (an addition of
two lines to the above example) would be:</simpara>
<screen>Joe R. Developer &lt;joe@example.com&gt;
Jane Doe &lt;jane@example.com&gt; &lt;jane@laptop.(none)&gt;
Jane Doe &lt;jane@example.com&gt; &lt;jane@desktop.(none)&gt;
Joe R. Developer &lt;joe@example.com&gt; Joe &lt;bugs@example.com&gt;
Jane Doe &lt;jane@example.com&gt; Jane &lt;bugs@example.com&gt;</screen>
</simplesect>
<simplesect id="gitmailmap(5)__see_also">
<title>SEE ALSO</title>
<simpara><xref linkend="git-check-mailmap(1)" /></simpara>
</simplesect>
<simplesect id="gitmailmap(5)__git">
<title>GIT</title>
<simpara>Part of the <xref linkend="git(1)" /> suite</simpara>
</simplesect>
</sect2>
