Skip to content

Commit 42342b3

Browse files
gitstergitster
committed
Merge branch 'ab/mailmap'
Clean-up docs, codepaths and tests around mailmap. * ab/mailmap: (22 commits) shortlog: remove unused(?) "repo-abbrev" feature mailmap doc + tests: document and test for case-insensitivity mailmap tests: add tests for empty "<>" syntax mailmap tests: add tests for whitespace syntax mailmap tests: add a test for comment syntax mailmap doc + tests: add better examples & test them tests: refactor a few tests to use "test_commit --append" test-lib functions: add an --append option to test_commit test-lib functions: add --author support to test_commit test-lib functions: document arguments to test_commit test-lib functions: expand "test_commit" comment template mailmap: test for silent exiting on missing file/blob mailmap tests: get rid of overly complex blame fuzzing mailmap tests: add a test for "not a blob" error mailmap tests: remove redundant entry in test mailmap tests: improve --stdin tests mailmap tests: modernize syntax & test idioms mailmap tests: use our preferred whitespace syntax mailmap doc: start by mentioning the comment syntax check-mailmap doc: note config options ...
2 parents 60ecad0 + 4e16833 commit 42342b3

22 files changed

+771
-429
lines changed

‎Documentation/Makefile‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ MAN1_TXT += gitweb.txt
2121
MAN5_TXT += gitattributes.txt
2222
MAN5_TXT += githooks.txt
2323
MAN5_TXT += gitignore.txt
24+
MAN5_TXT += gitmailmap.txt
2425
MAN5_TXT += gitmodules.txt
2526
MAN5_TXT += gitrepository-layout.txt
2627
MAN5_TXT += gitweb.conf.txt

‎Documentation/git-blame.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -226,7 +226,7 @@ commit commentary), a blame viewer will not care.
226226
MAPPING AUTHORS
227227
---------------
228228

229-
include::mailmap.txt[]
229+
See linkgit:gitmailmap[5].
230230

231231

232232
SEE ALSO

‎Documentation/git-check-mailmap.txt‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,10 +36,17 @@ name is provided or known to the 'mailmap', ``Name $$<user@host>$$'' is
3636
printed; otherwise only ``$$<user@host>$$'' is printed.
3737

3838

39+
CONFIGURATION
40+
-------------
41+
42+
See `mailmap.file` and `mailmap.blob` in linkgit:git-config[1] for how
43+
to specify a custom `.mailmap` target file or object.
44+
45+
3946
MAPPING AUTHORS
4047
---------------
4148

42-
include::mailmap.txt[]
49+
See linkgit:gitmailmap[5].
4350

4451

4552
GIT

‎Documentation/git-shortlog.txt‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -111,11 +111,7 @@ include::rev-list-options.txt[]
111111
MAPPING AUTHORS
112112
---------------
113113

114-
The `.mailmap` feature is used to coalesce together commits by the same
115-
person in the shortlog, where their name and/or email address was
116-
spelled differently.
117-
118-
include::mailmap.txt[]
114+
See linkgit:gitmailmap[5].
119115

120116
GIT
121117
---

