mailmap-checker 0.3.0

Pre-commit hook that checks and maintains .mailmap completeness

mailmap-checker

A pre-commit hook that detects unmapped Git identities by comparing your .mailmap against the full commit history. It groups authors and committers by email address and email local-part so duplicates are caught even across domain changes.

Follows the gitmailmap specification: all four mapping formats are supported, and both names and emails are matched case-insensitively.

How it works

The checker scans git log for all unique author and committer identities and groups them using two rules:

Rule 1 — Same email (case-insensitive)

Identities that share the exact same email address are the same person.

Alice Johnson <[e-mail]>
alice.j       <[e-mail]>   ← same email, grouped together

Rule 2 — Same email local-part (different domain)

Identities whose email local-part (the part before @) matches are likely the same person who changed companies or used a different address. Local-parts shorter than 8 characters are automatically skipped to reduce false positives.

Alice Johnson <[e-mail]>
Alice Johnson <[e-mail]>    ← same local-part, grouped
Alice J       <[e-mail]>   ← same local-part, grouped

Once groups are built, the checker looks for identities that are not mapped in .mailmap. If a group has more than one identity and any of them is missing from the file, the hook fails and reports the gap.

Example

Given these three identities in git history and an empty .mailmap:

Alice Johnson <[e-mail]>
Alice Johnson <[e-mail]>
Alice J       <[e-mail]>

mailmap-checker check detects the gap:

Found 2 unmapped identities in 1 group:

  Canonical: Alice J <[e-mail]>
    - Alice Johnson <[e-mail]>
    - Alice Johnson <[e-mail]>

mailmap-checker fix --dry-run suggests entries to add:

Suggested .mailmap entries:

  Alice J <[e-mail]> Alice Johnson <[e-mail]>
  Alice J <[e-mail]> Alice Johnson <[e-mail]>

Note: When no .mailmap exists, the tool picks the alphabetically first identity as the canonical. In this case it chose Alice J <[e-mail]>, but the actual preferred identity is likely Alice Johnson <[e-mail]>. After running fix, open .mailmap and swap the canonical if needed:

Alice Johnson <[e-mail]> Alice Johnson <[e-mail]>
Alice Johnson <[e-mail]> Alice J <[e-mail]>

Disabling local-part matching

If Rule 2 produces false positives on very large repositories, disable it with --no-local-part-matching.

Installation

Pre-commit hook (recommended)

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/cansarigol/mailmap-checker
    rev: ""  # run: pre-commit autoupdate
    hooks:
      - id: mailmap-check

Then run pre-commit autoupdate to pin the latest release.

Available hooks

Hook ID	Description
mailmap-check	Fail if any identity is missing from .mailmap
mailmap-fix	Automatically add missing entries to .mailmap
mailmap-fix-dry-run	Preview suggested entries without modifying the file

Standalone

pip install mailmap-checker

Usage

check

Scan all Git authors and committers and exit non-zero if any identity is missing from .mailmap.

mailmap-checker check

init

Create a .mailmap file (if it does not exist) and run a full check.

mailmap-checker init

fix

Preview or apply suggested .mailmap entries. New entries are inserted in sorted order (not appended at the end), and canonical groups are separated by blank lines.

The canonical identity for each group is chosen by preferring names that look like real person names (e.g. Alice Johnson) over usernames (alicej), git config artifacts (--global), or handle-style names (@username).

# Preview
mailmap-checker fix --dry-run

# Apply
mailmap-checker fix

Common options

Flag	Description
--mailmap <path>	Custom .mailmap file path (default: git config mailmap.file, then .mailmap)
--git-dir <path>	Path to git repository (default: current directory)
--no-local-part-matching	Disable grouping by email local-part across domains

Contributing

git clone https://github.com/cansarigol/mailmap-checker.git
cd mailmap-checker
uv sync
uv run poe setup   # installs pre-commit and commit-msg hooks
uv run poe check    # lint + security + tests

Commits must follow Conventional Commits with a required scope (e.g. feat(cli): add --verbose flag).

License

MIT