Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Files and Formats

The .mailmap file

Reference for the .mailmap file: the four line formats, how git log, shortlog, blame and check-mailmap apply it, and the mailmap.file and mailmap.blob settings.

A .mailmap file maps the names and email addresses stored in commits to the identities you want to display. People change their names, use several addresses, or commit with a misconfigured machine. History cannot be rewritten without changing every hash, but a mailmap fixes the display: git shortlog, git blame, git log with the %aN/%aE placeholders and other tools show the canonical identity.

The file lives at the top of the working tree and is committed like any other file. It never alters stored commits.

Terminal
Proper Name <[email protected]> <[email protected]>

Try it

Bash Merge two identities in shortlog

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash All four formats and check-mailmap

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
Proper Name <proper@email>                         # 1: fix a name
<proper@email> <commit@email>                      # 2: fix an email
Proper Name <proper@email> <commit@email>          # 3: fix both, matched by email
Proper Name <proper@email> Commit Name <commit@email>   # 4: matched by name and email
Form Meaning
1 Any commit using <proper@email> shows Proper Name.
2 Commits with <commit@email> show <proper@email>; the name is unchanged.
3 Commits with <commit@email> show both the proper name and email.
4 Only commits matching both the commit name and email are rewritten in display. Lets one shared address belong to two people.

Lines starting with # are comments. Email matching is case-insensitive. Name matching in form 4 is case-sensitive.

Where it is read: .mailmap in the working tree, the file named by mailmap.file, and the blob named by mailmap.blob (useful in bare repositories, where there is no working tree).

Usage notes

  • Display only. Raw hashes, %an and %ae stay unchanged. Use %aN/%aE (capital) for mapped values.
  • Commands that honor it: git shortlog, git blame, git log (with the capital placeholders or --use-mailmap), git cat-file --mailmap and git check-mailmap.
  • git log needs opt-in. Recent Git versions enable log.mailmap by default; on older ones set it, or pass --use-mailmap.
  • Debug with git check-mailmap. It prints the result for a name and email pair, as in the example.
  • Privacy use. A mailmap is a good way to hide an old private address from displayed history, but the original is still in the commit objects and in every clone.
  • Conventions. Put the canonical identity first; keep the file sorted by canonical name.
  • Check it in. The committed .mailmap makes everyone's tools agree; external services such as GitHub use it for contributor statistics only in some views.