‎Documentation/gitmailmap.txt‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
gitmailmap(5)
2+
=============
3+
4+
NAME
5+
----
6+
gitmailmap - Map author/committer names and/or E-Mail addresses
7+
8+
SYNOPSIS
9+
--------
10+
$GIT_WORK_DIR/.mailmap
11+
12+
13+
DESCRIPTION
14+
-----------
15+
16+
If the file `.mailmap` exists at the toplevel of the repository, or at
17+
the location pointed to by the `mailmap.file` or `mailmap.blob`
18+
configuration options (see linkgit:git-config[1]), it
19+
is used to map author and committer names and email addresses to
20+
canonical real names and email addresses.
21+
22+
23+
SYNTAX
24+
------
25+
26+
The '#' character begins a comment to the end of line, blank lines
27+
are ignored.
28+
29+
In the simple form, each line in the file consists of the canonical
30+
real name of an author, whitespace, and an email address used in the
31+
commit (enclosed by '<' and '>') to map to the name. For example:
32+
--
33+
Proper Name <commit@email.xx>
34+
--
35+
36+
The more complex forms are:
37+
--
38+
<proper@email.xx> <commit@email.xx>
39+
--
40+
which allows mailmap to replace only the email part of a commit, and:
41+
--
42+
Proper Name <proper@email.xx> <commit@email.xx>
43+
--
44+
which allows mailmap to replace both the name and the email of a
45+
commit matching the specified commit email address, and:
46+
--
47+
Proper Name <proper@email.xx> Commit Name <commit@email.xx>
48+
--
49+
which allows mailmap to replace both the name and the email of a
50+
commit matching both the specified commit name and email address.
51+
52+
Both E-Mails and names are matched case-insensitively. For example
53+
this would also match the 'Commit Name <commit@email.xx>' above:
54+
--
55+
Proper Name <proper@email.xx> CoMmIt NaMe <CoMmIt@EmAiL.xX>
56+
--
57+
58+
EXAMPLES
59+
--------
60+
61+
Your history contains commits by two authors, Jane
62+
and Joe, whose names appear in the repository under several forms:
63+
64+
------------
65+
Joe Developer <joe@example.com>
66+
Joe R. Developer <joe@example.com>
67+
Jane Doe <jane@example.com>
68+
Jane Doe <jane@laptop.(none)>
69+
Jane D. <jane@desktop.(none)>
70+
------------
71+
72+
Now suppose that Joe wants his middle name initial used, and Jane
73+
prefers her family name fully spelled out. A `.mailmap` file to
74+
correct the names would look like:
75+
76+
------------
77+
Joe R. Developer <joe@example.com>
78+
Jane Doe <jane@example.com>
79+
Jane Doe <jane@desktop.(none)>
80+
------------
81+
82+
Note that there's no need to map the name for 'jane@laptop.(none)' to
83+
only correct the names. However, leaving the obviously broken
84+
`<jane@laptop.(none)>' and '<jane@desktop.(none)>' E-Mails as-is is
85+
usually not what you want. A `.mailmap` file which also corrects those
86+
is:
87+
88+
------------
89+
Joe R. Developer <joe@example.com>
90+
Jane Doe <jane@example.com> <jane@laptop.(none)>
91+
Jane Doe <jane@example.com> <jane@desktop.(none)>
92+
------------
93+
94+
Finally, let's say that Joe and Jane shared an E-Mail address, but not
95+
a name, e.g. by having these two commits in the history generated by a
96+
bug reporting system. I.e. names appearing in history as:
97+
98+
------------
99+
Joe <bugs@example.com>
100+
Jane <bugs@example.com>
101+
------------
102+
103+
A full `.mailmap` file which also handles those cases (an addition of
104+
two lines to the above example) would be:
105+
106+
------------
107+
Joe R. Developer <joe@example.com>
108+
Jane Doe <jane@example.com> <jane@laptop.(none)>
109+
Jane Doe <jane@example.com> <jane@desktop.(none)>
110+
Joe R. Developer <joe@example.com> Joe <bugs@example.com>
111+
Jane Doe <jane@example.com> Jane <bugs@example.com>
112+
------------
113+
114+
115+
116+
SEE ALSO
117+
--------
118+
linkgit:git-check-mailmap[1]
119+
120+
121+
GIT
122+
---
123+
Part of the linkgit:git[1] suite

‎Documentation/mailmap.txt‎

Lines changed: 0 additions & 75 deletions
This file was deleted.

‎builtin/blame.c‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1151,7 +1151,7 @@ int cmd_blame(int argc, const char **argv, const char *prefix)
11511151
sb.xdl_opts = xdl_opts;
11521152
sb.no_whole_file_rename = no_whole_file_rename;
11531153

1154-
read_mailmap(&mailmap, NULL);
1154+
read_mailmap(&mailmap);
11551155

11561156
sb.found_guilty_entry = &found_guilty_entry;
11571157
sb.found_guilty_entry_data = &pi;

‎builtin/check-mailmap.c‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ int cmd_check_mailmap(int argc, const char **argv, const char *prefix)
4747
if (argc == 0 && !use_stdin)
4848
die(_("no contacts specified"));
4949

50-
read_mailmap(&mailmap, NULL);
50+
read_mailmap(&mailmap);
5151

5252
for (i = 0; i < argc; ++i)
5353
check_mailmap(&mailmap, argv[i]);

‎builtin/commit.c‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1039,7 +1039,7 @@ static const char *find_author_by_nickname(const char *name)
10391039
av[++ac] = NULL;
10401040
setup_revisions(ac, av, &revs, NULL);
10411041
revs.mailmap = &mailmap;
1042-
read_mailmap(revs.mailmap, NULL);
1042+
read_mailmap(revs.mailmap);
10431043

10441044
if (prepare_revision_walk(&revs))
10451045
die(_("revision walk setup failed"));

‎builtin/log.c‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -230,7 +230,7 @@ static void cmd_log_init_finish(int argc, const char **argv, const char *prefix,
230230

231231
if (mailmap) {
232232
rev->mailmap = xcalloc(1, sizeof(struct string_list));
233-
read_mailmap(rev->mailmap, NULL);
233+
read_mailmap(rev->mailmap);
234234
}
235235

236236
if (rev->pretty_given && rev->commit_format == CMIT_FMT_RAW) {

0 commit comments

Comments
 (0)