Add map_user() and clear_mailmap() to mailmap
[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
0925ce4d
MSO
51If the file `.mailmap` exists at the toplevel of the repository, or at
52the location pointed to by the mailmap.file configuration option, it
53is used to map author and committer names and email addresses to
54canonical real names and email addresses.
55This mapping can be used to coalesce together commits by the same
56person where their name and/or email address was spelled differently.
57
58In the simple form, each line in the file consists of the canonical
59real name of an author, whitespace, and an email address used in the
60commit (enclosed by '<' and '>') to map to the name. Thus, looks like
61this
62--
63 Proper Name <commit@email.xx>
64--
65
66The more complex forms are
67--
68 <proper@email.xx> <commit@email.xx>
69--
70which allows mailmap to replace only the email part of a commit, and
71--
72 Proper Name <proper@email.xx> <commit@email.xx>
73--
74which allows mailmap to replace both the name and the email of a
75commit matching the specified commit email address, and
76--
77 Proper Name <proper@email.xx> Commit Name <commit@email.xx>
78--
79which allows mailmap to replace both the name and the email of a
80commit matching both the specified commit name and email address.
81
82Example 1: Your history contains commits by two authors, Jane
3a882d96
AS
83and Joe, whose names appear in the repository under several forms:
84
85------------
86Joe Developer <joe@example.com>
87Joe R. Developer <joe@example.com>
88Jane Doe <jane@example.com>
89Jane Doe <jane@laptop.(none)>
90Jane D. <jane@desktop.(none)>
91------------
92
0925ce4d
MSO
93Now suppose that Joe wants his middle name initial used, and Jane
94prefers her family name fully spelled out. A proper `.mailmap` file
95would look like:
ba4c32bd
GH
96
97------------
0925ce4d 98Jane Doe <jane@desktop.(none)>
3fe2bf2f 99Joe R. Developer <joe@example.com>
ba4c32bd 100------------
3f971fc4 101
0925ce4d
MSO
102Note how we don't need an entry for <jane@laptop.(none)>, because the
103real name of that author is correct already, and coalesced directly.
104
105Example 2: Your repository contains commits from the following
106authors:
107
108------------
109nick1 <bugs@company.xx>
110nick2 <bugs@company.xx>
111nick2 <nick2@company.xx>
112santa <me@company.xx>
113claus <me@company.xx>
114CTO <cto@coompany.xx>
115------------
116
117Then, you might want a `.mailmap` file looking like:
118------------
119<cto@company.xx> <cto@coompany.xx>
120Some Dude <some@dude.xx> nick1 <bugs@company.xx>
121Other Author <other@author.xx> nick2 <bugs@company.xx>
122Other Author <other@author.xx> <nick2@company.xx>
123Santa Claus <santa.claus@northpole.xx> <me@company.xx>
124------------
125
126Use hash '#' for comments that are either on their own line, or after
127the email address.
128
129
3f971fc4
JH
130Author
131------
132Written by Jeff Garzik <jgarzik@pobox.com>
133
134Documentation
135--------------
136Documentation by Junio C Hamano.
137
138GIT
139---
9e1f0a85 140Part of the linkgit:git[1] suite