Add mailmap.file as configurational option for mailmap location
[git/git.git] / Documentation / git-shortlog.txt
CommitLineData
3f971fc4
JH
1git-shortlog(1)
2===============
3f971fc4
JH
3
4NAME
5----
467c0197 6git-shortlog - Summarize 'git-log' output
3f971fc4 7
3f971fc4
JH
8SYNOPSIS
9--------
0ad64fd0 10[verse]
b1889c36
JN
11git log --pretty=short | 'git shortlog' [-h] [-n] [-s] [-e] [-w]
12git shortlog [-n|--numbered] [-s|--summary] [-e|--email] [-w[<width>[,<indent1>[,<indent2>]]]] [<committish>...]
3f971fc4
JH
13
14DESCRIPTION
15-----------
ba020ef5 16Summarizes 'git-log' output in a format suitable for inclusion
4e27fb06 17in release announcements. Each commit will be grouped by author and
74237d62
JF
18the first line of the commit message will be shown.
19
20Additionally, "[PATCH]" will be stripped from the commit description.
21
4e27fb06
NP
22OPTIONS
23-------
24
3240240f
SB
25-h::
26--help::
4e27fb06
NP
27 Print a short usage message and exit.
28
3240240f
SB
29-n::
30--numbered::
4e27fb06
NP
31 Sort output according to the number of commits per author instead
32 of author alphabetic order.
33
3240240f
SB
34-s::
35--summary::
23bfbb81 36 Suppress commit description and provide a commit count summary only.
4e27fb06 37
3240240f
SB
38-e::
39--email::
6508bb75
JK
40 Show the email address of each author.
41
55ef8a46
JH
42-w[<width>[,<indent1>[,<indent2>]]]::
43 Linewrap the output by wrapping each line at `width`. The first
44 line of each entry is indented by `indent1` spaces, and the second
45 and subsequent lines are indented by `indent2` spaces. `width`,
46 `indent1`, and `indent2` default to 76, 6 and 9 respectively.
47
74237d62
JF
48FILES
49-----
0ad64fd0 50
d551a488
MSO
51If a file `.mailmap` exists at the toplevel of the repository, or at the
52location pointed to by the log.mailmap configuration option,
3a882d96
AS
53it is used to map an author email address to a canonical real name. This
54can be used to coalesce together commits by the same person where their
55name was spelled differently (whether with the same email address or
56not).
57
58Each line in the file consists, in this order, of the canonical real name
59of an author, whitespace, and an email address (enclosed by '<' and '>')
60to map to the name. Use hash '#' for comments, either on their own line,
61or after the email address.
62
63A canonical name may appear in more than one line, associated with
64different email addresses, but it doesn't make sense for a given address
65to appear more than once (if that happens, a later line overrides the
66earlier ones).
67
68So, for example, if your history contains commits by two authors, Jane
69and Joe, whose names appear in the repository under several forms:
70
71------------
72Joe Developer <joe@example.com>
73Joe R. Developer <joe@example.com>
74Jane Doe <jane@example.com>
75Jane Doe <jane@laptop.(none)>
76Jane D. <jane@desktop.(none)>
77------------
78
79Then, supposing Joe wants his middle name initial used, and Jane prefers
80her family name fully spelled out, a proper `.mailmap` file would look like:
ba4c32bd
GH
81
82------------
3a882d96
AS
83# Note how we don't need an entry for <jane@laptop.(none)>, because the
84# real name of that author is correct already, and coalesced directly.
85Jane Doe <jane@desktop.(none)>
3fe2bf2f 86Joe R. Developer <joe@example.com>
ba4c32bd 87------------
3f971fc4
JH
88
89Author
90------
91Written by Jeff Garzik <jgarzik@pobox.com>
92
93Documentation
94--------------
95Documentation by Junio C Hamano.
96
97GIT
98---
9e1f0a85 99Part of the linkgit:git[1] suite