undef/git-commit-vandalism
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

mailmap doc + tests: add better examples & test them

Browse Source 
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>
This commit is contained in:
Ævar Arnfjörð Bjarmason 2021-01-12 21:18:01 +01:00 committed by Junio C Hamano
parent f5d79bf7dd
commit 05b5ff219c
2 changed files with 118 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
Documentation/gitmailmap.txt
View File

@ -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.
Example 2: Your repository contains commits from the following
authors:
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:
------------
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 R. Developer <joe@example.com>
Jane Doe <jane@example.com> <jane@laptop.(none)>
Jane Doe <jane@example.com> <jane@desktop.(none)>
------------
Then you might want a `.mailmap` file that looks like:
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:
------------
<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 <bugs@example.com>
Jane <bugs@example.com>
------------
A full `.mailmap` file which also handles those cases (an addition of
two lines to the above example) would be:
------------
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>
------------

88
t/t4203-mailmap.sh
View File

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