# [PATCH] git-shortlog.txt: improve documentation about .mailmap files 3 messages from 2008-12-26 to 2008-12-27. Participants: Adeodato Simó, Junio C Hamano. Thread: https://gitlist.dev/t/16868 ## Adeodato Simó, 2008-12-26 11:18 Subject: [PATCH] git-shortlog.txt: improve documentation about .mailmap files Message-ID: <1230290283-6268-1-git-send-email-dato@net.com.org.es> URL: https://gitlist.dev/e/1230290283-6268-1-git-send-email-dato%40net.com.org.es ``` 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. --- Documentation/git-shortlog.txt | 31 ++++++++++++++++++++++++------- 1 files changed, 24 insertions(+), 7 deletions(-) diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt index 7ccf31c..69e10a4 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -48,15 +48,32 @@ 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 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). + +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. For example, if your history contains commits by these +committers: + +------------ +Author: Joe Developer +Author: Joe R. Developer +Author: Jane Doe +Author: Jane Doe +Author: Jane D. +------------ + +Then 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 ``` ## Adeodato Simó, 2008-12-26 11:55 Subject: [PATCH] git-shortlog.txt: improve documentation about .mailmap files Message-ID: <1230292553-7613-1-git-send-email-dato@net.com.org.es> URL: https://gitlist.dev/e/1230292553-7613-1-git-send-email-dato%40net.com.org.es In-Reply-To: <1230290283-6268-1-git-send-email-dato@net.com.org.es> ``` 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ó --- Now with a Signed-off-by line. Has there even been talk of a commit.signoff configuration variable to always add a S-o-b line? This could allow to enable it on a per-project basis, which would be cool. Documentation/git-shortlog.txt | 31 ++++++++++++++++++++++++------- 1 files changed, 24 insertions(+), 7 deletions(-) diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt index 7ccf31c..69e10a4 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -48,15 +48,32 @@ 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 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). + +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. For example, if your history contains commits by these +committers: + +------------ +Author: Joe Developer +Author: Joe R. Developer +Author: Jane Doe +Author: Jane Doe +Author: Jane D. +------------ + +Then 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 ``` ## Junio C Hamano, 2008-12-27 11:48 Subject: Re: [PATCH] git-shortlog.txt: improve documentation about .mailmap files Message-ID: <7viqp5et48.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7viqp5et48.fsf%40gitster.siamese.dyndns.org In-Reply-To: <1230292553-7613-1-git-send-email-dato@net.com.org.es> ``` 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. > -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 # early mistake... > +... For example, if your history contains commits by these > +committers: I think you meant "authors", not "committers". > +------------ > +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. 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 > -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 > ------------ ```