Map Old Git Identities to One Name with check-mailmap

Use git check-mailmap to fix a contributor list where one person shows up as three authors, and do it without rewriting a single commit. You will build a repeatable way to turn old or inconsistent Git identities into one canonical name and email address. The workflow uses the installed Git 2.43.0, a repository-local .mailmap, and git check-mailmap to inspect the result before you rely on it in reports.

Allow about fifteen minutes. You need:

Git, and a repository where you can make a local configuration change.
A few real identity variants to test. The examples use fictional addresses, so swap in identities from your own history.

No elevated privileges are needed. Do not use sudo for this task.

1. Check the installed command

Start outside any project if you only want to confirm the version. This is read-only:

$ git --version
git version 2.43.0
$ git check-mailmap --help

The command accepts one or more contacts in the form Name <user@host> or <user@host>. It prints one canonical contact per input line. If no mapping applies, it prints the input in the appropriate form rather than failing.

Checkpoint: you should have Git 2.43.0 or another installed version whose local manual describes git check-mailmap. Option names and mailmap syntax are version-sensitive, so read the local manual when working on an older host.

2. Create a small mailmap rule

Move into a disposable clone or a working tree where a new tracked file is acceptable:

$ cd /path/to/your/repository
$ printf '%s\n' 'Proper Name <[email protected]> <[email protected]>' > .mailmap

This three-part form says: when the commit identity is associated with [email protected], report the canonical name Proper Name and canonical address [email protected]. The angle brackets are part of the file syntax. Keep the whole line intact, because splitting it into separate shell arguments would not create the intended file.

There are simpler forms too:

Name only: Proper Name <[email protected]>
Email only: <[email protected]> <[email protected]>
Three-part: usually the clearest when someone has changed both their address and displayed name.

Comments begin with #, and blank lines are ignored. Git matches names and email addresses case-insensitively.

Warning: do not add a real person's address to a public repository without checking your project's privacy and contribution policy.

Checkpoint: inspect the file before testing it.

$ sed -n '1,20p' .mailmap
Proper Name <[email protected]> <[email protected]>

3. Query one identity directly

Pass the contact as one quoted shell argument. Git does not require the quotes, but they stop the shell treating the brackets or spaces as syntax:

$ git check-mailmap 'Old Name <[email protected]>'
Proper Name <[email protected]>

The output is the value to use in a report or check that understands mailmap data. This command does not alter the commit, the index, or the working tree beyond the .mailmap file you created.

Test an address without a name as well:

$ git check-mailmap '<[email protected]>'
Proper Name <[email protected]>

Recovery: if the output still shows the alias, check that you are in the intended repository, that the file is named exactly .mailmap, and that the three email fields are in the right order. A misspelt address is simply an unmatched identity, which can look like a successful command.

4. Check several identities from standard input

For a list, use --stdin. Git reads one contact per line after it has processed any command-line contacts:

$ printf '%s\n' \
    'Old Name <[email protected]>' \
    '<[email protected]>' \
  | git check-mailmap --stdin
Proper Name <[email protected]>
<[email protected]>

The two output lines correspond to the two input lines. The unknown address remains unchanged, which is handy when reviewing a mixed export. A non-zero exit status is not how an unmatched identity is reported.

You can combine both input sources. Git exhausts the command-line contacts first, then reads standard input:

$ git check-mailmap '<[email protected]>' --stdin <<'EOF'
Proper Name <[email protected]>
EOF
Proper Name <[email protected]>
Proper Name <[email protected]>

Tip: for larger lists, redirect a reviewed file instead of generating input from an untrusted source. Be especially careful with command substitutions: do not let arbitrary text become shell syntax before Git receives it.

5. Add name-only corrections without changing addresses

Different people can appear under different names while sharing an address, for example when a system-generated address was used. A name-and-email-specific rule can tell those identities apart:

$ cat >> .mailmap <<'EOF'
Proper Name <[email protected]> Alias Name <[email protected]>
EOF
$ git check-mailmap 'Alias Name <[email protected]>'
Proper Name <[email protected]>

The four-part form matches both the old name and the old email. Use it when a broad email-only rule would wrongly merge two people.

Warning: review overlapping rules carefully. A mailmap is identity data, and an over-broad correction can make authorship reports misleading even though no commit content changes.

6. Use a configured mailmap when the file cannot be in the work tree

Git also supports mailmap.file and mailmap.blob configuration. They suit a project that keeps correction data outside the ordinary working-tree path, but they are configuration changes and should be reviewed like any other repository policy:

$ git config --local mailmap.file /path/to/reviewed-mailmap
$ git check-mailmap 'Old Name <[email protected]>'
Proper Name <[email protected]>

--local writes the setting in this repository's .git/config, and it does not need root access. Use an absolute path only for a file whose ownership and permissions you understand. A path to a mutable shared file can silently change the result of future reports.

You do not need to configure both .mailmap and mailmap.file for this guide. If you used the temporary local file and want to undo that configuration, run:

$ git config --local --unset mailmap.file

If the setting was absent, Git may print an error. Verify the final state rather than repeating the command:

$ git config --local --get mailmap.file || echo 'no local mailmap.file setting'

7. Decide what to keep and what to remove

A .mailmap file affects commands and reports that consult mailmap data. It does not rewrite existing commits. Before committing it, compare the corrected output with the identities found in your history and ask another maintainer to review ambiguous cases.

If the file was only a test, remove it from the working tree once you have recorded any rules worth keeping:

$ rm .mailmap
$ git status --short

Destructive action: this is the only destructive example in the guide. It removes the uncommitted test file, so do not run it if the file contains corrections you intend to keep.

Recovery: if you remove it before committing, recover it from your shell history or recreate it from the reviewed rules. If it was already committed, restore it with your normal Git workflow, such as git restore --source=HEAD -- .mailmap, after checking that this is the version you want.

Done means

Command confirmed. You checked the installed Git version and the local check-mailmap interface.
Rules understood. You can explain whether each rule changes a name, an email address, or both.
Aliases resolve. A known alias produces the canonical contact, while an unknown contact stays unchanged.
Lists work. You can process a reviewed list with --stdin without losing line-by-line correspondence.
Config checked. You checked any mailmap.file setting and know how to unset it.
Privacy reviewed. You considered the privacy and authorship implications before committing identity data.