mailmap doc + tests: add better examples & test them
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> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ævar Arnfjörð Bjarmason committed
Jan 12, 2021 at 21:18 UTC
05b5ff219c22ca8b3abb7fed3e4dcaf41fe46018
2 files changed
+117
-20
Documentation/gitmailmap.txt
+29
-20
@@ -53,7 +53,7 @@ commit matching both the specified commit name and email address.
53
EXAMPLES
54
--------
55
56
-Example 1: Your history contains commits by two authors, Jane
56
+Your history contains commits by two authors, Jane
57
and Joe, whose names appear in the repository under several forms:
58
59
------------
@@ -65,36 +65,45 @@ Jane D. <jane@desktop.(none)>
65
------------
66
67
Now suppose that Joe wants his middle name initial used, and Jane
68
-prefers her family name fully spelled out. A proper `.mailmap` file
69
-would look like:
68
+prefers her family name fully spelled out. A `.mailmap` file to
69
+correct the names would look like:
70
71
------------
72
-Jane Doe <jane@desktop.(none)>
72
Joe R. Developer <joe@example.com>
73
+Jane Doe <jane@example.com>
74
+Jane Doe <jane@desktop.(none)>
75
------------
76
76
-Note how there is no need for an entry for `<jane@laptop.(none)>`, because the
77
-real name of that author is already correct.
77
+Note that there's no need to map the name for 'jane@laptop.(none)' to
78
+only correct the names. However, leaving the obviously broken
79
+`<jane@laptop.(none)>' and '<jane@desktop.(none)>' E-Mails as-is is
80
+usually not what you want. A `.mailmap` file which also corrects those
81
+is:
82
79
-Example 2: Your repository contains commits from the following
80
-authors:
83
+------------
84
+Joe R. Developer <joe@example.com>
85
+Jane Doe <jane@example.com> <jane@laptop.(none)>
86
+Jane Doe <jane@example.com> <jane@desktop.(none)>
87
+------------
88
+
89
+Finally, let's say that Joe and Jane shared an E-Mail address, but not
90
+a name, e.g. by having these two commits in the history generated by a
91
+bug reporting system. I.e. names appearing in history as:
92
93
------------
83
-nick1 <bugs@company.xx>
84
-nick2 <bugs@company.xx>
85
-nick2 <nick2@company.xx>
86
-santa <me@company.xx>
87
-claus <me@company.xx>
88
-CTO <cto@coompany.xx>
94
+Joe <bugs@example.com>
95
+Jane <bugs@example.com>
96
------------
97
91
-Then you might want a `.mailmap` file that looks like:
98
+A full `.mailmap` file which also handles those cases (an addition of
99
+two lines to the above example) would be:
100
+
101
------------
93
-<cto@company.xx> <cto@coompany.xx>
94
-Some Dude <some@dude.xx> nick1 <bugs@company.xx>
95
-Other Author <other@author.xx> nick2 <bugs@company.xx>
96
-Other Author <other@author.xx> <nick2@company.xx>
97
-Santa Claus <santa.claus@northpole.xx> <me@company.xx>
102
+Joe R. Developer <joe@example.com>
103
+Jane Doe <jane@example.com> <jane@laptop.(none)>
104
+Jane Doe <jane@example.com> <jane@desktop.(none)>
105
+Joe R. Developer <joe@example.com> Joe <bugs@example.com>
106
+Jane Doe <jane@example.com> Jane <bugs@example.com>
107
------------
108
109
t/t4203-mailmap.sh
+88
@@ -419,6 +419,94 @@ test_expect_success 'preserve canonical email case' '
419
test_cmp expect actual
420
'
421
422
+test_expect_success 'gitmailmap(5) example output: setup' '
423
+ test_create_repo doc &&
424
+ test_commit -C doc --author "Joe Developer <joe@example.com>" A &&
425
+ test_commit -C doc --author "Joe R. Developer <joe@example.com>" B &&
426
+ test_commit -C doc --author "Jane Doe <jane@example.com>" C &&
427
+ test_commit -C doc --author "Jane Doe <jane@laptop.(none)>" D &&
428
+ test_commit -C doc --author "Jane D. <jane@desktop.(none)>" E
429
+'
430
+
431
+test_expect_success 'gitmailmap(5) example output: example #1' '
432
+ test_config -C doc mailmap.file ../doc.map &&
433
+ cat >doc.map <<-\EOF &&
434
+ Joe R. Developer <joe@example.com>
435
+ Jane Doe <jane@example.com>
436
+ Jane Doe <jane@desktop.(none)>
437
+ EOF
438
+
439
+ cat >expect <<-\EOF &&
440
+ Author Joe Developer <joe@example.com> maps to Joe R. Developer <joe@example.com>
441
+ Committer C O Mitter <committer@example.com> maps to C O Mitter <committer@example.com>
442
+
443
+ Author Joe R. Developer <joe@example.com> maps to Joe R. Developer <joe@example.com>
444
+ Committer C O Mitter <committer@example.com> maps to C O Mitter <committer@example.com>
445
+
446
+ Author Jane Doe <jane@example.com> maps to Jane Doe <jane@example.com>
447
+ Committer C O Mitter <committer@example.com> maps to C O Mitter <committer@example.com>
448
+
449
+ Author Jane Doe <jane@laptop.(none)> maps to Jane Doe <jane@laptop.(none)>
450
+ Committer C O Mitter <committer@example.com> maps to C O Mitter <committer@example.com>
451
+
452
+ Author Jane D <jane@desktop.(none)> maps to Jane Doe <jane@desktop.(none)>
453
+ Committer C O Mitter <committer@example.com> maps to C O Mitter <committer@example.com>
454
+ EOF
455
+ git -C doc log --reverse --pretty=format:"Author %an <%ae> maps to %aN <%aE>%nCommitter %cn <%ce> maps to %cN <%cE>%n" >actual &&
456
+ test_cmp expect actual
457
+'
458
+
459
+test_expect_success 'gitmailmap(5) example output: example #2' '
460
+ test_config -C doc mailmap.file ../doc.map &&
461
+ cat >doc.map <<-\EOF &&
462
+ Joe R. Developer <joe@example.com>
463
+ Jane Doe <jane@example.com> <jane@laptop.(none)>
464
+ Jane Doe <jane@example.com> <jane@desktop.(none)>
465
+ EOF
466
+
467
+ cat >expect <<-\EOF &&
468
+ Author Joe Developer <joe@example.com> maps to Joe R. Developer <joe@example.com>
469
+ Committer C O Mitter <committer@example.com> maps to C O Mitter <committer@example.com>
470
+
471
+ Author Joe R. Developer <joe@example.com> maps to Joe R. Developer <joe@example.com>
472
+ Committer C O Mitter <committer@example.com> maps to C O Mitter <committer@example.com>
473
+
474
+ Author Jane Doe <jane@example.com> maps to Jane Doe <jane@example.com>
475
+ Committer C O Mitter <committer@example.com> maps to C O Mitter <committer@example.com>
476
+
477
+ Author Jane Doe <jane@laptop.(none)> maps to Jane Doe <jane@example.com>
478
+ Committer C O Mitter <committer@example.com> maps to C O Mitter <committer@example.com>
479
+
480
+ Author Jane D <jane@desktop.(none)> maps to Jane Doe <jane@example.com>
481
+ Committer C O Mitter <committer@example.com> maps to C O Mitter <committer@example.com>
482
+ EOF
483
+ git -C doc log --reverse --pretty=format:"Author %an <%ae> maps to %aN <%aE>%nCommitter %cn <%ce> maps to %cN <%cE>%n" >actual &&
484
+ test_cmp expect actual
485
+'
486
+
487
+test_expect_success 'gitmailmap(5) example output: example #3' '
488
+ test_config -C doc mailmap.file ../doc.map &&
489
+ cat >>doc.map <<-\EOF &&
490
+ Joe R. Developer <joe@example.com> Joe <bugs@example.com>
491
+ Jane Doe <jane@example.com> Jane <bugs@example.com>
492
+ EOF
493
+
494
+ test_commit -C doc --author "Joe <bugs@example.com>" F &&
495
+ test_commit -C doc --author "Jane <bugs@example.com>" G &&
496
+
497
+ cat >>expect <<-\EOF &&
498
+
499
+ Author Joe <bugs@example.com> maps to Joe R. Developer <joe@example.com>
500
+ Committer C O Mitter <committer@example.com> maps to C O Mitter <committer@example.com>
501
+
502
+ Author Jane <bugs@example.com> maps to Jane Doe <jane@example.com>
503
+ Committer C O Mitter <committer@example.com> maps to C O Mitter <committer@example.com>
504
+ EOF
505
+ git -C doc log --reverse --pretty=format:"Author %an <%ae> maps to %aN <%aE>%nCommitter %cn <%ce> maps to %cN <%cE>%n" >actual &&
506
+ test_cmp expect actual
507
+'
508
+
509
+
510
test_expect_success 'Shortlog output (complex mapping)' '
511
test_config mailmap.file complex.map &&
512
cat >complex.map <<-EOF &&