Appearance
Git Mailmap: Author Identity Normalization for DevOps
git mailmap maps multiple author/committer identities belonging to the same person to a single canonical identity. For a DevOps engineer, it's the difference between a changelog that says "John D. contributed 47 commits" and one that lists "john.doe@corp.com, John Doe, jdoe, John D., john.doe@personal.com" as five separate people.
Without mailmap, release notes, contributor stats, blame audits, and compliance reports are all unreliable.
Why a DevOps engineer needs mailmap
| Problem | Without mailmap | With mailmap |
|---|---|---|
| Same person commits with different emails (work + personal) | Counted as separate contributors | Merged into one canonical identity |
| Developer changes email after acquisition/rename | Historical commits attributed to a ghost | All commits attributed to current identity |
| Bot/CI commits from different hosts with varying env | Bloats author lists with "jenkins-bot", "ci-runner-3", "deploy-svc" | Unified under "CI Pipeline" |
| Changelog generation for compliance audits | Names don't match HR records | Each contributor has one canonical name + email |
git shortlog -sn for sprint metrics | Inflated contributor counts, unreliable trend data | Accurate per-person commit counts |
How mailmap works
Git reads a .mailmap file from the repository root (or the mailmap.file / mailmap.blob config key) and rewrites Author and Committer fields in commands like git log, git shortlog, git blame, and git archive.
The mailmap file is a list of rewrite rules. Each line maps a non-canonical identity to a canonical one.
Canonical Name <canonical@email> <alternative@email>
Canonical Name <canonical@email> Alternative Name <alternative@email>Git matches from right to left: the right side is the "old" identity, the left side is the "new" one.
Line formats
# Canonical name + email replaces only email
Proper Name <proper@email> <wrong@email>
# Canonical name + email replaces both name and email
Proper Name <proper@email> Improper Name <wrong@email>
# Only name is replaced (email must match)
Proper Name <wrong@email>
# Blanket: any identity with this email gets the canonical name (use carefully)
<proper@email> <wrong@email>
# Comments start with #Match precedence
Git tries right-side matches in this order:
- Both name and email match (most specific)
- Only email matches
- Only name matches (rarely used — email is the primary key)
If no rule matches, the original identity is displayed unchanged.
Setting up mailmap
Option A: Committed .mailmap (recommended)
Check a .mailmap file into the repository root:
bash
cat > .mailmap << 'EOF'
# Canonical identities for release engineering
Alice Zhang <alice.zhang@company.com> <azhang@personal.com>
Alice Zhang <alice.zhang@company.com> alice_dev <alice@dev.local>
Bob Chen <bob.chen@company.com> <bob.chen@acq-hire-2022.io>
Bob Chen <bob.chen@company.com> Bob C <bob.chen@legacy-domain.com>
CI Pipeline <ci@company.com> <jenkins@build-01.company.com>
CI Pipeline <ci@company.com> <runner@gha-ubuntu-latest.local>
EOFThis is the best option for teams. Every clone gets the same rules, and changes are reviewed through PRs.
Option B: Blob reference (for CI runners)
Point to a mailmap blob that lives outside the working tree:
bash
# Store mailmap as a git object
MAILMAP_BLOB=$(git hash-object -w .mailmap)
# Reference it in config
git config mailmap.blob "$MAILMAP_BLOB"This decouples the mailmap config from the checked-out files. Useful when .mailmap would interfere with directory-based tooling.
Option C: External file (for local or CI-only overrides)
bash
# Point to a file outside the repo
git config mailmap.file /etc/git/mailmap
# Or per-repo
git config mailmap.file "$(pwd)/.mailmap-override"Using mailmap in DevOps pipelines
1. Changelog generation with accurate attribution
bash
# Before mailmap: fragmented authors
git shortlog -sn v1.0..v2.0
# 12 Alice Zhang
# 8 azhang@personal.com
# 5 alice_dev
# 3 Bob Chen
# 3 Bob C
# 2 jenkins@build-01
# After mailmap: unified
git shortlog -sn v1.0..v2.0
# 25 Alice Zhang
# 6 Bob Chen
# 2 CI Pipeline2. Blame with clean identities
bash
# Without mailmap, blame shows the commit-time identity
git blame src/deploy.sh
# azhang@personal.com (alice_dev, 2024-01-15) DEPLOY_ENV=prod
# With mailmap, it shows the canonical identity
git blame src/deploy.sh
# Alice Zhang (Alice Zhang, 2024-01-15) DEPLOY_ENV=prod3. Compliance audit reports
bash
# Generate a contributor roster for SOC 2 access review
git log --format='%aN <%aE>' --since='2024-01-01' --until='2024-12-31' | \
sort -u > raw-contributors.txt
# Same query with mailmap resolution
git -c mailmap.file=.mailmap log --format='%aN <%aE>' --since='2024-01-01' \
--until='2024-12-31' | sort -u > canonical-contributors.txt4. CI commit-count gates
bash
# Count unique contributors in a release range
CONTRIBUTORS=$(git shortlog -sn v1.0..v2.0 | wc -l)
echo "Contributors this release: $CONTRIBUTORS"
# Gate: reject if fewer than N distinct contributors (signals bus factor)
if [ "$CONTRIBUTORS" -lt 3 ]; then
echo "FAIL: Bus factor too high — only $CONTRIBUTORS contributors"
exit 1
fi5. Sprint velocity metrics
bash
# Reliable per-person commit counts for velocity tracking
git shortlog -sne --since='2024-03-01' --until='2024-03-31' > sprint-metrics.txt
# Format: CSV for ingestion into analytics
git shortlog -sne --since='2024-03-01' --until='2024-03-31' | \
sed 's/^[[:space:]]*//;s/[[:space:]]*$//;s/[[:space:]]\{1,\}/,/' | \
awk -F, '{print $2","$1}' | sort -t, -k2 -rn6. CI pipeline identity cleanup
When running CI pipelines, the committer identity varies by runner environment. Standardise it:
bash
# In CI pipeline setup step
cat > .mailmap << EOF
CI Pipeline <ci@company.com> <runner@$(hostname)>
CI Pipeline <ci@company.com> <$(whoami)@$(hostname)>
CI Pipeline <ci@company.com> <bot@users.noreply.github.com>
EOF
git config mailmap.file "$(pwd)/.mailmap"7. Pre-commit hook to prevent identity drift
bash
#!/bin/bash
# .git/hooks/pre-commit — warn if author email doesn't match canonical list
CANONICAL_EMAILS="alice.zhang@company.com bob.chen@company.com ci@company.com"
AUTHOR_EMAIL=$(git config user.email)
if ! echo "$CANONICAL_EMAILS" | grep -q "$AUTHOR_EMAIL"; then
echo "WARNING: Author email '$AUTHOR_EMAIL' is not in the canonical list."
echo "Update your git config or add it to .mailmap."
echo "Canonical emails: $CANONICAL_EMAILS"
fiGenerating a mailmap from history
Bootstrapping a mailmap for an existing repo is tedious by hand. Use git log to extract every distinct author identity pair, then group them:
bash
# Extract all unique (name, email) pairs from history
git log --format='%aN||%aE' --all | sort -uFor initial bootstrapping, run the mailmap-manage.sh script:
bash
./scripts/mailmap-manage.sh bootstrap > .mailmap
# Review, deduplicate, and commitOr use a one-liner to detect likely duplicate emails (same local-part with different domains):
bash
git log --format='%aN||%aE' --all | sort -u | \
awk -F'\\|\\|' '{email=$2; gsub(/.*@/, "", email); print email, $0}' | \
sort | uniq -c | sort -rn | head -20Best practices
- Keep
.mailmapin the repo root. Committed mailmap is versioned, reviewed, and available to everyone. - Use canonical corporate email as the key. Prefer the identity in HR/Active Directory over personal emails.
- Group bot/CI identities early. Add a single "CI Pipeline" entry for all runner hostnames. Prevents thousands of unique bot identities from bloating stats.
- Review mailmap changes in code review. A mailmap entry can effectively rename a person across all history. Treat it with the same care as a code change.
- Combine with
.gitattributesexport-ignore. Exclude.mailmapfrom release archives if it contains personal email mappings. - Run
git shortlog -sneafter changes. Verify the merge worked as expected before committing. - CI validation gate. Add a pipeline step that checks
.mailmapparses correctly and canonicalizes at least N% of authors.
Mailmap + git log format placeholders
Mailmap-aware format specifiers (these apply mailmap rewriting):
| Specifier | Field | Without mailmap equivalent |
|---|---|---|
%aN | Author name (mailmap) | %an |
%aE | Author email (mailmap) | %ae |
%cN | Committer name (mailmap) | %cn |
%cE | Committer email (mailmap) | %ce |
Always use the capital-letter variants in CI scripts when mailmap is active.
Pitfalls
- Mailmap only affects display commands. It does not rewrite commit objects.
git log --format=%Hstill returns the original SHA. For actual history rewrites, usegit filter-repo --mailmap. - Case sensitivity. Email matching is case-sensitive.
User@Company.comanduser@company.comare different to mailmap unless both are listed. - Mailmap is not applied to
git log --raworgit diff. These show the on-disk identity from the commit object directly. - Shallow clones with
mailmap.blob. If the mailmap blob doesn't exist in the shallow history, Git falls back to no mailmap. Usemailmap.filefor CI runners with shallow clones. - Mailmap + signed commits. Mailmap rewrites the display, not the GPG signature. The signature still validates against the original identity. This is by design — mailmap is cosmetic, not cryptographic.
- Accidental over-matching. A rule like
<correct@email> <wrong@email>matches any author withwrong@emailregardless of name. Use the four-field form (Name <email> Name <email>) when you want to match both fields. - Mailmap is not inherited across forks. Each fork needs its own
.mailmapor must configuremailmap.fileglobally.
Mailmap vs filter-repo --mailmap
| Approach | Changes commit SHAs? | Scope | Use case |
|---|---|---|---|
.mailmap file | No | Cosmetic (display only) | Daily workflows, CI, changelogs |
git filter-repo --mailmap | Yes | Permanent history rewrite | Sanitizing public repos, pre-acquisition cleanup |
Use .mailmap for daily operations. Use filter-repo --mailmap only when you need to permanently rewrite identity data (e.g., removing personal emails before open-sourcing a repo).
Reference
git help mailmap— full format specificationgit shortlog -sne— mailmap-aware contributor summarygit log --use-mailmap— force mailmap on log output (enabled by default when.mailmapexists)git blame --use-mailmap— mailmap-aware blamegit config mailmap.file/mailmap.blob— custom mailmap sources