Re: [PATCH] git-shortlog.txt: improve documentation about .mailmap files
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.
Show 9 quoted lines
> -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".
Show 7 quoted lines
> +------------
> +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".
Show 11 quoted lines
> +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>
> ------------
Adeodato Simó