mailmap doc + tests: add better examples & test them

Change the mailmap documentation added in 0925ce4 (Add map_user()
and clear_mailmap() to mailmap, 2009-02-08) to continue discussing the
Jane/Joe example. I think this makes things a lot less confusing as
we're building up more complex examples using one set of data which
covers all the things we'd like to discuss.

Also add tests to assert that what our documentation says is what's
actually happening. This is mostly (or entirely) covered by existing
tests which I'm not deleting, but having these tests for the synopsis
makes it easier to follow-along while reading the tests & docs.

Signed-off-by: Ævar Arnfjörð Bjarmason <[email protected]>
Signed-off-by: Junio C Hamano <[email protected]>

Author: avar

Documentation/gitmailmap.txt

@@ -53,7 +53,7 @@ commit matching both the specified commit name and email address.
 EXAMPLES
 --------
 
-Example 1: Your history contains commits by two authors, Jane
+Your history contains commits by two authors, Jane
 and Joe, whose names appear in the repository under several forms:
 
 ------------
@@ -65,36 +65,45 @@ Jane D. <jane@desktop.(none)>
 ------------
 
 Now suppose that Joe wants his middle name initial used, and Jane
-prefers her family name fully spelled out. A proper `.mailmap` file
-would look like:
+prefers her family name fully spelled out. A `.mailmap` file to
+correct the names would look like:
 
 ------------
-Jane Doe         <jane@desktop.(none)>
 Joe R. Developer <[email protected]>
+Jane Doe <[email protected]>
+Jane Doe <jane@desktop.(none)>
 ------------
 
