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. ------------ 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 Joe R. Developer +Jane Doe +Jane Doe ------------ -Note how there is no need for an entry for ``, 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 +`' and '' E-Mails as-is is +usually not what you want. A `.mailmap` file which also corrects those +is: ------------ -nick1 -nick2 -nick2 -santa -claus -CTO +Joe R. Developer +Jane Doe +Jane Doe ------------ -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: + ------------ - -Some Dude nick1 -Other Author nick2 -Other Author -Santa Claus +Joe +Jane +------------ + +A full `.mailmap` file which also handles those cases (an addition of +two lines to the above example) would be: + +------------ +Joe R. Developer +Jane Doe +Jane Doe +Joe R. Developer Joe +Jane Doe Jane ------------ 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 " A && + test_commit -C doc --author "Joe R. Developer " B && + test_commit -C doc --author "Jane Doe " C && + test_commit -C doc --author "Jane Doe " D && + test_commit -C doc --author "Jane D. " 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 + Jane Doe + Jane Doe + EOF + + cat >expect <<-\EOF && + Author Joe Developer maps to Joe R. Developer + Committer C O Mitter maps to C O Mitter + + Author Joe R. Developer maps to Joe R. Developer + Committer C O Mitter maps to C O Mitter + + Author Jane Doe maps to Jane Doe + Committer C O Mitter maps to C O Mitter + + Author Jane Doe maps to Jane Doe + Committer C O Mitter maps to C O Mitter + + Author Jane D maps to Jane Doe + Committer C O Mitter maps to C O Mitter + 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 + Jane Doe + Jane Doe + EOF + + cat >expect <<-\EOF && + Author Joe Developer maps to Joe R. Developer + Committer C O Mitter maps to C O Mitter + + Author Joe R. Developer maps to Joe R. Developer + Committer C O Mitter maps to C O Mitter + + Author Jane Doe maps to Jane Doe + Committer C O Mitter maps to C O Mitter + + Author Jane Doe maps to Jane Doe + Committer C O Mitter maps to C O Mitter + + Author Jane D maps to Jane Doe + Committer C O Mitter maps to C O Mitter + 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 + Jane Doe Jane + EOF + + test_commit -C doc --author "Joe " F && + test_commit -C doc --author "Jane " G && + + cat >>expect <<-\EOF && + + Author Joe maps to Joe R. Developer + Committer C O Mitter maps to C O Mitter + + Author Jane maps to Jane Doe + Committer C O Mitter maps to C O Mitter + 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 &&