Move mailmap documentation into separate file
Include it directly from git-shortlog.txt, and refer to it from pretty-format.txt. Signed-off-by: Marius Storm-Olsen <marius@trolltech.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Marius Storm-Olsen committed
Feb 8, 2009 at 15:34 UTC
7d48e9e6f77d336376c1a554eeff0590f77e1ee1
4 files changed
+94
-84
Documentation/git-blame.txt
+6
@@ -184,6 +184,12 @@ there is ever added information (like the commit encoding or extended
184
commit commentary), a blame viewer won't ever care.
185
186
187
+MAPPING AUTHORS
188
+---------------
189
+
190
+include::mailmap.txt[]
191
+
192
+
193
SEE ALSO
194
--------
195
linkgit:git-annotate[1]
Documentation/git-shortlog.txt
+9
-80
@@ -45,86 +45,15 @@ OPTIONS
45
and subsequent lines are indented by `indent2` spaces. `width`,
46
`indent1`, and `indent2` default to 76, 6 and 9 respectively.
47
48
-FILES
49
------
50
-
51
-If the file `.mailmap` exists at the toplevel of the repository, or at
52
-the location pointed to by the mailmap.file configuration option, it
53
-is used to map author and committer names and email addresses to
54
-canonical real names and email addresses.
55
-This mapping can be used to coalesce together commits by the same
56
-person where their name and/or email address was spelled differently.
57
-
58
-In the simple form, each line in the file consists of the canonical
59
-real name of an author, whitespace, and an email address used in the
60
-commit (enclosed by '<' and '>') to map to the name. Thus, looks like
61
-this
62
---
63
- Proper Name <commit@email.xx>
64
---
65
-
66
-The more complex forms are
67
---
68
- <proper@email.xx> <commit@email.xx>
69
---
70
-which allows mailmap to replace only the email part of a commit, and
71
---
72
- Proper Name <proper@email.xx> <commit@email.xx>
73
---
74
-which allows mailmap to replace both the name and the email of a
75
-commit matching the specified commit email address, and
76
---
77
- Proper Name <proper@email.xx> Commit Name <commit@email.xx>
78
---
79
-which allows mailmap to replace both the name and the email of a
80
-commit matching both the specified commit name and email address.
81
-
82
-Example 1: Your history contains commits by two authors, Jane
83
-and Joe, whose names appear in the repository under several forms:
84
-
85
-------------
86
-Joe Developer <joe@example.com>
87
-Joe R. Developer <joe@example.com>
88
-Jane Doe <jane@example.com>
89
-Jane Doe <jane@laptop.(none)>
90
-Jane D. <jane@desktop.(none)>
91
-------------
92
-
93
-Now suppose that Joe wants his middle name initial used, and Jane
94
-prefers her family name fully spelled out. A proper `.mailmap` file
95
-would look like:
96
-
97
-------------
98
-Jane Doe <jane@desktop.(none)>
99
-Joe R. Developer <joe@example.com>
100
-------------
101
-
102
-Note how we don't need an entry for <jane@laptop.(none)>, because the
103
-real name of that author is correct already, and coalesced directly.
104
-
105
-Example 2: Your repository contains commits from the following
106
-authors:
107
-
108
-------------
109
-nick1 <bugs@company.xx>
110
-nick2 <bugs@company.xx>
111
-nick2 <nick2@company.xx>
112
-santa <me@company.xx>
113
-claus <me@company.xx>
114
-CTO <cto@coompany.xx>
115
-------------
116
-
117
-Then, you might want a `.mailmap` file looking like:
118
-------------
119
-<cto@company.xx> <cto@coompany.xx>
120
-Some Dude <some@dude.xx> nick1 <bugs@company.xx>
121
-Other Author <other@author.xx> nick2 <bugs@company.xx>
122
-Other Author <other@author.xx> <nick2@company.xx>
123
-Santa Claus <santa.claus@northpole.xx> <me@company.xx>
124
-------------
125
-
126
-Use hash '#' for comments that are either on their own line, or after
127
-the email address.
48
+
49
+MAPPING AUTHORS
50
+---------------
51
+
52
+The `.mailmap` feature is used to coalesce together commits by the same
53
+person in the shortlog, where their name and/or email address was
54
+spelled differently.
55
+
56
+include::mailmap.txt[]
57
58
59
Author
Documentation/mailmap.txt
new
+75
@@ -0,0 +1,75 @@
1
+If the file `.mailmap` exists at the toplevel of the repository, or at
2
+the location pointed to by the mailmap.file configuration option, it
3
+is used to map author and committer names and email addresses to
4
+canonical real names and email addresses.
5
+
6
+In the simple form, each line in the file consists of the canonical
7
+real name of an author, whitespace, and an email address used in the
8
+commit (enclosed by '<' and '>') to map to the name. Thus, looks like
9
+this
10
+--
11
+ Proper Name <commit@email.xx>
12
+--
13
+
14
+The more complex forms are
15
+--
16
+ <proper@email.xx> <commit@email.xx>
17
+--
18
+which allows mailmap to replace only the email part of a commit, and
19
+--
20
+ Proper Name <proper@email.xx> <commit@email.xx>
21
+--
22
+which allows mailmap to replace both the name and the email of a
23
+commit matching the specified commit email address, and
24
+--
25
+ Proper Name <proper@email.xx> Commit Name <commit@email.xx>
26
+--
27
+which allows mailmap to replace both the name and the email of a
28
+commit matching both the specified commit name and email address.
29
+
30
+Example 1: Your history contains commits by two authors, Jane
31
+and Joe, whose names appear in the repository under several forms:
32
+
33
+------------
34
+Joe Developer <joe@example.com>
35
+Joe R. Developer <joe@example.com>
36
+Jane Doe <jane@example.com>
37
+Jane Doe <jane@laptop.(none)>
38
+Jane D. <jane@desktop.(none)>
39
+------------
40
+
41
+Now suppose that Joe wants his middle name initial used, and Jane
42
+prefers her family name fully spelled out. A proper `.mailmap` file
43
+would look like:
44
+
45
+------------
46
+Jane Doe <jane@desktop.(none)>
47
+Joe R. Developer <joe@example.com>
48
+------------
49
+
50
+Note how we don't need an entry for <jane@laptop.(none)>, because the
51
+real name of that author is correct already.
52
+
53
+Example 2: Your repository contains commits from the following
54
+authors:
55
+
56
+------------
57
+nick1 <bugs@company.xx>
58
+nick2 <bugs@company.xx>
59
+nick2 <nick2@company.xx>
60
+santa <me@company.xx>
61
+claus <me@company.xx>
62
+CTO <cto@coompany.xx>
63
+------------
64
+
65
+Then, you might want a `.mailmap` file looking like:
66
+------------
67
+<cto@company.xx> <cto@coompany.xx>
68
+Some Dude <some@dude.xx> nick1 <bugs@company.xx>
69
+Other Author <other@author.xx> nick2 <bugs@company.xx>
70
+Other Author <other@author.xx> <nick2@company.xx>
71
+Santa Claus <santa.claus@northpole.xx> <me@company.xx>
72
+------------
73
+
74
+Use hash '#' for comments that are either on their own line, or after
75
+the email address.
\ No newline at end of file
Documentation/pretty-formats.txt
+4
-4
@@ -101,18 +101,18 @@ The placeholders are:
101
- '%P': parent hashes
102
- '%p': abbreviated parent hashes
103
- '%an': author name
104
-- '%aN': author name (respecting .mailmap)
104
+- '%aN': author name (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1])
105
- '%ae': author email
106
-- '%aE': author email (respecting .mailmap)
106
+- '%aE': author email (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1])
107
- '%ad': author date (format respects --date= option)
108
- '%aD': author date, RFC2822 style
109
- '%ar': author date, relative
110
- '%at': author date, UNIX timestamp
111
- '%ai': author date, ISO 8601 format
112
- '%cn': committer name
113
-- '%cN': committer name (respecting .mailmap)
113
+- '%cN': committer name (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1])
114
- '%ce': committer email
115
-- '%cE': committer email (respecting .mailmap)
115
+- '%cE': committer email (respecting .mailmap, see linkgit:git-shortlog[1] or linkgit:git-blame[1])
116
- '%cd': committer date
117
- '%cD': committer date, RFC2822 style
118
- '%cr': committer date, relative