git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH 17/22] mailmap doc + tests: add better examples & test them

From
Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date
Jan 12, 2021, 20:18 UTC
Message-ID
<20210112201806.13284-18-avarab@gmail.com>
In-Reply-To
<20210105130359.21139-1-avarab@gmail.com>

Change the mailmap documentation added in 0925ce4d49 (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 <avarab@gmail.com>
---
 Documentation/gitmailmap.txt | 49 ++++++++++++--------
 t/t4203-mailmap.sh           | 88 ++++++++++++++++++++++++++++++++++++
 2 files changed, 117 insertions(+), 20 deletions(-)
diff --git a/Documentation/gitmailmap.txt b/Documentation/gitmailmap.txt
index 4e4677018b..55dfebd1b1 100644
--- a/Documentation/gitmailmap.txt
+++ b/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 <joe@example.com>
+Jane Doe <jane@example.com>
+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 <joe@example.com>
+Jane Doe <jane@example.com> <jane@laptop.(none)>
+Jane Doe <jane@example.com> <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 <bugs@company.xx>
-nick2 <bugs@company.xx>
-nick2 <nick2@company.xx>
-santa <me@company.xx>
-claus <me@company.xx>
-CTO <cto@coompany.xx>
+Joe <bugs@example.com>
+Jane <bugs@example.com>
 ------------
 
-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:
+
 ------------
-<cto@company.xx>                       <cto@coompany.xx>
-Some Dude <some@dude.xx>         nick1 <bugs@company.xx>
-Other Author <other@author.xx>   nick2 <bugs@company.xx>
-Other Author <other@author.xx>         <nick2@company.xx>
-Santa Claus <santa.claus@northpole.xx> <me@company.xx>
+Joe R. Developer <joe@example.com>
+Jane Doe <jane@example.com> <jane@laptop.(none)>
+Jane Doe <jane@example.com> <jane@desktop.(none)>
+Joe R. Developer <joe@example.com> Joe <bugs@example.com>
+Jane Doe <jane@example.com> Jane <bugs@example.com>
 ------------
 
 
diff --git a/t/t4203-mailmap.sh b/t/t4203-mailmap.sh
index 5d92880a5a..96ba5367c6 100755
--- a/t/t4203-mailmap.sh
+++ b/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 <joe@example.com>" A &&
+	test_commit -C doc --author "Joe R. Developer <joe@example.com>" B &&
+	test_commit -C doc --author "Jane Doe <jane@example.com>" 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 <joe@example.com>
+	Jane Doe <jane@example.com>
+	Jane Doe <jane@desktop.(none)>
+	EOF
+
+	cat >expect <<-\EOF &&
+	Author Joe Developer <joe@example.com> maps to Joe R. Developer <joe@example.com>
+	Committer C O Mitter <committer@example.com> maps to C O Mitter <committer@example.com>
+
+	Author Joe R. Developer <joe@example.com> maps to Joe R. Developer <joe@example.com>
+	Committer C O Mitter <committer@example.com> maps to C O Mitter <committer@example.com>
+
+	Author Jane Doe <jane@example.com> maps to Jane Doe <jane@example.com>
+	Committer C O Mitter <committer@example.com> maps to C O Mitter <committer@example.com>
+
+	Author Jane Doe <jane@laptop.(none)> maps to Jane Doe <jane@laptop.(none)>
+	Committer C O Mitter <committer@example.com> maps to C O Mitter <committer@example.com>
+
+	Author Jane D <jane@desktop.(none)> maps to Jane Doe <jane@desktop.(none)>
+	Committer C O Mitter <committer@example.com> maps to C O Mitter <committer@example.com>
+	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 <joe@example.com>
+	Jane Doe <jane@example.com> <jane@laptop.(none)>
+	Jane Doe <jane@example.com> <jane@desktop.(none)>
+	EOF
+
+	cat >expect <<-\EOF &&
+	Author Joe Developer <joe@example.com> maps to Joe R. Developer <joe@example.com>
+	Committer C O Mitter <committer@example.com> maps to C O Mitter <committer@example.com>
+
+	Author Joe R. Developer <joe@example.com> maps to Joe R. Developer <joe@example.com>
+	Committer C O Mitter <committer@example.com> maps to C O Mitter <committer@example.com>
+
+	Author Jane Doe <jane@example.com> maps to Jane Doe <jane@example.com>
+	Committer C O Mitter <committer@example.com> maps to C O Mitter <committer@example.com>
+
+	Author Jane Doe <jane@laptop.(none)> maps to Jane Doe <jane@example.com>
+	Committer C O Mitter <committer@example.com> maps to C O Mitter <committer@example.com>
+
+	Author Jane D <jane@desktop.(none)> maps to Jane Doe <jane@example.com>
+	Committer C O Mitter <committer@example.com> maps to C O Mitter <committer@example.com>
+	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 <joe@example.com> Joe <bugs@example.com>
+	Jane Doe <jane@example.com> Jane <bugs@example.com>
+	EOF
+
+	test_commit -C doc --author "Joe <bugs@example.com>" F &&
+	test_commit -C doc --author "Jane <bugs@example.com>" G &&
+
+	cat >>expect <<-\EOF &&
+
+	Author Joe <bugs@example.com> maps to Joe R. Developer <joe@example.com>
+	Committer C O Mitter <committer@example.com> maps to C O Mitter <committer@example.com>
+
+	Author Jane <bugs@example.com> maps to Jane Doe <jane@example.com>
+	Committer C O Mitter <committer@example.com> maps to C O Mitter <committer@example.com>
+	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 &&

-- 
2.29.2.222.g5d2a92d10f8
Previous: Ævar Arnfjörð BjarmasonNext: Ævar Arnfjörð Bjarmason
Message 25 of 50 in “git-shortlog: make common repository prefix configurable with .mailmap”
  1. 2/2 git-shortlog: make common repository prefix configurable with .mailmapJunio C Hamano, Nov 25, 2006
  2. shortlog: remove unused(?) "repo-abbrev" featureÆvar Arnfjörð Bjarmason, Jan 5, 2021
  3. Linus TorvaldsJan 5, 2021
  4. Martin ÅgrenJan 5, 2021
  5. Junio C HamanoJan 5, 2021
  6. 20/22 mailmap tests: add tests for empty "<>" syntaxÆvar Arnfjörð Bjarmason, Jan 12, 2021
  7. 19/22 mailmap tests: add tests for whitespace syntaxÆvar Arnfjörð Bjarmason, Jan 12, 2021
  8. 21/22 mailmap doc + tests: document and test for case-insensitivityÆvar Arnfjörð Bjarmason, Jan 12, 2021
  9. 22/22 shortlog: remove unused(?) "repo-abbrev" featureÆvar Arnfjörð Bjarmason, Jan 12, 2021
  10. 16/22 tests: refactor a few tests to use "test_commit --append"Ævar Arnfjörð Bjarmason, Jan 12, 2021
  11. 15/22 test-lib functions: add an --append option to test_commitÆvar Arnfjörð Bjarmason, Jan 12, 2021
  12. 09/22 mailmap tests: add a test for "not a blob" errorÆvar Arnfjörð Bjarmason, Jan 12, 2021
  13. Junio C HamanoJan 12, 2021
  14. 12/22 test-lib functions: expand "test_commit" comment templateÆvar Arnfjörð Bjarmason, Jan 12, 2021
  15. 11/22 mailmap: test for silent exiting on missing file/blobÆvar Arnfjörð Bjarmason, Jan 12, 2021
  16. 14/22 test-lib functions: add --author support to test_commitÆvar Arnfjörð Bjarmason, Jan 12, 2021
  17. Junio C HamanoJan 12, 2021
  18. Denton LiuJan 14, 2021
  19. 13/22 test-lib functions: document arguments to test_commitÆvar Arnfjörð Bjarmason, Jan 12, 2021
  20. 10/22 mailmap tests: get rid of overly complex blame fuzzingÆvar Arnfjörð Bjarmason, Jan 12, 2021
  21. Junio C HamanoJan 12, 2021
  22. Junio C HamanoJan 14, 2021
  23. 08/22 mailmap tests: remove redundant entry in testÆvar Arnfjörð Bjarmason, Jan 12, 2021
  24. 07/22 mailmap tests: improve --stdin testsÆvar Arnfjörð Bjarmason, Jan 12, 2021
  25. 17/22 mailmap doc + tests: add better examples & test themÆvar Arnfjörð Bjarmason, Jan 12, 2021
  26. 18/22 mailmap tests: add a test for comment syntaxÆvar Arnfjörð Bjarmason, Jan 12, 2021
  27. 06/22 mailmap tests: modernize syntax & test idiomsÆvar Arnfjörð Bjarmason, Jan 12, 2021
  28. Denton LiuJan 14, 2021
  29. Junio C HamanoJan 14, 2021
  30. 05/22 mailmap tests: use our preferred whitespace syntaxÆvar Arnfjörð Bjarmason, Jan 12, 2021
  31. 04/22 mailmap doc: start by mentioning the comment syntaxÆvar Arnfjörð Bjarmason, Jan 12, 2021
  32. 03/22 check-mailmap doc: note config optionsÆvar Arnfjörð Bjarmason, Jan 12, 2021
  33. 01/22 mailmap doc: create a new "gitmailmap(5)" man pageÆvar Arnfjörð Bjarmason, Jan 12, 2021
  34. Philippe BlainJan 14, 2021
  35. Junio C HamanoJan 14, 2021
  36. Philippe BlainJan 15, 2021
  37. Junio C HamanoJan 15, 2021
  38. Philippe BlainJan 15, 2021
  39. Junio C HamanoJan 15, 2021
  40. fixup! mailmap doc: create a new "gitmailmap(5)" man pagePhilippe Blain, Jan 15, 2021
  41. mailmap doc: use correct environment variable 'GIT_WORK_TREE'Philippe Blain, Jan 15, 2021
  42. 00/22 mailmap: doc + test fixesÆvar Arnfjörð Bjarmason, Jan 12, 2021
  43. Junio C HamanoJan 12, 2021
  44. Ævar Arnfjörð BjarmasonJan 14, 2021
  45. 0/2 mailmap: test cleanupDenton Liu, Jan 14, 2021
  46. 1/2 test-lib-functions.sh: fix usage for test_commit()Denton Liu, Jan 14, 2021
  47. Ævar Arnfjörð BjarmasonJan 15, 2021
  48. 2/2 t4203: stop losing return codes of git commandsDenton Liu, Jan 14, 2021
  49. Ævar Arnfjörð BjarmasonJan 15, 2021
  50. 02/22 mailmap doc: quote config variables `like.this`Ævar Arnfjörð Bjarmason, Jan 12, 2021

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.