-Note how there is no need for an entry for `<jane@laptop.(none)>`, because the
-real name of that author is already correct.
+Note that there's no need to map the name for 'jane@laptop.(none)' to
+only correct the names. However, leaving the obviously broken
+`<jane@laptop.(none)>' and '<jane@desktop.(none)>' E-Mails as-is is
+usually not what you want. A `.mailmap` file which also corrects those
+is:
 
-Example 2: Your repository contains commits from the following
-authors:
+------------
+Joe R. Developer <[email protected]>
+Jane Doe <[email protected]> <jane@laptop.(none)>
+Jane Doe <[email protected]> <jane@desktop.(none)>
+------------
+
+Finally, let's say that Joe and Jane shared an E-Mail address, but not
+a name, e.g. by having these two commits in the history generated by a
+bug reporting system. I.e. names appearing in history as:
 
 ------------
-nick1 <[email protected]>
-nick2 <[email protected]>
-nick2 <[email protected]>
-santa <[email protected]>
-claus <[email protected]>
-CTO <[email protected]>
+Joe <[email protected]>
+Jane <[email protected]>
 ------------
 
-Then you might want a `.mailmap` file that looks like:
+A full `.mailmap` file which also handles those cases (an addition of
+two lines to the above example) would be:
+
 ------------
-<[email protected]>                       <[email protected]>
-Some Dude <[email protected]>         nick1 <[email protected]>
-Other Author <[email protected]>   nick2 <[email protected]>
-Other Author <[email protected]>         <[email protected]>
-Santa Claus <[email protected]> <[email protected]>
+Joe R. Developer <[email protected]>
+Jane Doe <[email protected]> <jane@laptop.(none)>
+Jane Doe <[email protected]> <jane@desktop.(none)>
+Joe R. Developer <[email protected]> Joe <[email protected]>
+Jane Doe <[email protected]> Jane <[email protected]>
 ------------
 
 

t/t4203-mailmap.sh

@@ -419,6 +419,94 @@ test_expect_success 'preserve canonical email case' '
 	test_cmp expect actual
 '
 
+test_expect_success 'gitmailmap(5) example output: setup' '
+	test_create_repo doc &&
+	test_commit -C doc --author "Joe Developer <[email protected]>" A &&
+	test_commit -C doc --author "Joe R. Developer <[email protected]>" B &&
+	test_commit -C doc --author "Jane Doe <[email protected]>" C &&
+	test_commit -C doc --author "Jane Doe <jane@laptop.(none)>" D &&
+	test_commit -C doc --author "Jane D. <jane@desktop.(none)>" E
+'
+
+test_expect_success 'gitmailmap(5) example output: example #1' '
+	test_config -C doc mailmap.file ../doc.map &&
+	cat >doc.map <<-\EOF &&
+	Joe R. Developer <[email protected]>
+	Jane Doe <[email protected]>
+	Jane Doe <jane@desktop.(none)>
+	EOF
+
+	cat >expect <<-\EOF &&
+	Author Joe Developer <[email protected]> maps to Joe R. Developer <[email protected]>
+	Committer C O Mitter <[email protected]> maps to C O Mitter <[email protected]>
+
+	Author Joe R. Developer <[email protected]> maps to Joe R. Developer <[email protected]>
+	Committer C O Mitter <[email protected]> maps to C O Mitter <[email protected]>
+
+	Author Jane Doe <[email protected]> maps to Jane Doe <[email protected]>
+	Committer C O Mitter <[email protected]> maps to C O Mitter <[email protected]>
+
+	Author Jane Doe <jane@laptop.(none)> maps to Jane Doe <jane@laptop.(none)>
+	Committer C O Mitter <[email protected]> maps to C O Mitter <[email protected]>
+
+	Author Jane D <jane@desktop.(none)> maps to Jane Doe <jane@desktop.(none)>
+	Committer C O Mitter <[email protected]> maps to C O Mitter <[email protected]>
+	EOF
+	git -C doc log --reverse --pretty=format:"Author %an <%ae> maps to %aN <%aE>%nCommitter %cn <%ce> maps to %cN <%cE>%n" >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'gitmailmap(5) example output: example #2' '
+	test_config -C doc mailmap.file ../doc.map &&
+	cat >doc.map <<-\EOF &&
+	Joe R. Developer <[email protected]>
+	Jane Doe <[email protected]> <jane@laptop.(none)>
+	Jane Doe <[email protected]> <jane@desktop.(none)>
+	EOF
+
+	cat >expect <<-\EOF &&
+	Author Joe Developer <[email protected]> maps to Joe R. Developer <[email protected]>
+	Committer C O Mitter <[email protected]> maps to C O Mitter <[email protected]>
+
+	Author Joe R. Developer <[email protected]> maps to Joe R. Developer <[email protected]>
+	Committer C O Mitter <[email protected]> maps to C O Mitter <[email protected]>
+
+	Author Jane Doe <[email protected]> maps to Jane Doe <[email protected]>
+	Committer C O Mitter <[email protected]> maps to C O Mitter <[email protected]>
+
+	Author Jane Doe <jane@laptop.(none)> maps to Jane Doe <[email protected]>
+	Committer C O Mitter <[email protected]> maps to C O Mitter <[email protected]>
+
+	Author Jane D <jane@desktop.(none)> maps to Jane Doe <[email protected]>
+	Committer C O Mitter <[email protected]> maps to C O Mitter <[email protected]>
+	EOF
+	git -C doc log --reverse --pretty=format:"Author %an <%ae> maps to %aN <%aE>%nCommitter %cn <%ce> maps to %cN <%cE>%n" >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'gitmailmap(5) example output: example #3' '
+	test_config -C doc mailmap.file ../doc.map &&
+	cat >>doc.map <<-\EOF &&
+	Joe R. Developer <[email protected]> Joe <[email protected]>
+	Jane Doe <[email protected]> Jane <[email protected]>
+	EOF
+
+	test_commit -C doc --author "Joe <[email protected]>" F &&
+	test_commit -C doc --author "Jane <[email protected]>" G &&
+
+	cat >>expect <<-\EOF &&
+
+	Author Joe <[email protected]> maps to Joe R. Developer <[email protected]>
+	Committer C O Mitter <[email protected]> maps to C O Mitter <[email protected]>
+
+	Author Jane <[email protected]> maps to Jane Doe <[email protected]>
+	Committer C O Mitter <[email protected]> maps to C O Mitter <[email protected]>
+	EOF
+	git -C doc log --reverse --pretty=format:"Author %an <%ae> maps to %aN <%aE>%nCommitter %cn <%ce> maps to %cN <%cE>%n" >actual &&
+	test_cmp expect actual
+'
+
+
 test_expect_success 'Shortlog output (complex mapping)' '
 	test_config mailmap.file complex.map &&
 	cat >complex.map <<-EOF &&