git check-mailmap

Apply .mailmap to a name to see the canonical form.

🎯 What & why

Applies your repository's .mailmap to a name/email and prints the canonical form. Lets you confirm that 'jdoe <jd@old.com>' really is being collapsed into 'Jane Doe <jane@new.org>' before shortlog or blame surprise you.

🧠 Mental model

Plumbing wrapper around the same lookup that log/shortlog/blame use when mailmap is in effect. .mailmap is a flat text file in the repo root (or wherever mailmap.file points) mapping commit identities to canonical ones; check-mailmap is just 'run that mapping and show me the result'.

🛠️ Synopsis

git check-mailmap [<options>] <contact>...

Each <contact> is either 'Name <email>' or '<email>'. With --stdin,
read one contact per line from standard input. Output is the canonical
form, one per input, in order. Useful for sanity-checking .mailmap
edits without running a full shortlog.

🎚️ Switches & options

Flag	What it does
`--stdin`	Read contacts from stdin, one per line. Pipe `git log --pretty=format:'%an <%ae>'` into it to see how every author would be rewritten.

💡 Use cases

Verify a new .mailmap entry rewrites the identity you intended before relying on it in release notes.
Audit author de-duplication across a repo: pipe all distinct '%an <%ae>' lines through it and diff against the originals.
Debug why git shortlog -sn still shows two entries for what you thought was one person.
Generate a 'canonical contributors' list for AUTHORS or CONTRIBUTORS files.

🧪 Examples

Single lookup

git check-mailmap 'Jane D <jd@old.example>'

Email-only form

git check-mailmap '<jd@old.example>'

Audit every author

git log --pretty=format:'%an <%ae>' | sort -u | git check-mailmap --stdin

Spot identities with no mapping

git log --pretty='%an <%ae>' | sort -u | git check-mailmap --stdin | sort -u

🎓 Recommendations

Keep .mailmap at the repo root — that's the default and what most tooling expects. Override with mailmap.file only if you have a reason.
Prefer the four-field form 'Proper Name <proper@email> Commit Name <commit@email>' in .mailmap; it's the most precise and supports name-only or email-only rewrites.
Run check-mailmap whenever you edit .mailmap; a missing '<' or stray comment will silently break a rule.

🪤 Common pitfalls

.mailmap only takes effect for commands that opt in (log/shortlog/blame do; raw plumbing like cat-file doesn't). Don't expect it to alter commit data on disk.
If both name and email are provided in .mailmap, both must match exactly (case-insensitive on email) for the rule to fire.
mailmap.blob lets you ship the mapping outside the working tree; if it's set and stale, check-mailmap will use it and confuse you.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.