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

["Adeodato Simó" <dato@net.com.org.es>]

* Junio C Hamano [Sat, 27 Dec 2008 03:48:39 -0800]:

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

Thanks for your review!

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

Hm. I'd prefer to keep it in if you don't mind much.

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

Changed.

> > +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".

Changed.

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

It is processed correctly. Good suggestion to have it documented. I did:

  Use hash '#' for comments, either on their own line, or after the
  email address.

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

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

Ok.

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

And ok.

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

I wanted to use a real TLD to clearly convey that these were for real
addresses and not misconfigured ones. How about "example.com"? (This is
used in other Documentation files.)

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

Good point. As always, what it's obvious to the writer may not be to the
reader. Thanks.

I also added a sentence mentioning that names can appear more than once,
but addresses can't.

Can you take another look? (Amended patch coming.)

-- 
Adeodato Simó                                     dato at net.com.org.es
Debian Developer                                  adeodato at debian.org
 
- You look beaten.
- I just caught Tara laughing with another man.
- Are you sure they weren't just... kissing or something?
- No, they were laughing.
                -- Denny Crane and Alan Shore