# [PATCH v2] git-shortlog.txt: improve documentation about .mailmap files 2 messages from 2008-12-27 to 2008-12-27. Participants: Adeodato Simó. Thread: https://gitlist.dev/t/16886 ## Adeodato Simó, 2008-12-27 18:21 Subject: Re: [PATCH] git-shortlog.txt: improve documentation about .mailmap files Message-ID: <20081227182140.GA28946@chistera.yi.org> URL: https://gitlist.dev/e/20081227182140.GA28946%40chistera.yi.org In-Reply-To: <7viqp5et48.fsf@gitster.siamese.dyndns.org> ``` * Junio C Hamano [Sat, 27 Dec 2008 03:48:39 -0800]: > Adeodato Simó 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 # 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 > > +Author: Joe R. Developer > > +Author: Jane Doe > > +Author: Jane Doe > > +Author: Jane D. > > +------------ > 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 ``` ## Adeodato Simó, 2008-12-27 18:23 Subject: [PATCH v2] git-shortlog.txt: improve documentation about .mailmap files Message-ID: <1230402210-30565-1-git-send-email-dato@net.com.org.es> URL: https://gitlist.dev/e/1230402210-30565-1-git-send-email-dato%40net.com.org.es In-Reply-To: <20081227182140.GA28946@chistera.yi.org> ``` 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. Signed-off-by: Adeodato Simó --- Documentation/git-shortlog.txt | 40 +++++++++++++++++++++++++++++++++------- 1 files changed, 33 insertions(+), 7 deletions(-) diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt index 7ccf31c..4a76b7f 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -48,15 +48,41 @@ OPTIONS FILES ----- -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 is used to map 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). + +Each line in the file consists, in this order, of the canonical real name +of an author, whitespace, and an email address (enclosed by '<' and '>') +to map to the name. Use hash '#' for comments, either on their own line, +or after the email address. + +A canonical name may appear in more than one line, associated with +different email addresses, but it doesn't make sense for a given address +to appear more than once (if that happens, the latest line in which it +appears will take effect). + +So, for example, if your history contains commits by two authors, Jane +and Joe, whose names appear in the repository under several forms: + +------------ +Joe Developer +Joe R. Developer +Jane Doe +Jane Doe +Jane D. +------------ + +Then, supposing Joe wants his middle name initial used, and Jane prefers +her family name fully spelled out, a proper `.mailmap` file would be: ------------ -# Keep alphabetized -Adam Morrow -Eve Jones +# Note how we don't need an entry for , because the +# real name of that author is correct already, and coalesced directly. +Jane Doe +Joe R. Developer ------------ Author -- 1.6.1.307.g07803 ```