Using git check-mailmap correctly

Question

Context

There is a .mailmap file at the root of the project in question. It consists of entries such as these:

Some User <[email protected]> <[email protected]>
Some User <[email protected]> <[email protected]>
Another User <[email protected]> <[email protected]>
...

I found documentation on retrieving canonical contact data for any given user using git check-mailmap:

https://git-scm.com/docs/git-check-mailmap

Question

Simple question, to which I did not find a concise answer - how does one use the command correctly?

Documentation provides syntax as follows:

git check-mailmap [<options>] <contact>

However entering e.g. any the following

git check-mailmap [email protected]
git check-mailmap Some User
git check-mailmap --std

yields no result other than

fatal: unable to parse contact ...

In addition I entered git check-mailmap --help to look for additional info, but it seems to me like the provided HTML is equivalent to the page I linked earlier.

So how is git check-mailmap being used properly?

Answer 1

Git 2.47 (Q4 2024), batch 13, should be more permissive with "git send-email"^(man):

See commit 241499a, commit f54ca6a, commit 3a27e99 (27 Aug 2024) by Jacob Keller (jacob-keller).
^{(Merged by Junio C Hamano -- gitster -- in commit 6dcb2db, 06 Sep 2024)}

check-mailmap: accept "user@host" contacts

^{Signed-off-by: Jacob Keller}

git check-mailmap^(man) splits each provided contact using split_ident_line.
This function requires that the contact either be of the form "Name <user@host>" or of the form "<user@host>".
In particular, if the mail portion of the contact is not surrounded by angle brackets, split_ident_line will reject it.

This results in git check-mailmap rejecting attempts to translate simple email addresses:

$ git check-mailmap user@host
fatal: unable to parse contact: user@host

This limits the usability of check-mailmap as it requires placing angle brackets around plain email addresses.

In particular, attempting to use git check-mailmap to support mapping addresses in git send-email^(man) is not straight forward.
The sanitization and validation functions in git send-email strip angle brackets from plain email addresses.
It is not trivial to add brackets prior to invoking git check-mailmap.

Instead, modify check_mailmap() to allow such strings as contacts.
In particular, treat any line which cannot be split by split_ident_line as a simple email address.

No attempt is made to actually parse the address line, or validate that it is actually an email address.
Implementing such validation is not trivial.
Besides, we weren't validating the address between angle brackets before anyways.

git check-mailmap now includes in its man page:

For each Name <user@host>, <user@host, or user@host from the command-line or standard input (when using --stdin), look up the person's canonical name and email address (see "Mapping Authors" below). If found, print them; otherwise print the input as-is.

And:

check-mailmap: add options for additional mailmap sources

^{Signed-off-by: Jacob Keller}

The git check-mailmap^(man) command reads the mailmap from either the default .mailmap location and then from the mailmap.blob and mailmap.file configurations.

A following change to git send-email^(man) will want to support new configuration options based on the configured identity.
The identity-based configuration and options only make sense in the context of git send-email.

Expose the read_mailmap_file and read_mailmap_blob functions from mailmap.c.
Teach git check-mailmap the --mailmap-file and --mailmap-blob options which load the additional mailmap sources.

git check-mailmap now includes in its man page:

--mailmap-file=<file>

In addition to any configured mailmap files, read the specified mailmap file. Entries in this file take precedence over entries in either the default mailmap file or any configured mailmap file.

--mailmap-blob=<blob>

Like --mailmap-file, but consider the value as a reference to a blob in the repository. If both --mailmap-file and --mailmap-blob are specified, entries in --mailmap-file will take precedence.

---

The idea is then:

send-email: add mailmap support via sendemail.mailmap and --mailmap

^{Signed-off-by: Jacob Keller}

In some cases, a user may be generating a patch for an old commit which now has an out-of-date author or other identity.
For example, consider a team member who contributes to an internal fork of an upstream project, but leaves before this change is submitted upstream.

In this case, the team members company address may no longer be valid, and will thus bounce when sending email.

This can be manually avoided by editing the generated patch files, or by carefully using --suppress-<cc|to> options.
This requires a lot of manual intervention and is easy to forget.

Git has support for mapping old email addresses and names to a canonical name and address via the .mailmap file (and its associated mailmap.file, mailmap.blob, and log.mailmap options).

Teach git send-email^(man) to enable mailmap support for all addresses.
This ensures that addresses point to the canonical real name and email address.

Add the sendemail.mailmap configuration option and its associated --mailmap (and --use-mailmap for compatibility with git log^(man)) options.
For now, the default behavior is to disable the mailmap in order to avoid any surprises or breaking any existing setups.

These options support per-identity configuration via the sendemail.identity configuration blocks.
This enables identity-specific configuration in cases where users may not want to enable support.

In addition, support send-email specific mailmap data via sendemail.mailmap.file, sendemail.mailmap.blob and their identity-specific variants.

The intention of these options is to enable mapping addresses which are no longer valid to a current project or team maintainer.
Such mappings may change the actual person being referred to, and may not make sense in a traditional mailmap file which is intended for updating canonical name and address for the same individual.

Answer 2

An anwer was found thanks to @phd. See comment section under opening post for details given.

The syntax I was using to call git check-mailmap is incorrect:

git check-mailmap [email protected]
git check-mailmap Some User
git check-mailmap --std

Instead, in order to retrieve a canonical alias, both a username and a corresponding address need to be provided.

In the example given a valid call may look like this:

git check-mailmap 'Some User <[email protected]>'

and should yield:

Some User <[email protected]>

A handy way to check .mailmap validity is usage of git shortlog -se.