Skip to content

Enforce a canonical author identity via .mailmap

This is a principle

A reusable technical claim: something I would want true in any of my work.

Claim. Map every contributor's name/email variants to one canonical identity in a .mailmap, and check it mechanically so new unmapped identities can't creep in.

When to apply. Situational - multi-contributor repos, or any project where clean attribution/history matters (shortlog, changelog generation). Overkill for a solo throwaway repo.

Why. People commit under several names and emails (work laptop, personal machine, web edits), which fragments git shortlog, contributor counts and changelog attribution. A .mailmap collapses the variants to one identity; a CI check that flags any commit author missing from it keeps the map complete over time instead of silently rotting.

Snippet.

# .mailmap
Proper Name <canonical@example.com> <old-or-alt@example.com>

How enforced. A .mailmap plus a guard that scans git log for authors absent from it (a case of Guard invariants at commit-time, not review-time). Mark this one situational: enforce only where attribution quality is worth the friction.

The following pages link to this page: