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

> A .mailmap file canonicalizes author names and emails across log, shortlog, and blame. Reference for the format, check-mailmap, and contributor errors.

Source: https://latchkey.dev/learn/command-reference/git-mailmap  
Updated: 2026-06-25

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
# .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

| Entry form | Effect |
| --- | --- |
| <canonical> <commit-email> | Map an email to a canonical email |
| Name <canonical> <commit-email> | Also fix the display name |
| Name <canonical> Old <commit-email> | Match by both name and email |

## 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.

```.github/workflows/ci.yml
- 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
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

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

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 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).

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt