mailmap-checker 0.2.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.

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]>. The .mailmap format places the canonical (left) and the alias (right) on each line. 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]>

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.

# Preview
mailmap-checker fix --dry-run

# Apply
mailmap-checker fix

All commands accept --mailmap <path> to use a custom file path. When omitted, the tool checks git config mailmap.file first, then falls back to .mailmap in the repository root.

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