git mailmap (.mailmap): Usage & Common CI Errors

By Kaveh Alemi·Latchkey

A .mailmap file maps a contributor’s many names/emails to one canonical identity in git output.

Mailmap fixes split contributor lists in shortlog, log, and blame - essential for accurate release credits in CI.

What it does

A .mailmap file at the repo root tells Git to rewrite author/committer names and emails consistently in log, shortlog, and blame, so one person’s commits group together regardless of the identity they used.

Common usage

# .mailmap format:
Proper Name <proper@email.com> <old@email.com>
Proper Name <proper@email.com> Old Name <old@email.com>

# verify a mapping:
git check-mailmap "Old Name <old@email.com>"
git shortlog -sne   # now grouped by canonical identity

Options

Common errors in CI

Contributor counts look wrong because the same person used several emails - add them to .mailmap. If mappings seem ignored, confirm the file is named .mailmap at the repo root (or set mailmap.file), and that the tool reading it honors mailmap (log/shortlog/blame do).

Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached

Frequently asked questions

Related guides

References

• GitHub Actions documentation