git-shortlog.txt: improve documentation about .mailmap files
The description on .mailmap made it seem like they are only useful for commits with a wrong address for an author, but they are about fixing the real name. Explain this better in the text, and replace the existing example with a new one that hopefully makes things clearer. Signed-off-by: Adeodato Simó <dato@net.com.org.es> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Adeodato Simó committed
Dec 27, 2008 at 19:23 UTC
3a882d9696ba2ba46adc107b92b4721e59bb60b4
1 file changed
+33
-7
Documentation/git-shortlog.txt
+33
-7
@@ -48,15 +48,41 @@ OPTIONS
48
FILES
49
-----
50
51
-If the file `.mailmap` exists, it will be used for mapping author
52
-email addresses to a real author name. One mapping per line, first
53
-the author name followed by the email address enclosed by
54
-'<' and '>'. Use hash '#' for comments. Example:
51
+If a file `.mailmap` exists at the toplevel of the repository,
52
+it is used to map an author email address to a canonical real name. This
53
+can be used to coalesce together commits by the same person where their
54
+name was spelled differently (whether with the same email address or
55
+not).
56
+
57
+Each line in the file consists, in this order, of the canonical real name
58
+of an author, whitespace, and an email address (enclosed by '<' and '>')
59
+to map to the name. Use hash '#' for comments, either on their own line,
60
+or after the email address.
61
+
62
+A canonical name may appear in more than one line, associated with
63
+different email addresses, but it doesn't make sense for a given address
64
+to appear more than once (if that happens, a later line overrides the
65
+earlier ones).
66
+
67
+So, for example, if your history contains commits by two authors, Jane
68
+and Joe, whose names appear in the repository under several forms:
69
+
70
+------------
71
+Joe Developer <joe@example.com>
72
+Joe R. Developer <joe@example.com>
73
+Jane Doe <jane@example.com>
74
+Jane Doe <jane@laptop.(none)>
75
+Jane D. <jane@desktop.(none)>
76
+------------
77
+
78
+Then, supposing Joe wants his middle name initial used, and Jane prefers
79
+her family name fully spelled out, a proper `.mailmap` file would look like:
80
81
------------
57
-# Keep alphabetized
58
-Adam Morrow <adam@localhost.localdomain>
59
-Eve Jones <eve@laptop.(none)>
82
+# Note how we don't need an entry for <jane@laptop.(none)>, because the
83
+# real name of that author is correct already, and coalesced directly.
84
+Jane Doe <jane@desktop.(none)>
85
+Joe R. Developer <joe@random.com>
86
------------
87
88
Author