blob: 771450dc4792612bf7bd58ebfff28b39a36d227f [file] [log] [blame]
'\" t
.\" Title: git-shortlog
.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\" Date: 11/18/2018
.\" Manual: Git Manual
.\" Source: Git 2.20.0.rc0
.\" Language: English
.\"
.TH "GIT\-SHORTLOG" "1" "11/18/2018" "Git 2\&.20\&.0\&.rc0" "Git Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
git-shortlog \- Summarize \(aqgit log\(aq output
.SH "SYNOPSIS"
.sp
.nf
\fIgit shortlog\fR [<options>] [<revision range>] [[\-\-] <path>\&...]
git log \-\-pretty=short | \fIgit shortlog\fR [<options>]
.fi
.sp
.SH "DESCRIPTION"
.sp
Summarizes \fIgit log\fR output in a format suitable for inclusion in release announcements\&. Each commit will be grouped by author and title\&.
.sp
Additionally, "[PATCH]" will be stripped from the commit description\&.
.sp
If no revisions are passed on the command line and either standard input is not a terminal or there is no current branch, \fIgit shortlog\fR will output a summary of the log read from standard input, without reference to the current repository\&.
.SH "OPTIONS"
.PP
\-n, \-\-numbered
.RS 4
Sort output according to the number of commits per author instead of author alphabetic order\&.
.RE
.PP
\-s, \-\-summary
.RS 4
Suppress commit description and provide a commit count summary only\&.
.RE
.PP
\-e, \-\-email
.RS 4
Show the email address of each author\&.
.RE
.PP
\-\-format[=<format>]
.RS 4
Instead of the commit subject, use some other information to describe each commit\&.
\fI<format>\fR
can be any string accepted by the
\fB\-\-format\fR
option of
\fIgit log\fR, such as
\fI* [%h] %s\fR\&. (See the "PRETTY FORMATS" section of
\fBgit-log\fR(1)\&.)
.sp
.if n \{\
.RS 4
.\}
.nf
Each pretty\-printed commit will be rewrapped before it is shown\&.
.fi
.if n \{\
.RE
.\}
.RE
.PP
\-c, \-\-committer
.RS 4
Collect and show committer identities instead of authors\&.
.RE
.PP
\-w[<width>[,<indent1>[,<indent2>]]]
.RS 4
Linewrap the output by wrapping each line at
\fBwidth\fR\&. The first line of each entry is indented by
\fBindent1\fR
spaces, and the second and subsequent lines are indented by
\fBindent2\fR
spaces\&.
\fBwidth\fR,
\fBindent1\fR, and
\fBindent2\fR
default to 76, 6 and 9 respectively\&.
.sp
If width is
\fB0\fR
(zero) then indent the lines of the output without wrapping them\&.
.RE
.PP
<revision range>
.RS 4
Show only commits in the specified revision range\&. When no <revision range> is specified, it defaults to
\fBHEAD\fR
(i\&.e\&. the whole history leading to the current commit)\&.
\fBorigin\&.\&.HEAD\fR
specifies all the commits reachable from the current commit (i\&.e\&.
\fBHEAD\fR), but not from
\fBorigin\fR\&. For a complete list of ways to spell <revision range>, see the "Specifying Ranges" section of
\fBgitrevisions\fR(7)\&.
.RE
.PP
[\-\-] <path>\&...
.RS 4
Consider only commits that are enough to explain how the files that match the specified paths came to be\&.
.sp
Paths may need to be prefixed with
\fB\-\-\fR
to separate them from options or the revision range, when confusion arises\&.
.RE
.SH "MAPPING AUTHORS"
.sp
The \fB\&.mailmap\fR feature is used to coalesce together commits by the same person in the shortlog, where their name and/or email address was spelled differently\&.
.sp
If the file \fB\&.mailmap\fR exists at the toplevel of the repository, or at the location pointed to by the mailmap\&.file or mailmap\&.blob configuration options, it is used to map author and committer names and email addresses to canonical real names and email addresses\&.
.sp
In the simple form, each line in the file consists of the canonical real name of an author, whitespace, and an email address used in the commit (enclosed by \fI<\fR and \fI>\fR) to map to the name\&. For example:
.sp
.if n \{\
.RS 4
.\}
.nf
Proper Name <commit@email\&.xx>
.fi
.if n \{\
.RE
.\}
.sp
The more complex forms are:
.sp
.if n \{\
.RS 4
.\}
.nf
<proper@email\&.xx> <commit@email\&.xx>
.fi
.if n \{\
.RE
.\}
.sp
which allows mailmap to replace only the email part of a commit, and:
.sp
.if n \{\
.RS 4
.\}
.nf
Proper Name <proper@email\&.xx> <commit@email\&.xx>
.fi
.if n \{\
.RE
.\}
.sp
which allows mailmap to replace both the name and the email of a commit matching the specified commit email address, and:
.sp
.if n \{\
.RS 4
.\}
.nf
Proper Name <proper@email\&.xx> Commit Name <commit@email\&.xx>
.fi
.if n \{\
.RE
.\}
.sp
which allows mailmap to replace both the name and the email of a commit matching both the specified commit name and email address\&.
.sp
Example 1: Your history contains commits by two authors, Jane and Joe, whose names appear in the repository under several forms:
.sp
.if n \{\
.RS 4
.\}
.nf
Joe Developer <joe@example\&.com>
Joe R\&. Developer <joe@example\&.com>
Jane Doe <jane@example\&.com>
Jane Doe <jane@laptop\&.(none)>
Jane D\&. <jane@desktop\&.(none)>
.fi
.if n \{\
.RE
.\}
.sp
.sp
Now suppose that Joe wants his middle name initial used, and Jane prefers her family name fully spelled out\&. A proper \fB\&.mailmap\fR file would look like:
.sp
.if n \{\
.RS 4
.\}
.nf
Jane Doe <jane@desktop\&.(none)>
Joe R\&. Developer <joe@example\&.com>
.fi
.if n \{\
.RE
.\}
.sp
.sp
Note how there is no need for an entry for \fB<jane@laptop\&.(none)>\fR, because the real name of that author is already correct\&.
.sp
Example 2: Your repository contains commits from the following authors:
.sp
.if n \{\
.RS 4
.\}
.nf
nick1 <bugs@company\&.xx>
nick2 <bugs@company\&.xx>
nick2 <nick2@company\&.xx>
santa <me@company\&.xx>
claus <me@company\&.xx>
CTO <cto@coompany\&.xx>
.fi
.if n \{\
.RE
.\}
.sp
.sp
Then you might want a \fB\&.mailmap\fR file that looks like:
.sp
.if n \{\
.RS 4
.\}
.nf
<cto@company\&.xx> <cto@coompany\&.xx>
Some Dude <some@dude\&.xx> nick1 <bugs@company\&.xx>
Other Author <other@author\&.xx> nick2 <bugs@company\&.xx>
Other Author <other@author\&.xx> <nick2@company\&.xx>
Santa Claus <santa\&.claus@northpole\&.xx> <me@company\&.xx>
.fi
.if n \{\
.RE
.\}
.sp
.sp
Use hash \fI#\fR for comments that are either on their own line, or after the email address\&.
.SH "GIT"
.sp
Part of the \fBgit\fR(1) suite