git mailmap (.mailmap): Usage & Common CI Errors

A .mailmap file maps a contributor’s many names/emails to one canonical identity in git output.

Mailmap fixes split contributor lists in shortlog, log, and blame - essential for accurate release credits in CI.

What it does

A .mailmap file at the repo root tells Git to rewrite author/committer names and emails consistently in log, shortlog, and blame, so one person’s commits group together regardless of the identity they used.

Common usage

.mailmap

# .mailmap format:
Proper Name <proper@email.com> <old@email.com>
Proper Name <proper@email.com> Old Name <old@email.com>

# verify a mapping:
git check-mailmap "Old Name <old@email.com>"
git shortlog -sne   # now grouped by canonical identity

Options

Entry form	Effect
<canonical> <commit-email>	Map an email to a canonical email
Name <canonical> <commit-email>	Also fix the display name
Name <canonical> Old <commit-email>	Match by both name and email

Common errors in CI

Contributor counts look wrong because the same person used several emails - add them to .mailmap. If mappings seem ignored, confirm the file is named .mailmap at the repo root (or set mailmap.file), and that the tool reading it honors mailmap (log/shortlog/blame do).

Related guides

git shortlog: Usage, Options & Common CI Errorsgit shortlog summarizes commits grouped by author, perfect for changelogs and release notes. Reference for -s… git log: Usage, Options & Common CI Errorsgit log shows commit history with flexible formatting. Reference for --oneline, --graph, --pretty, ranges, an… git blame: Usage, Options & Common CI Errorsgit blame shows which commit and author last changed each line of a file. Reference for -L, -C, --since, and… git config: Usage, Options & Common CI Errorsgit config gets and sets Git configuration at system, global, and local scope. Reference for --global, --get,…