Re: [PATCH] git-shortlog.txt: improve documentation about .mailmap files

[Junio C Hamano <gitster@pobox.com>]

Adeodato Simó <dato@net.com.org.es> writes:

> The previous .mailmap example made it seem like .mailmap files are only
> useful for commits with a wrong address for an author, when they are about
> fixing the real name. Explained this better in the text, and replaced the
> existing example with a new one that hopefully makes things clearer.

Thanks.

> -If the file `.mailmap` exists, it will be used for mapping author
> -email addresses to a real author name. One mapping per line, first
> -the author name followed by the email address enclosed by
> -'<' and '>'. Use hash '#' for comments. Example:
> +If a file `.mailmap` exists in the toplevel directory of the repository,
> +it will be used for mapping author email addresses to a canonical real
> +name. This can be used to coalesce together commits by the same person
> +where their name was spelled differently (whether with the same email
> +address or not).

We didn't stress "the toplevel" earlier, partly because it is obvious that
the file cannot be anything but project-tree wide (as opposed to being per
subdirectory, similar to .gitignore and .gitattributes).  I guess it would
not hurt to be explicit, even though it feels slightly silly.

"..., it is used to map author email addresses to..." would flow easier.

> +The format of the file is one mapping per line, first the desired author
> +name followed by the email address enclosed by '<' and '>'. Use hash '#'
> +for comments.

You already introduced the term "a canonical real name" in the earlier
description.  It would be easier to read if you stick to it and say "Each
line consists of the canonical real name of an author, whitespaces, and an
email address, enclosed by '<' and '>', to map to the name".

Can a hash '#' character be anywhere on a line?  E.g. how is an entry like
this processed?

	Jane Doe <jane@desktop.(none)> # early mistake...

> +... For example, if your history contains commits by these
> +committers:

I think you meant "authors", not "committers".

> +------------
> +Author: Joe Developer <joe@random.com>
> +Author: Joe R. Developer <joe@random.com>
> +Author: Jane Doe <jane@the-does.name>
> +Author: Jane Doe <jane@laptop.(none)>
> +Author: Jane D. <jane@desktop.(none)>
> +------------

I'd suggest dropping "Author: ".  You said you are listing people.

Isn't random.com a real domain (the same goes for the-does.name)?  It
would be preferrable to use addresses from .example (or .xz) top-level
domain.

Clarify that there are actually two people in the list above, and explain
that they are one Joe with two spellings who prefers to be referred to
with his middle initial, and one Jane with three spellings who prefers to
show the family name fully spelled out.  Do not force your readers guess
which spelling is preferred for each person in the example.  It would make
it easier for them to understand the example you will give them next and
to agree that the mailmap is "proper".

> +Then a proper `.mailmap` file would be:
>
>  ------------
> -# Keep alphabetized
> -Adam Morrow <adam@localhost.localdomain>
> -Eve Jones <eve@laptop.(none)>
> +# Note how we don't need an entry for <jane@laptop.(none)>, because the
> +# real name of that author is correct already, and coalesced directly.
> +Jane Doe <jane@desktop.(none)>
> +Joe R. Developer <joe@random.com>
>  ------------