1GIT-SHORTLOG(1) Git Manual GIT-SHORTLOG(1)
2
6 git-shortlog - Summarize 'git log' output
7
9 git shortlog [<options>] [<revision range>] [[--] <path>...]
10 git log --pretty=short | git shortlog [<options>]
11
13 Summarizes git log output in a format suitable for inclusion in release
14 announcements. Each commit will be grouped by author and title.
15 Additionally, "[PATCH]" will be stripped from the commit description.
17 If no revisions are passed on the command line and either standard
19 input is not a terminal or there is no current branch, git shortlog
20 will output a summary of the log read from standard input, without
21 reference to the current repository.
22
24 -n, --numbered
25 Sort output according to the number of commits per author instead
26 of author alphabetic order.
27 -s, --summary
29 Suppress commit description and provide a commit count summary
30 only.
31 -e, --email
33 Show the email address of each author.
34 --format[=<format>]
36 Instead of the commit subject, use some other information to
37 describe each commit. <format> can be any string accepted by the
38 --format option of git log, such as * [%h] %s. (See the "PRETTY
39 FORMATS" section of git-log(1).)
40 Each pretty-printed commit will be rewrapped before it is shown.
42 -c, --committer
44 Collect and show committer identities instead of authors.
45 -w[<width>[,<indent1>[,<indent2>]]]
47 Linewrap the output by wrapping each line at width. The first line
48 of each entry is indented by indent1 spaces, and the second and
49 subsequent lines are indented by indent2 spaces. width, indent1,
50 and indent2 default to 76, 6 and 9 respectively.
51 If width is 0 (zero) then indent the lines of the output without
53 wrapping them.
54 <revision range>
56 Show only commits in the specified revision range. When no
57 <revision range> is specified, it defaults to HEAD (i.e. the whole
58 history leading to the current commit). origin..HEAD specifies all
59 the commits reachable from the current commit (i.e. HEAD), but not
60 from origin. For a complete list of ways to spell <revision range>,
61 see the "Specifying Ranges" section of gitrevisions(7).
62 [--] <path>...
64 Consider only commits that are enough to explain how the files that
65 match the specified paths came to be.
66 Paths may need to be prefixed with -- to separate them from options
68 or the revision range, when confusion arises.
69 Commit Limiting
71 Besides specifying a range of commits that should be listed using the
72 special notations explained in the description, additional commit
73 limiting may be applied.
74 Using more options generally further limits the output (e.g.
76 --since=<date1> limits to commits newer than <date1>, and using it with
77 --grep=<pattern> further limits to commits whose log message has a line
78 that matches <pattern>), unless otherwise noted.
79 Note that these are applied before commit ordering and formatting
81 options, such as --reverse.
82 -<number>, -n <number>, --max-count=<number>
84 Limit the number of commits to output.
85 --skip=<number>
87 Skip number commits before starting to show the commit output.
88 --since=<date>, --after=<date>
90 Show commits more recent than a specific date.
91 --until=<date>, --before=<date>
93 Show commits older than a specific date.
94 --author=<pattern>, --committer=<pattern>
96 Limit the commits output to ones with author/committer header lines
97 that match the specified pattern (regular expression). With more
98 than one --author=<pattern>, commits whose author matches any of
99 the given patterns are chosen (similarly for multiple
100 --committer=<pattern>).
101 --grep-reflog=<pattern>
103 Limit the commits output to ones with reflog entries that match the
104 specified pattern (regular expression). With more than one
105 --grep-reflog, commits whose reflog message matches any of the
106 given patterns are chosen. It is an error to use this option unless
107 --walk-reflogs is in use.
108 --grep=<pattern>
110 Limit the commits output to ones with log message that matches the
111 specified pattern (regular expression). With more than one
112 --grep=<pattern>, commits whose message matches any of the given
113 patterns are chosen (but see --all-match).
114 When --notes is in effect, the message from the notes is matched as
116 if it were part of the log message.
117 --all-match
119 Limit the commits output to ones that match all given --grep,
120 instead of ones that match at least one.
121 --invert-grep
123 Limit the commits output to ones with log message that do not match
124 the pattern specified with --grep=<pattern>.
125 -i, --regexp-ignore-case
127 Match the regular expression limiting patterns without regard to
128 letter case.
129 --basic-regexp
131 Consider the limiting patterns to be basic regular expressions;
132 this is the default.
133 -E, --extended-regexp
135 Consider the limiting patterns to be extended regular expressions
136 instead of the default basic regular expressions.
137 -F, --fixed-strings
139 Consider the limiting patterns to be fixed strings (don’t interpret
140 pattern as a regular expression).
141 -P, --perl-regexp
143 Consider the limiting patterns to be Perl-compatible regular
144 expressions.
145 Support for these types of regular expressions is an optional
147 compile-time dependency. If Git wasn’t compiled with support for
148 them providing this option will cause it to die.
149 --remove-empty
151 Stop when a given path disappears from the tree.
152 --merges
154 Print only merge commits. This is exactly the same as
155 --min-parents=2.
156 --no-merges
158 Do not print commits with more than one parent. This is exactly the
159 same as --max-parents=1.
160 --min-parents=<number>, --max-parents=<number>, --no-min-parents,
162 --no-max-parents
163 Show only commits which have at least (or at most) that many parent
164 commits. In particular, --max-parents=1 is the same as --no-merges,
165 --min-parents=2 is the same as --merges. --max-parents=0 gives all
166 root commits and --min-parents=3 all octopus merges.
167 --no-min-parents and --no-max-parents reset these limits (to no
169 limit) again. Equivalent forms are --min-parents=0 (any commit has
170 0 or more parents) and --max-parents=-1 (negative numbers denote no
171 upper limit).
172 --first-parent
174 Follow only the first parent commit upon seeing a merge commit.
175 This option can give a better overview when viewing the evolution
176 of a particular topic branch, because merges into a topic branch
177 tend to be only about adjusting to updated upstream from time to
178 time, and this option allows you to ignore the individual commits
179 brought in to your history by such a merge. Cannot be combined with
180 --bisect.
181 --not
183 Reverses the meaning of the ^ prefix (or lack thereof) for all
184 following revision specifiers, up to the next --not.
185 --all
187 Pretend as if all the refs in refs/, along with HEAD, are listed on
188 the command line as <commit>.
189 --branches[=<pattern>]
191 Pretend as if all the refs in refs/heads are listed on the command
192 line as <commit>. If <pattern> is given, limit branches to ones
193 matching given shell glob. If pattern lacks ?, *, or [, /* at the
194 end is implied.
195 --tags[=<pattern>]
197 Pretend as if all the refs in refs/tags are listed on the command
198 line as <commit>. If <pattern> is given, limit tags to ones
199 matching given shell glob. If pattern lacks ?, *, or [, /* at the
200 end is implied.
201 --remotes[=<pattern>]
203 Pretend as if all the refs in refs/remotes are listed on the
204 command line as <commit>. If <pattern> is given, limit
205 remote-tracking branches to ones matching given shell glob. If
206 pattern lacks ?, *, or [, /* at the end is implied.
207 --glob=<glob-pattern>
209 Pretend as if all the refs matching shell glob <glob-pattern> are
210 listed on the command line as <commit>. Leading refs/, is
211 automatically prepended if missing. If pattern lacks ?, *, or [, /*
212 at the end is implied.
213 --exclude=<glob-pattern>
215 Do not include refs matching <glob-pattern> that the next --all,
216 --branches, --tags, --remotes, or --glob would otherwise consider.
217 Repetitions of this option accumulate exclusion patterns up to the
218 next --all, --branches, --tags, --remotes, or --glob option (other
219 options or arguments do not clear accumulated patterns).
220 The patterns given should not begin with refs/heads, refs/tags, or
222 refs/remotes when applied to --branches, --tags, or --remotes,
223 respectively, and they must begin with refs/ when applied to --glob
224 or --all. If a trailing /* is intended, it must be given
225 explicitly.
226 --reflog
228 Pretend as if all objects mentioned by reflogs are listed on the
229 command line as <commit>.
230 --alternate-refs
232 Pretend as if all objects mentioned as ref tips of alternate
233 repositories were listed on the command line. An alternate
234 repository is any repository whose object directory is specified in
235 objects/info/alternates. The set of included objects may be
236 modified by core.alternateRefsCommand, etc. See git-config(1).
237 --single-worktree
239 By default, all working trees will be examined by the following
240 options when there are more than one (see git-worktree(1)): --all,
241 --reflog and --indexed-objects. This option forces them to examine
242 the current working tree only.
243 --ignore-missing
245 Upon seeing an invalid object name in the input, pretend as if the
246 bad input was not given.
247 --bisect
249 Pretend as if the bad bisection ref refs/bisect/bad was listed and
250 as if it was followed by --not and the good bisection refs
251 refs/bisect/good-* on the command line. Cannot be combined with
252 --first-parent.
253 --stdin
255 In addition to the <commit> listed on the command line, read them
256 from the standard input. If a -- separator is seen, stop reading
257 commits and start reading paths to limit the result.
258 --cherry-mark
260 Like --cherry-pick (see below) but mark equivalent commits with =
261 rather than omitting them, and inequivalent ones with +.
262 --cherry-pick
264 Omit any commit that introduces the same change as another commit
265 on the “other side” when the set of commits are limited with
266 symmetric difference.
267 For example, if you have two branches, A and B, a usual way to list
269 all commits on only one side of them is with --left-right (see the
270 example below in the description of the --left-right option).
271 However, it shows the commits that were cherry-picked from the
272 other branch (for example, “3rd on b” may be cherry-picked from
273 branch A). With this option, such pairs of commits are excluded
274 from the output.
275 --left-only, --right-only
277 List only commits on the respective side of a symmetric difference,
278 i.e. only those which would be marked < resp. > by --left-right.
279 For example, --cherry-pick --right-only A...B omits those commits
281 from B which are in A or are patch-equivalent to a commit in A. In
282 other words, this lists the + commits from git cherry A B. More
283 precisely, --cherry-pick --right-only --no-merges gives the exact
284 list.
285 --cherry
287 A synonym for --right-only --cherry-mark --no-merges; useful to
288 limit the output to the commits on our side and mark those that
289 have been applied to the other side of a forked history with git
290 log --cherry upstream...mybranch, similar to git cherry upstream
291 mybranch.
292 -g, --walk-reflogs
294 Instead of walking the commit ancestry chain, walk reflog entries
295 from the most recent one to older ones. When this option is used
296 you cannot specify commits to exclude (that is, ^commit,
297 commit1..commit2, and commit1...commit2 notations cannot be used).
298 With --pretty format other than oneline and reference (for obvious
300 reasons), this causes the output to have two extra lines of
301 information taken from the reflog. The reflog designator in the
302 output may be shown as ref@{Nth} (where Nth is the
303 reverse-chronological index in the reflog) or as ref@{timestamp}
304 (with the timestamp for that entry), depending on a few rules:
305 1. If the starting point is specified as ref@{Nth}, show the index
307 format.
308 2. If the starting point was specified as ref@{now}, show the
310 timestamp format.
311 3. If neither was used, but --date was given on the command line,
313 show the timestamp in the format requested by --date.
314 4. Otherwise, show the index format.
316 Under --pretty=oneline, the commit message is prefixed with this
318 information on the same line. This option cannot be combined with
319 --reverse. See also git-reflog(1).
320 Under --pretty=reference, this information will not be shown at
322 all.
323 --merge
325 After a failed merge, show refs that touch files having a conflict
326 and don’t exist on all heads to merge.
327 --boundary
329 Output excluded boundary commits. Boundary commits are prefixed
330 with -.
331 History Simplification
333 Sometimes you are only interested in parts of the history, for example
334 the commits modifying a particular <path>. But there are two parts of
335 History Simplification, one part is selecting the commits and the other
336 is how to do it, as there are various strategies to simplify the
337 history.
338 The following options select the commits to be shown:
340 <paths>
342 Commits modifying the given <paths> are selected.
343 --simplify-by-decoration
345 Commits that are referred by some branch or tag are selected.
346 Note that extra commits can be shown to give a meaningful history.
348 The following options affect the way the simplification is performed:
350 Default mode
352 Simplifies the history to the simplest history explaining the final
353 state of the tree. Simplest because it prunes some side branches if
354 the end result is the same (i.e. merging branches with the same
355 content)
356 --full-history
358 Same as the default mode, but does not prune some history.
359 --dense
361 Only the selected commits are shown, plus some to have a meaningful
362 history.
363 --sparse
365 All commits in the simplified history are shown.
366 --simplify-merges
368 Additional option to --full-history to remove some needless merges
369 from the resulting history, as there are no selected commits
370 contributing to this merge.
371 --ancestry-path
373 When given a range of commits to display (e.g. commit1..commit2 or
374 commit2 ^commit1), only display commits that exist directly on the
375 ancestry chain between the commit1 and commit2, i.e. commits that
376 are both descendants of commit1, and ancestors of commit2.
377 A more detailed explanation follows.
379 Suppose you specified foo as the <paths>. We shall call commits that
381 modify foo !TREESAME, and the rest TREESAME. (In a diff filtered for
382 foo, they look different and equal, respectively.)
383 In the following, we will always refer to the same example history to
385 illustrate the differences between simplification settings. We assume
386 that you are filtering for a file foo in this commit graph:
387 .-A---M---N---O---P---Q
389 / / / / / /
390 I B C D E Y
391 \ / / / / /
392 `-------------' X
393 The horizontal line of history A---Q is taken to be the first parent of
395 each merge. The commits are:
396 · I is the initial commit, in which foo exists with contents “asdf”,
398 and a file quux exists with contents “quux”. Initial commits are
399 compared to an empty tree, so I is !TREESAME.
400 · In A, foo contains just “foo”.
402 · B contains the same change as A. Its merge M is trivial and hence
404 TREESAME to all parents.
405 · C does not change foo, but its merge N changes it to “foobar”, so
407 it is not TREESAME to any parent.
408 · D sets foo to “baz”. Its merge O combines the strings from N and D
410 to “foobarbaz”; i.e., it is not TREESAME to any parent.
411 · E changes quux to “xyzzy”, and its merge P combines the strings to
413 “quux xyzzy”. P is TREESAME to O, but not to E.
414 · X is an independent root commit that added a new file side, and Y
416 modified it. Y is TREESAME to X. Its merge Q added side to P, and
417 Q is TREESAME to P, but not to Y.
418 rev-list walks backwards through history, including or excluding
420 commits based on whether --full-history and/or parent rewriting (via
421 --parents or --children) are used. The following settings are
422 available.
423 Default mode
425 Commits are included if they are not TREESAME to any parent (though
426 this can be changed, see --sparse below). If the commit was a
427 merge, and it was TREESAME to one parent, follow only that parent.
428 (Even if there are several TREESAME parents, follow only one of
429 them.) Otherwise, follow all parents.
430 This results in:
432 .-A---N---O
434 / / /
435 I---------D
436 Note how the rule to only follow the TREESAME parent, if one is
438 available, removed B from consideration entirely. C was considered
439 via N, but is TREESAME. Root commits are compared to an empty tree,
440 so I is !TREESAME.
441 Parent/child relations are only visible with --parents, but that
443 does not affect the commits selected in default mode, so we have
444 shown the parent lines.
445 --full-history without parent rewriting
447 This mode differs from the default in one point: always follow all
448 parents of a merge, even if it is TREESAME to one of them. Even if
449 more than one side of the merge has commits that are included, this
450 does not imply that the merge itself is! In the example, we get
451 I A B N D O P Q
453 M was excluded because it is TREESAME to both parents. E, C and B
455 were all walked, but only B was !TREESAME, so the others do not
456 appear.
457 Note that without parent rewriting, it is not really possible to
459 talk about the parent/child relationships between the commits, so
460 we show them disconnected.
461 --full-history with parent rewriting
463 Ordinary commits are only included if they are !TREESAME (though
464 this can be changed, see --sparse below).
465 Merges are always included. However, their parent list is
467 rewritten: Along each parent, prune away commits that are not
468 included themselves. This results in
469 .-A---M---N---O---P---Q
471 / / / / /
472 I B / D /
473 \ / / / /
474 `-------------'
475 Compare to --full-history without rewriting above. Note that E was
477 pruned away because it is TREESAME, but the parent list of P was
478 rewritten to contain E's parent I. The same happened for C and N,
479 and X, Y and Q.
480 In addition to the above settings, you can change whether TREESAME
482 affects inclusion:
483 --dense
485 Commits that are walked are included if they are not TREESAME to
486 any parent.
487 --sparse
489 All commits that are walked are included.
490 Note that without --full-history, this still simplifies merges: if
492 one of the parents is TREESAME, we follow only that one, so the
493 other sides of the merge are never walked.
494 --simplify-merges
496 First, build a history graph in the same way that --full-history
497 with parent rewriting does (see above).
498 Then simplify each commit C to its replacement C' in the final
500 history according to the following rules:
501 · Set C' to C.
503 · Replace each parent P of C' with its simplification P'. In the
505 process, drop parents that are ancestors of other parents or
506 that are root commits TREESAME to an empty tree, and remove
507 duplicates, but take care to never drop all parents that we are
508 TREESAME to.
509 · If after this parent rewriting, C' is a root or merge commit
511 (has zero or >1 parents), a boundary commit, or !TREESAME, it
512 remains. Otherwise, it is replaced with its only parent.
513 The effect of this is best shown by way of comparing to
515 --full-history with parent rewriting. The example turns into:
516 .-A---M---N---O
518 / / /
519 I B D
520 \ / /
521 `---------'
522 Note the major differences in N, P, and Q over --full-history:
524 · N's parent list had I removed, because it is an ancestor of the
526 other parent M. Still, N remained because it is !TREESAME.
527 · P's parent list similarly had I removed. P was then removed
529 completely, because it had one parent and is TREESAME.
530 · Q's parent list had Y simplified to X. X was then removed,
532 because it was a TREESAME root. Q was then removed completely,
533 because it had one parent and is TREESAME.
534 Finally, there is a fifth simplification mode available:
536 --ancestry-path
538 Limit the displayed commits to those directly on the ancestry chain
539 between the “from” and “to” commits in the given commit range. I.e.
540 only display commits that are ancestor of the “to” commit and
541 descendants of the “from” commit.
542 As an example use case, consider the following commit history:
544 D---E-------F
546 / \ \
547 B---C---G---H---I---J
548 / \
549 A-------K---------------L--M
550 A regular D..M computes the set of commits that are ancestors of M,
552 but excludes the ones that are ancestors of D. This is useful to
553 see what happened to the history leading to M since D, in the sense
554 that “what does M have that did not exist in D”. The result in this
555 example would be all the commits, except A and B (and D itself, of
556 course).
557 When we want to find out what commits in M are contaminated with
559 the bug introduced by D and need fixing, however, we might want to
560 view only the subset of D..M that are actually descendants of D,
561 i.e. excluding C and K. This is exactly what the --ancestry-path
562 option does. Applied to the D..M range, it results in:
563 E-------F
565 \ \
566 G---H---I---J
567 \
568 L--M
569 The --simplify-by-decoration option allows you to view only the big
571 picture of the topology of the history, by omitting commits that are
572 not referenced by tags. Commits are marked as !TREESAME (in other
573 words, kept after history simplification rules described above) if (1)
574 they are referenced by tags, or (2) they change the contents of the
575 paths given on the command line. All other commits are marked as
576 TREESAME (subject to be simplified away).
577
579 The .mailmap feature is used to coalesce together commits by the same
580 person in the shortlog, where their name and/or email address was
581 spelled differently.
582 If the file .mailmap exists at the toplevel of the repository, or at
584 the location pointed to by the mailmap.file or mailmap.blob
585 configuration options, it is used to map author and committer names and
586 email addresses to canonical real names and email addresses.
587 In the simple form, each line in the file consists of the canonical
589 real name of an author, whitespace, and an email address used in the
590 commit (enclosed by < and >) to map to the name. For example:
591 Proper Name <commit@email.xx>
593 The more complex forms are:
595 <proper@email.xx> <commit@email.xx>
597 which allows mailmap to replace only the email part of a commit, and:
599 Proper Name <proper@email.xx> <commit@email.xx>
601 which allows mailmap to replace both the name and the email of a commit
603 matching the specified commit email address, and:
604 Proper Name <proper@email.xx> Commit Name <commit@email.xx>
606 which allows mailmap to replace both the name and the email of a commit
608 matching both the specified commit name and email address.
609 Example 1: Your history contains commits by two authors, Jane and Joe,
611 whose names appear in the repository under several forms:
612 Joe Developer <joe@example.com>
614 Joe R. Developer <joe@example.com>
615 Jane Doe <jane@example.com>
616 Jane Doe <jane@laptop.(none)>
617 Jane D. <jane@desktop.(none)>
618 Now suppose that Joe wants his middle name initial used, and Jane
620 prefers her family name fully spelled out. A proper .mailmap file would
621 look like:
622 Jane Doe <jane@desktop.(none)>
624 Joe R. Developer <joe@example.com>
625 Note how there is no need for an entry for <jane@laptop.(none)>,
627 because the real name of that author is already correct.
628 Example 2: Your repository contains commits from the following authors:
630 nick1 <bugs@company.xx>
632 nick2 <bugs@company.xx>
633 nick2 <nick2@company.xx>
634 santa <me@company.xx>
635 claus <me@company.xx>
636 CTO <cto@coompany.xx>
637 Then you might want a .mailmap file that looks like:
639 <cto@company.xx> <cto@coompany.xx>
641 Some Dude <some@dude.xx> nick1 <bugs@company.xx>
642 Other Author <other@author.xx> nick2 <bugs@company.xx>
643 Other Author <other@author.xx> <nick2@company.xx>
644 Santa Claus <santa.claus@northpole.xx> <me@company.xx>
645 Use hash # for comments that are either on their own line, or after the
647 email address.
648
650 Part of the git(1) suite
651Git 2.26.2 2020-04-20 GIT-SHORTLOG(1)