.mailmap Tester

Nine times out of ten the entry is the fourth form and the name does not match. Jane Doe <jane@corp.example> jane <ci@build.example> only catches commits whose author name is exactly jane (case aside) — a commit from the same address under release-bot is untouched, because a name-keyed entry that misses falls back to the plain entry for that address, and there may not be one. Drop the Commit Name part and the line catches every commit from that address instead. The other common causes are an address that never appears in the history at all (check with git log --format='%an <%ae>' | sort -u, and watch for +tag forms and GitHub users.noreply addresses), and a .mailmap that is not at the top level of the working tree, where git looks for it.

How they are looked up, and how much they replace. The first three are filed under the commit address alone: Proper Name <commit@x> replaces the name, <proper@x> <commit@x> replaces the address and keeps whatever name the commit had, and Proper Name <proper@x> <commit@x> replaces both. The fourth adds a name in front of the commit address, and is filed under that name as well, so it applies only to commits that match on both halves. When both kinds exist for one address, git tries the name-keyed table first and uses the plain entry as the fallback — in whichever order you wrote them, since the file is a map, not a script.

It does not. The lookup runs once per identity and the result is never fed back in, so an identity at A comes out at B and stops there, even though B is the key of another entry sitting in the same file. This bites when a file grows over years: someone folds an old laptop address into a work address, then later folds that work address into a personal one, and the first group never follows. The fix is to point every entry at the final identity directly. This tester flags any entry whose canonical address is itself a key elsewhere.

Neither half of the key is: addresses and names are both compared without case, so <OLD@EXAMPLE.COM> in a commit matches an entry written <old@example.com>, and a fourth-form entry keyed on Old Name also catches OLD NAME. Everything else about the name is literal, though. Two Spaces with two spaces does not match Two Spaces with one, and git does not trim what comes before a name on the identity line — an indented identity keeps that indentation as part of its name and stops matching a name-keyed entry. Inside the angle brackets nothing is trimmed either, so < old@x > is a key with spaces in it that no commit will ever have.

Both, partly. git keeps one canonical name and one canonical address per commit address, and each entry writes only the fields it carries, so Alpha <alpha@x> <dup@x> followed by <beta@x> <dup@x> resolves to Alpha <beta@x> — a name from the first line and an address from the second, an identity that appears nowhere in the file. Only a later entry carrying the same field overwrites it. That is why a duplicated address can leave a line in the file that quietly contributes nothing, and why this tester marks a row whose name and address came from different lines.

No. It is read at display time, from the working tree of the repository you are standing in, and applied by git log, git shortlog, git blame, git check-mailmap and anything run with --use-mailmap or with log.mailmap set. The author recorded in each commit object is untouched, which is the point: correcting a name this way costs nothing and breaks no signatures, while rewriting history changes every commit id below the change. The flip side is that the file only works where it is checked out — a forge that builds its own contributor list, GitHub included, does not consult it.