git-check-mailmap

Look up the canonical name associated with an email address

$ git check-mailmap "<[email@example.com]>"

git check-mailmap [--stdin] [--] [mailmap…]

--stdin
    Read the first mailmap from standard input instead of files.

git check-mailmap is a Git command that validates mailmap files by ensuring they correctly map identities (names and email addresses) from repository commits to canonical forms without ambiguities or omissions. It simulates Git's mailmap normalization process, scanning all author and committer identities across the entire repository history.

By default, it uses Git's standard mailmap locations: .mailmap in the working tree and $GIT_DIR/mailmap. The command identifies and reports three main issues:
• Unmapped identities: Repository identities not covered by any mailmap entry.
• Ambiguous canonicals: Multiple distinct identities mapping to the same canonical name/email.
• Invalid entries: Malformed lines in the mailmap file.

This helps maintain clean authorship attribution in tools like git shortlog or git log --pretty=short. Output includes categorized warnings with examples, making it easy to fix mailmap issues. It's particularly useful before publishing repositories or generating contributor lists.

Only checks identities present in commits; does not validate future use. Mailmap files override defaults when specified. Reports warnings but continues unless fatal parse errors occur.

Warnings grouped as:
• Identities not mapped
• Canonical identities with multiples
• Invalid mailmap lines

0: All checks pass.
1: Warnings issued.

Introduced in Git 2.44.0 (December 2023) to aid mailmap maintenance, evolving from contrib scripts for better core integration.

shortlog(1)