Skip to content

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 ​

ProblemWithout mailmapWith mailmap
Same person commits with different emails (work + personal)Counted as separate contributorsMerged into one canonical identity
Developer changes email after acquisition/renameHistorical commits attributed to a ghostAll commits attributed to current identity
Bot/CI commits from different hosts with varying envBloats author lists with "jenkins-bot", "ci-runner-3", "deploy-svc"Unified under "CI Pipeline"
Changelog generation for compliance auditsNames don't match HR recordsEach contributor has one canonical name + email
git shortlog -sn for sprint metricsInflated contributor counts, unreliable trend dataAccurate 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:

  1. Both name and email match (most specific)
  2. Only email matches
  3. Only name matches (rarely used — email is the primary key)

If no rule matches, the original identity is displayed unchanged.

Setting up mailmap ​

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>
EOF

This 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 Pipeline

2. 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=prod

3. 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.txt

4. 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
fi

5. 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 -rn

6. 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"
fi

Generating 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 -u

For initial bootstrapping, run the mailmap-manage.sh script:

bash
./scripts/mailmap-manage.sh bootstrap > .mailmap
# Review, deduplicate, and commit

Or 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 -20

Best practices ​

  1. Keep .mailmap in the repo root. Committed mailmap is versioned, reviewed, and available to everyone.
  2. Use canonical corporate email as the key. Prefer the identity in HR/Active Directory over personal emails.
  3. Group bot/CI identities early. Add a single "CI Pipeline" entry for all runner hostnames. Prevents thousands of unique bot identities from bloating stats.
  4. 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.
  5. Combine with .gitattributes export-ignore. Exclude .mailmap from release archives if it contains personal email mappings.
  6. Run git shortlog -sne after changes. Verify the merge worked as expected before committing.
  7. CI validation gate. Add a pipeline step that checks .mailmap parses correctly and canonicalizes at least N% of authors.

Mailmap + git log format placeholders ​

Mailmap-aware format specifiers (these apply mailmap rewriting):

SpecifierFieldWithout mailmap equivalent
%aNAuthor name (mailmap)%an
%aEAuthor email (mailmap)%ae
%cNCommitter name (mailmap)%cn
%cECommitter email (mailmap)%ce

Always use the capital-letter variants in CI scripts when mailmap is active.

Pitfalls ​

  1. Mailmap only affects display commands. It does not rewrite commit objects. git log --format=%H still returns the original SHA. For actual history rewrites, use git filter-repo --mailmap.
  2. Case sensitivity. Email matching is case-sensitive. User@Company.com and user@company.com are different to mailmap unless both are listed.
  3. Mailmap is not applied to git log --raw or git diff. These show the on-disk identity from the commit object directly.
  4. Shallow clones with mailmap.blob. If the mailmap blob doesn't exist in the shallow history, Git falls back to no mailmap. Use mailmap.file for CI runners with shallow clones.
  5. 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.
  6. Accidental over-matching. A rule like <correct@email> <wrong@email> matches any author with wrong@email regardless of name. Use the four-field form (Name <email> Name <email>) when you want to match both fields.
  7. Mailmap is not inherited across forks. Each fork needs its own .mailmap or must configure mailmap.file globally.

Mailmap vs filter-repo --mailmap ​

ApproachChanges commit SHAs?ScopeUse case
.mailmap fileNoCosmetic (display only)Daily workflows, CI, changelogs
git filter-repo --mailmapYesPermanent history rewriteSanitizing 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 specification
  • git shortlog -sne — mailmap-aware contributor summary
  • git log --use-mailmap — force mailmap on log output (enabled by default when .mailmap exists)
  • git blame --use-mailmap — mailmap-aware blame
  • git config mailmap.file / mailmap.blob — custom mailmap sources

Git Master — Git Reference for Every Skill Level