diff options
| -rw-r--r-- | Documentation/gitmailmap.txt | 49 | ||||
| -rwxr-xr-x | 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 && |