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

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

[Adeodato Simó]

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 <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)>
+------------
+
+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>
 ------------
 
 Author
-- 
1.6.1

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

[Adeodato Simó]

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ó <dato@net.com.org.es>
---

    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 <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)>
+------------
+
+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>
 ------------
 
 Author
-- 
1.6.1

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

[Junio C Hamano]

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

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

[Adeodato Simó]

* 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

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

[Adeodato Simó]

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ó <dato@net.com.org.es>
---
 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@example.com>
+Joe R. Developer <joe@example.com>
+Jane Doe <jane@example.com>
+Jane Doe <jane@laptop.(none)>
+Jane D. <jane@desktop.(none)>
+------------
+
+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 <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>
 ------------
 
 Author
-- 
1.6.1.307.g07803