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.
Proper Name <[email protected]> <[email protected]>
Try it
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.
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
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,
%anand%aestay 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 --mailmapandgit check-mailmap. git logneeds opt-in. Recent Git versions enablelog.mailmapby 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
.mailmapmakes everyone's tools agree; external services such as GitHub use it for contributor statistics only in some views.