| blob | 443913d90045be324c7f7c0b72acdac8005c3559 |
1 '\" t
2 .\" Title: git-shortlog
3 .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
5 .\" Date: 2024-02-15
6 .\" Manual: Git Manual
7 .\" Source: Git 2.44.0.rc1.17.g3e0d3cd5c7
8 .\" Language: English
9 .\"
10 .TH "GIT\-SHORTLOG" "1" "2024\-02\-15" "Git 2\&.44\&.0\&.rc1\&.17\&.g3" "Git Manual"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 git-shortlog \- Summarize \*(Aqgit log\*(Aq output
32 .SH "SYNOPSIS"
33 .sp
34 .nf
35 \fIgit shortlog\fR [<options>] [<revision\-range>] [[\-\-] <path>\&...]
36 git log \-\-pretty=short | \fIgit shortlog\fR [<options>]
37 .fi
38 .sp
39 .SH "DESCRIPTION"
40 .sp
41 Summarizes \fIgit log\fR output in a format suitable for inclusion in release announcements\&. Each commit will be grouped by author and title\&.
42 .sp
43 Additionally, "[PATCH]" will be stripped from the commit description\&.
44 .sp
45 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\&.
46 .SH "OPTIONS"
47 .PP
48 \-n, \-\-numbered
49 .RS 4
50 Sort output according to the number of commits per author instead of author alphabetic order\&.
51 .RE
52 .PP
53 \-s, \-\-summary
54 .RS 4
55 Suppress commit description and provide a commit count summary only\&.
56 .RE
57 .PP
58 \-e, \-\-email
59 .RS 4
60 Show the email address of each author\&.
61 .RE
62 .PP
63 \-\-format[=<format>]
64 .RS 4
65 Instead of the commit subject, use some other information to describe each commit\&.
66 \fI<format>\fR
67 can be any string accepted by the
68 \fB\-\-format\fR
69 option of
70 \fIgit log\fR, such as
71 \fI* [%h] %s\fR\&. (See the "PRETTY FORMATS" section of
72 \fBgit-log\fR(1)\&.)
73 .sp
74 .if n \{\
75 .RS 4
76 .\}
77 .nf
78 Each pretty\-printed commit will be rewrapped before it is shown\&.
79 .fi
80 .if n \{\
81 .RE
82 .\}
83 .RE
84 .PP
85 \-\-date=<format>
86 .RS 4
87 Show dates formatted according to the given date string\&. (See the
88 \fB\-\-date\fR
89 option in the "Commit Formatting" section of
90 \fBgit-log\fR(1))\&. Useful with
91 \fB\-\-group=format:<format>\fR\&.
92 .RE
93 .PP
94 \-\-group=<type>
95 .RS 4
96 Group commits based on
97 \fB<type>\fR\&. If no
98 \fB\-\-group\fR
99 option is specified, the default is
100 \fBauthor\fR\&.
101 \fB<type>\fR
102 is one of:
103 .sp
104 .RS 4
105 .ie n \{\
106 \h'-04'\(bu\h'+03'\c
107 .\}
108 .el \{\
109 .sp -1
110 .IP \(bu 2.3
111 .\}
112 \fBauthor\fR, commits are grouped by author
113 .RE
114 .sp
115 .RS 4
116 .ie n \{\
117 \h'-04'\(bu\h'+03'\c
118 .\}
119 .el \{\
120 .sp -1
121 .IP \(bu 2.3
122 .\}
123 \fBcommitter\fR, commits are grouped by committer (the same as
124 \fB\-c\fR)
125 .RE
126 .sp
127 .RS 4
128 .ie n \{\
129 \h'-04'\(bu\h'+03'\c
130 .\}
131 .el \{\
132 .sp -1
133 .IP \(bu 2.3
134 .\}
135 \fBtrailer:<field>\fR, the
136 \fB<field>\fR
137 is interpreted as a case\-insensitive commit message trailer (see
138 \fBgit-interpret-trailers\fR(1))\&. For example, if your project uses
139 \fBReviewed\-by\fR
140 trailers, you might want to see who has been reviewing with
141 \fBgit shortlog \-ns \-\-group=trailer:reviewed\-by\fR\&.
142 .RE
143 .sp
144 .RS 4
145 .ie n \{\
146 \h'-04'\(bu\h'+03'\c
147 .\}
148 .el \{\
149 .sp -1
150 .IP \(bu 2.3
151 .\}
152 \fBformat:<format>\fR, any string accepted by the
153 \fB\-\-format\fR
154 option of
155 \fIgit log\fR\&. (See the "PRETTY FORMATS" section of
156 \fBgit-log\fR(1)\&.)
157 .sp
158 Note that commits that do not include the trailer will not be counted\&. Likewise, commits with multiple trailers (e\&.g\&., multiple signoffs) may be counted more than once (but only once per unique trailer value in that commit)\&.
159 .sp
160 Shortlog will attempt to parse each trailer value as a
161 \fBname <email>\fR
162 identity\&. If successful, the mailmap is applied and the email is omitted unless the
163 \fB\-\-email\fR
164 option is specified\&. If the value cannot be parsed as an identity, it will be taken literally and completely\&.
165 .RE
166 .sp
167 If
168 \fB\-\-group\fR
169 is specified multiple times, commits are counted under each value (but again, only once per unique value in that commit)\&. For example,
170 \fBgit shortlog \-\-group=author \-\-group=trailer:co\-authored\-by\fR
171 counts both authors and co\-authors\&.
172 .RE
173 .PP
174 \-c, \-\-committer
175 .RS 4
176 This is an alias for
177 \fB\-\-group=committer\fR\&.
178 .RE
179 .PP
180 \-w[<width>[,<indent1>[,<indent2>]]]
181 .RS 4
182 Linewrap the output by wrapping each line at
183 \fBwidth\fR\&. The first line of each entry is indented by
184 \fBindent1\fR
185 spaces, and the second and subsequent lines are indented by
186 \fBindent2\fR
187 spaces\&.
188 \fBwidth\fR,
189 \fBindent1\fR, and
190 \fBindent2\fR
191 default to 76, 6 and 9 respectively\&.
192 .sp
193 If width is
194 \fB0\fR
195 (zero) then indent the lines of the output without wrapping them\&.
196 .RE
197 .PP
198 <revision\-range>
199 .RS 4
200 Show only commits in the specified revision range\&. When no <revision\-range> is specified, it defaults to
201 \fBHEAD\fR
202 (i\&.e\&. the whole history leading to the current commit)\&.
203 \fBorigin\&.\&.HEAD\fR
204 specifies all the commits reachable from the current commit (i\&.e\&.
205 \fBHEAD\fR), but not from
206 \fBorigin\fR\&. For a complete list of ways to spell <revision\-range>, see the "Specifying Ranges" section of
207 \fBgitrevisions\fR(7)\&.
208 .RE
209 .PP
210 [\-\-] <path>\&...
211 .RS 4
212 Consider only commits that are enough to explain how the files that match the specified paths came to be\&.
213 .sp
214 Paths may need to be prefixed with
215 \fB\-\-\fR
216 to separate them from options or the revision range, when confusion arises\&.
217 .RE
218 .SS "Commit Limiting"
219 .sp
220 Besides specifying a range of commits that should be listed using the special notations explained in the description, additional commit limiting may be applied\&.
221 .sp
222 Using more options generally further limits the output (e\&.g\&. \fB\-\-since=<date1>\fR limits to commits newer than \fB<date1>\fR, and using it with \fB\-\-grep=<pattern>\fR further limits to commits whose log message has a line that matches \fB<pattern>\fR), unless otherwise noted\&.
223 .sp
224 Note that these are applied before commit ordering and formatting options, such as \fB\-\-reverse\fR\&.
225 .PP
226 \-<number>, \-n <number>, \-\-max\-count=<number>
227 .RS 4
228 Limit the number of commits to output\&.
229 .RE
230 .PP
231 \-\-skip=<number>
232 .RS 4
233 Skip
234 \fInumber\fR
235 commits before starting to show the commit output\&.
236 .RE
237 .PP
238 \-\-since=<date>, \-\-after=<date>
239 .RS 4
240 Show commits more recent than a specific date\&.
241 .RE
242 .PP
243 \-\-since\-as\-filter=<date>
244 .RS 4
245 Show all commits more recent than a specific date\&. This visits all commits in the range, rather than stopping at the first commit which is older than a specific date\&.
246 .RE
247 .PP
248 \-\-until=<date>, \-\-before=<date>
249 .RS 4
250 Show commits older than a specific date\&.
251 .RE
252 .PP
253 \-\-author=<pattern>, \-\-committer=<pattern>
254 .RS 4
255 Limit the commits output to ones with author/committer header lines that match the specified pattern (regular expression)\&. With more than one
256 \fB\-\-author=<pattern>\fR, commits whose author matches any of the given patterns are chosen (similarly for multiple
257 \fB\-\-committer=<pattern>\fR)\&.
258 .RE
259 .PP
260 \-\-grep\-reflog=<pattern>
261 .RS 4
262 Limit the commits output to ones with reflog entries that match the specified pattern (regular expression)\&. With more than one
263 \fB\-\-grep\-reflog\fR, commits whose reflog message matches any of the given patterns are chosen\&. It is an error to use this option unless
264 \fB\-\-walk\-reflogs\fR
265 is in use\&.
266 .RE
267 .PP
268 \-\-grep=<pattern>
269 .RS 4
270 Limit the commits output to ones with a log message that matches the specified pattern (regular expression)\&. With more than one
271 \fB\-\-grep=<pattern>\fR, commits whose message matches any of the given patterns are chosen (but see
272 \fB\-\-all\-match\fR)\&.
273 .sp
274 When
275 \fB\-\-notes\fR
276 is in effect, the message from the notes is matched as if it were part of the log message\&.
277 .RE
278 .PP
279 \-\-all\-match
280 .RS 4
281 Limit the commits output to ones that match all given
282 \fB\-\-grep\fR, instead of ones that match at least one\&.
283 .RE
284 .PP
285 \-\-invert\-grep
286 .RS 4
287 Limit the commits output to ones with a log message that do not match the pattern specified with
288 \fB\-\-grep=<pattern>\fR\&.
289 .RE
290 .PP
291 \-i, \-\-regexp\-ignore\-case
292 .RS 4
293 Match the regular expression limiting patterns without regard to letter case\&.
294 .RE
295 .PP
296 \-\-basic\-regexp
297 .RS 4
298 Consider the limiting patterns to be basic regular expressions; this is the default\&.
299 .RE
300 .PP
301 \-E, \-\-extended\-regexp
302 .RS 4
303 Consider the limiting patterns to be extended regular expressions instead of the default basic regular expressions\&.
304 .RE
305 .PP
306 \-F, \-\-fixed\-strings
307 .RS 4
308 Consider the limiting patterns to be fixed strings (don\(cqt interpret pattern as a regular expression)\&.
309 .RE
310 .PP
311 \-P, \-\-perl\-regexp
312 .RS 4
313 Consider the limiting patterns to be Perl\-compatible regular expressions\&.
314 .sp
315 Support for these types of regular expressions is an optional compile\-time dependency\&. If Git wasn\(cqt compiled with support for them providing this option will cause it to die\&.
316 .RE
317 .PP
318 \-\-remove\-empty
319 .RS 4
320 Stop when a given path disappears from the tree\&.
321 .RE
322 .PP
323 \-\-merges
324 .RS 4
325 Print only merge commits\&. This is exactly the same as
326 \fB\-\-min\-parents=2\fR\&.
327 .RE
328 .PP
329 \-\-no\-merges
330 .RS 4
331 Do not print commits with more than one parent\&. This is exactly the same as
332 \fB\-\-max\-parents=1\fR\&.
333 .RE
334 .PP
335 \-\-min\-parents=<number>, \-\-max\-parents=<number>, \-\-no\-min\-parents, \-\-no\-max\-parents
336 .RS 4
337 Show only commits which have at least (or at most) that many parent commits\&. In particular,
338 \fB\-\-max\-parents=1\fR
339 is the same as
340 \fB\-\-no\-merges\fR,
341 \fB\-\-min\-parents=2\fR
342 is the same as
343 \fB\-\-merges\fR\&.
344 \fB\-\-max\-parents=0\fR
345 gives all root commits and
346 \fB\-\-min\-parents=3\fR
347 all octopus merges\&.
348 .sp
349 \fB\-\-no\-min\-parents\fR
350 and
351 \fB\-\-no\-max\-parents\fR
352 reset these limits (to no limit) again\&. Equivalent forms are
353 \fB\-\-min\-parents=0\fR
354 (any commit has 0 or more parents) and
355 \fB\-\-max\-parents=\-1\fR
356 (negative numbers denote no upper limit)\&.
357 .RE
358 .PP
359 \-\-first\-parent
360 .RS 4
361 When finding commits to include, follow only the first parent commit upon seeing a merge commit\&. This option can give a better overview when viewing the evolution of a particular topic branch, because merges into a topic branch tend to be only about adjusting to updated upstream from time to time, and this option allows you to ignore the individual commits brought in to your history by such a merge\&.
362 .RE
363 .PP
364 \-\-exclude\-first\-parent\-only
365 .RS 4
366 When finding commits to exclude (with a
367 \fI^\fR), follow only the first parent commit upon seeing a merge commit\&. This can be used to find the set of changes in a topic branch from the point where it diverged from the remote branch, given that arbitrary merges can be valid topic branch changes\&.
368 .RE
369 .PP
370 \-\-not
371 .RS 4
372 Reverses the meaning of the
373 \fI^\fR
374 prefix (or lack thereof) for all following revision specifiers, up to the next
375 \fB\-\-not\fR\&. When used on the command line before \-\-stdin, the revisions passed through stdin will not be affected by it\&. Conversely, when passed via standard input, the revisions passed on the command line will not be affected by it\&.
376 .RE
377 .PP
378 \-\-all
379 .RS 4
380 Pretend as if all the refs in
381 \fBrefs/\fR, along with
382 \fBHEAD\fR, are listed on the command line as
383 \fI<commit>\fR\&.
384 .RE
385 .PP
386 \-\-branches[=<pattern>]
387 .RS 4
388 Pretend as if all the refs in
389 \fBrefs/heads\fR
390 are listed on the command line as
391 \fI<commit>\fR\&. If
392 \fI<pattern>\fR
393 is given, limit branches to ones matching given shell glob\&. If pattern lacks
394 \fI?\fR,
395 \fI*\fR, or
396 \fI[\fR,
397 \fI/*\fR
398 at the end is implied\&.
399 .RE
400 .PP
401 \-\-tags[=<pattern>]
402 .RS 4
403 Pretend as if all the refs in
404 \fBrefs/tags\fR
405 are listed on the command line as
406 \fI<commit>\fR\&. If
407 \fI<pattern>\fR
408 is given, limit tags to ones matching given shell glob\&. If pattern lacks
409 \fI?\fR,
410 \fI*\fR, or
411 \fI[\fR,
412 \fI/*\fR
413 at the end is implied\&.
414 .RE
415 .PP
416 \-\-remotes[=<pattern>]
417 .RS 4
418 Pretend as if all the refs in
419 \fBrefs/remotes\fR
420 are listed on the command line as
421 \fI<commit>\fR\&. If
422 \fI<pattern>\fR
423 is given, limit remote\-tracking branches to ones matching given shell glob\&. If pattern lacks
424 \fI?\fR,
425 \fI*\fR, or
426 \fI[\fR,
427 \fI/*\fR
428 at the end is implied\&.
429 .RE
430 .PP
431 \-\-glob=<glob\-pattern>
432 .RS 4
433 Pretend as if all the refs matching shell glob
434 \fI<glob\-pattern>\fR
435 are listed on the command line as
436 \fI<commit>\fR\&. Leading
437 \fIrefs/\fR, is automatically prepended if missing\&. If pattern lacks
438 \fI?\fR,
439 \fI*\fR, or
440 \fI[\fR,
441 \fI/*\fR
442 at the end is implied\&.
443 .RE
444 .PP
445 \-\-exclude=<glob\-pattern>
446 .RS 4
447 Do not include refs matching
448 \fI<glob\-pattern>\fR
449 that the next
450 \fB\-\-all\fR,
451 \fB\-\-branches\fR,
452 \fB\-\-tags\fR,
453 \fB\-\-remotes\fR, or
454 \fB\-\-glob\fR
455 would otherwise consider\&. Repetitions of this option accumulate exclusion patterns up to the next
456 \fB\-\-all\fR,
457 \fB\-\-branches\fR,
458 \fB\-\-tags\fR,
459 \fB\-\-remotes\fR, or
460 \fB\-\-glob\fR
461 option (other options or arguments do not clear accumulated patterns)\&.
462 .sp
463 The patterns given should not begin with
464 \fBrefs/heads\fR,
465 \fBrefs/tags\fR, or
466 \fBrefs/remotes\fR
467 when applied to
468 \fB\-\-branches\fR,
469 \fB\-\-tags\fR, or
470 \fB\-\-remotes\fR, respectively, and they must begin with
471 \fBrefs/\fR
472 when applied to
473 \fB\-\-glob\fR
474 or
475 \fB\-\-all\fR\&. If a trailing
476 \fI/*\fR
477 is intended, it must be given explicitly\&.
478 .RE
479 .PP
480 \-\-exclude\-hidden=[fetch|receive|uploadpack]
481 .RS 4
482 Do not include refs that would be hidden by
483 \fBgit\-fetch\fR,
484 \fBgit\-receive\-pack\fR
485 or
486 \fBgit\-upload\-pack\fR
487 by consulting the appropriate
488 \fBfetch\&.hideRefs\fR,
489 \fBreceive\&.hideRefs\fR
490 or
491 \fBuploadpack\&.hideRefs\fR
492 configuration along with
493 \fBtransfer\&.hideRefs\fR
494 (see
495 \fBgit-config\fR(1))\&. This option affects the next pseudo\-ref option
496 \fB\-\-all\fR
497 or
498 \fB\-\-glob\fR
499 and is cleared after processing them\&.
500 .RE
501 .PP
502 \-\-reflog
503 .RS 4
504 Pretend as if all objects mentioned by reflogs are listed on the command line as
505 \fB<commit>\fR\&.
506 .RE
507 .PP
508 \-\-alternate\-refs
509 .RS 4
510 Pretend as if all objects mentioned as ref tips of alternate repositories were listed on the command line\&. An alternate repository is any repository whose object directory is specified in
511 \fBobjects/info/alternates\fR\&. The set of included objects may be modified by
512 \fBcore\&.alternateRefsCommand\fR, etc\&. See
513 \fBgit-config\fR(1)\&.
514 .RE
515 .PP
516 \-\-single\-worktree
517 .RS 4
518 By default, all working trees will be examined by the following options when there are more than one (see
519 \fBgit-worktree\fR(1)):
520 \fB\-\-all\fR,
521 \fB\-\-reflog\fR
522 and
523 \fB\-\-indexed\-objects\fR\&. This option forces them to examine the current working tree only\&.
524 .RE
525 .PP
526 \-\-ignore\-missing
527 .RS 4
528 Upon seeing an invalid object name in the input, pretend as if the bad input was not given\&.
529 .RE
530 .PP
531 \-\-bisect
532 .RS 4
533 Pretend as if the bad bisection ref
534 \fBrefs/bisect/bad\fR
535 was listed and as if it was followed by
536 \fB\-\-not\fR
537 and the good bisection refs
538 \fBrefs/bisect/good\-*\fR
539 on the command line\&.
540 .RE
541 .PP
542 \-\-stdin
543 .RS 4
544 In addition to getting arguments from the command line, read them from standard input as well\&. This accepts commits and pseudo\-options like
545 \fB\-\-all\fR
546 and
547 \fB\-\-glob=\fR\&. When a
548 \fB\-\-\fR
549 separator is seen, the following input is treated as paths and used to limit the result\&. Flags like
550 \fB\-\-not\fR
551 which are read via standard input are only respected for arguments passed in the same way and will not influence any subsequent command line arguments\&.
552 .RE
553 .PP
554 \-\-cherry\-mark
555 .RS 4
556 Like
557 \fB\-\-cherry\-pick\fR
558 (see below) but mark equivalent commits with
559 \fB=\fR
560 rather than omitting them, and inequivalent ones with
561 \fB+\fR\&.
562 .RE
563 .PP
564 \-\-cherry\-pick
565 .RS 4
566 Omit any commit that introduces the same change as another commit on the \(lqother side\(rq when the set of commits are limited with symmetric difference\&.
567 .sp
568 For example, if you have two branches,
569 \fBA\fR
570 and
571 \fBB\fR, a usual way to list all commits on only one side of them is with
572 \fB\-\-left\-right\fR
573 (see the example below in the description of the
574 \fB\-\-left\-right\fR
575 option)\&. However, it shows the commits that were cherry\-picked from the other branch (for example, \(lq3rd on b\(rq may be cherry\-picked from branch A)\&. With this option, such pairs of commits are excluded from the output\&.
576 .RE
577 .PP
578 \-\-left\-only, \-\-right\-only
579 .RS 4
580 List only commits on the respective side of a symmetric difference, i\&.e\&. only those which would be marked
581 \fB<\fR
582 resp\&.
583 \fB>\fR
584 by
585 \fB\-\-left\-right\fR\&.
586 .sp
587 For example,
588 \fB\-\-cherry\-pick \-\-right\-only A\&.\&.\&.B\fR
589 omits those commits from
590 \fBB\fR
591 which are in
592 \fBA\fR
593 or are patch\-equivalent to a commit in
594 \fBA\fR\&. In other words, this lists the
595 \fB+\fR
596 commits from
597 \fBgit cherry A B\fR\&. More precisely,
598 \fB\-\-cherry\-pick \-\-right\-only \-\-no\-merges\fR
599 gives the exact list\&.
600 .RE
601 .PP
602 \-\-cherry
603 .RS 4
604 A synonym for
605 \fB\-\-right\-only \-\-cherry\-mark \-\-no\-merges\fR; useful to limit the output to the commits on our side and mark those that have been applied to the other side of a forked history with
606 \fBgit log \-\-cherry upstream\&.\&.\&.mybranch\fR, similar to
607 \fBgit cherry upstream mybranch\fR\&.
608 .RE
609 .PP
610 \-g, \-\-walk\-reflogs
611 .RS 4
612 Instead of walking the commit ancestry chain, walk reflog entries from the most recent one to older ones\&. When this option is used you cannot specify commits to exclude (that is,
613 \fI^commit\fR,
614 \fIcommit1\&.\&.commit2\fR, and
615 \fIcommit1\&.\&.\&.commit2\fR
616 notations cannot be used)\&.
617 .sp
618 With
619 \fB\-\-pretty\fR
620 format other than
621 \fBoneline\fR
622 and
623 \fBreference\fR
624 (for obvious reasons), this causes the output to have two extra lines of information taken from the reflog\&. The reflog designator in the output may be shown as
625 \fBref@{Nth}\fR
626 (where
627 \fBNth\fR
628 is the reverse\-chronological index in the reflog) or as
629 \fBref@{timestamp}\fR
630 (with the timestamp for that entry), depending on a few rules:
631 .sp
632 .RS 4
633 .ie n \{\
634 \h'-04' 1.\h'+01'\c
635 .\}
636 .el \{\
637 .sp -1
638 .IP " 1." 4.2
639 .\}
640 If the starting point is specified as
641 \fBref@{Nth}\fR, show the index format\&.
642 .RE
643 .sp
644 .RS 4
645 .ie n \{\
646 \h'-04' 2.\h'+01'\c
647 .\}
648 .el \{\
649 .sp -1
650 .IP " 2." 4.2
651 .\}
652 If the starting point was specified as
653 \fBref@{now}\fR, show the timestamp format\&.
654 .RE
655 .sp
656 .RS 4
657 .ie n \{\
658 \h'-04' 3.\h'+01'\c
659 .\}
660 .el \{\
661 .sp -1
662 .IP " 3." 4.2
663 .\}
664 If neither was used, but
665 \fB\-\-date\fR
666 was given on the command line, show the timestamp in the format requested by
667 \fB\-\-date\fR\&.
668 .RE
669 .sp
670 .RS 4
671 .ie n \{\
672 \h'-04' 4.\h'+01'\c
673 .\}
674 .el \{\
675 .sp -1
676 .IP " 4." 4.2
677 .\}
678 Otherwise, show the index format\&.
679 .RE
680 .sp
681 Under
682 \fB\-\-pretty=oneline\fR, the commit message is prefixed with this information on the same line\&. This option cannot be combined with
683 \fB\-\-reverse\fR\&. See also
684 \fBgit-reflog\fR(1)\&.
685 .sp
686 Under
687 \fB\-\-pretty=reference\fR, this information will not be shown at all\&.
688 .RE
689 .PP
690 \-\-merge
691 .RS 4
692 After a failed merge, show refs that touch files having a conflict and don\(cqt exist on all heads to merge\&.
693 .RE
694 .PP
695 \-\-boundary
696 .RS 4
697 Output excluded boundary commits\&. Boundary commits are prefixed with
698 \fB\-\fR\&.
699 .RE
700 .SS "History Simplification"
701 .sp
702 Sometimes you are only interested in parts of the history, for example the commits modifying a particular <path>\&. But there are two parts of \fIHistory Simplification\fR, one part is selecting the commits and the other is how to do it, as there are various strategies to simplify the history\&.
703 .sp
704 The following options select the commits to be shown:
705 .PP
706 <paths>
707 .RS 4
708 Commits modifying the given <paths> are selected\&.
709 .RE
710 .PP
711 \-\-simplify\-by\-decoration
712 .RS 4
713 Commits that are referred by some branch or tag are selected\&.
714 .RE
715 .sp
716 Note that extra commits can be shown to give a meaningful history\&.
717 .sp
718 The following options affect the way the simplification is performed:
719 .PP
720 Default mode
721 .RS 4
722 Simplifies the history to the simplest history explaining the final state of the tree\&. Simplest because it prunes some side branches if the end result is the same (i\&.e\&. merging branches with the same content)
723 .RE
724 .PP
725 \-\-show\-pulls
726 .RS 4
727 Include all commits from the default mode, but also any merge commits that are not TREESAME to the first parent but are TREESAME to a later parent\&. This mode is helpful for showing the merge commits that "first introduced" a change to a branch\&.
728 .RE
729 .PP
730 \-\-full\-history
731 .RS 4
732 Same as the default mode, but does not prune some history\&.
733 .RE
734 .PP
735 \-\-dense
736 .RS 4
737 Only the selected commits are shown, plus some to have a meaningful history\&.
738 .RE
739 .PP
740 \-\-sparse
741 .RS 4
742 All commits in the simplified history are shown\&.
743 .RE
744 .PP
745 \-\-simplify\-merges
746 .RS 4
747 Additional option to
748 \fB\-\-full\-history\fR
749 to remove some needless merges from the resulting history, as there are no selected commits contributing to this merge\&.
750 .RE
751 .PP
752 \-\-ancestry\-path[=<commit>]
753 .RS 4
754 When given a range of commits to display (e\&.g\&.
755 \fIcommit1\&.\&.commit2\fR
756 or
757 \fIcommit2 ^commit1\fR), only display commits in that range that are ancestors of <commit>, descendants of <commit>, or <commit> itself\&. If no commit is specified, use
758 \fIcommit1\fR
759 (the excluded part of the range) as <commit>\&. Can be passed multiple times; if so, a commit is included if it is any of the commits given or if it is an ancestor or descendant of one of them\&.
760 .RE
761 .sp
762 A more detailed explanation follows\&.
763 .sp
764 Suppose you specified \fBfoo\fR as the <paths>\&. We shall call commits that modify \fBfoo\fR !TREESAME, and the rest TREESAME\&. (In a diff filtered for \fBfoo\fR, they look different and equal, respectively\&.)
765 .sp
766 In the following, we will always refer to the same example history to illustrate the differences between simplification settings\&. We assume that you are filtering for a file \fBfoo\fR in this commit graph:
767 .sp
768 .if n \{\
769 .RS 4
770 .\}
771 .nf
772 \&.\-A\-\-\-M\-\-\-N\-\-\-O\-\-\-P\-\-\-Q
773 / / / / / /
774 I B C D E Y
775 \e / / / / /
776 `\-\-\-\-\-\-\-\-\-\-\-\-\-\*(Aq X
777 .fi
778 .if n \{\
779 .RE
780 .\}
781 .sp
782 .sp
783 The horizontal line of history A\-\-\-Q is taken to be the first parent of each merge\&. The commits are:
784 .sp
785 .RS 4
786 .ie n \{\
787 \h'-04'\(bu\h'+03'\c
788 .\}
789 .el \{\
790 .sp -1
791 .IP \(bu 2.3
792 .\}
793 \fBI\fR
794 is the initial commit, in which
795 \fBfoo\fR
796 exists with contents \(lqasdf\(rq, and a file
797 \fBquux\fR
798 exists with contents \(lqquux\(rq\&. Initial commits are compared to an empty tree, so
799 \fBI\fR
800 is !TREESAME\&.
801 .RE
802 .sp
803 .RS 4
804 .ie n \{\
805 \h'-04'\(bu\h'+03'\c
806 .\}
807 .el \{\
808 .sp -1
809 .IP \(bu 2.3
810 .\}
811 In
812 \fBA\fR,
813 \fBfoo\fR
814 contains just \(lqfoo\(rq\&.
815 .RE
816 .sp
817 .RS 4
818 .ie n \{\
819 \h'-04'\(bu\h'+03'\c
820 .\}
821 .el \{\
822 .sp -1
823 .IP \(bu 2.3
824 .\}
825 \fBB\fR
826 contains the same change as
827 \fBA\fR\&. Its merge
828 \fBM\fR
829 is trivial and hence TREESAME to all parents\&.
830 .RE
831 .sp
832 .RS 4
833 .ie n \{\
834 \h'-04'\(bu\h'+03'\c
835 .\}
836 .el \{\
837 .sp -1
838 .IP \(bu 2.3
839 .\}
840 \fBC\fR
841 does not change
842 \fBfoo\fR, but its merge
843 \fBN\fR
844 changes it to \(lqfoobar\(rq, so it is not TREESAME to any parent\&.
845 .RE
846 .sp
847 .RS 4
848 .ie n \{\
849 \h'-04'\(bu\h'+03'\c
850 .\}
851 .el \{\
852 .sp -1
853 .IP \(bu 2.3
854 .\}
855 \fBD\fR
856 sets
857 \fBfoo\fR
858 to \(lqbaz\(rq\&. Its merge
859 \fBO\fR
860 combines the strings from
861 \fBN\fR
862 and
863 \fBD\fR
864 to \(lqfoobarbaz\(rq; i\&.e\&., it is not TREESAME to any parent\&.
865 .RE
866 .sp
867 .RS 4
868 .ie n \{\
869 \h'-04'\(bu\h'+03'\c
870 .\}
871 .el \{\
872 .sp -1
873 .IP \(bu 2.3
874 .\}
875 \fBE\fR
876 changes
877 \fBquux\fR
878 to \(lqxyzzy\(rq, and its merge
879 \fBP\fR
880 combines the strings to \(lqquux xyzzy\(rq\&.
881 \fBP\fR
882 is TREESAME to
883 \fBO\fR, but not to
884 \fBE\fR\&.
885 .RE
886 .sp
887 .RS 4
888 .ie n \{\
889 \h'-04'\(bu\h'+03'\c
890 .\}
891 .el \{\
892 .sp -1
893 .IP \(bu 2.3
894 .\}
895 \fBX\fR
896 is an independent root commit that added a new file
897 \fBside\fR, and
898 \fBY\fR
899 modified it\&.
900 \fBY\fR
901 is TREESAME to
902 \fBX\fR\&. Its merge
903 \fBQ\fR
904 added
905 \fBside\fR
906 to
907 \fBP\fR, and
908 \fBQ\fR
909 is TREESAME to
910 \fBP\fR, but not to
911 \fBY\fR\&.
912 .RE
913 .sp
914 \fBrev\-list\fR walks backwards through history, including or excluding commits based on whether \fB\-\-full\-history\fR and/or parent rewriting (via \fB\-\-parents\fR or \fB\-\-children\fR) are used\&. The following settings are available\&.
915 .PP
916 Default mode
917 .RS 4
918 Commits are included if they are not TREESAME to any parent (though this can be changed, see
919 \fB\-\-sparse\fR
920 below)\&. If the commit was a merge, and it was TREESAME to one parent, follow only that parent\&. (Even if there are several TREESAME parents, follow only one of them\&.) Otherwise, follow all parents\&.
921 .sp
922 This results in:
923 .sp
924 .if n \{\
925 .RS 4
926 .\}
927 .nf
928 \&.\-A\-\-\-N\-\-\-O
929 / / /
930 I\-\-\-\-\-\-\-\-\-D
931 .fi
932 .if n \{\
933 .RE
934 .\}
935 .sp
936 Note how the rule to only follow the TREESAME parent, if one is available, removed
937 \fBB\fR
938 from consideration entirely\&.
939 \fBC\fR
940 was considered via
941 \fBN\fR, but is TREESAME\&. Root commits are compared to an empty tree, so
942 \fBI\fR
943 is !TREESAME\&.
944 .sp
945 Parent/child relations are only visible with
946 \fB\-\-parents\fR, but that does not affect the commits selected in default mode, so we have shown the parent lines\&.
947 .RE
948 .PP
949 \-\-full\-history without parent rewriting
950 .RS 4
951 This mode differs from the default in one point: always follow all parents of a merge, even if it is TREESAME to one of them\&. Even if more than one side of the merge has commits that are included, this does not imply that the merge itself is! In the example, we get
952 .sp
953 .if n \{\
954 .RS 4
955 .\}
956 .nf
957 I A B N D O P Q
958 .fi
959 .if n \{\
960 .RE
961 .\}
962 .sp
963 \fBM\fR
964 was excluded because it is TREESAME to both parents\&.
965 \fBE\fR,
966 \fBC\fR
967 and
968 \fBB\fR
969 were all walked, but only
970 \fBB\fR
971 was !TREESAME, so the others do not appear\&.
972 .sp
973 Note that without parent rewriting, it is not really possible to talk about the parent/child relationships between the commits, so we show them disconnected\&.
974 .RE
975 .PP
976 \-\-full\-history with parent rewriting
977 .RS 4
978 Ordinary commits are only included if they are !TREESAME (though this can be changed, see
979 \fB\-\-sparse\fR
980 below)\&.
981 .sp
982 Merges are always included\&. However, their parent list is rewritten: Along each parent, prune away commits that are not included themselves\&. This results in
983 .sp
984 .if n \{\
985 .RS 4
986 .\}
987 .nf
988 \&.\-A\-\-\-M\-\-\-N\-\-\-O\-\-\-P\-\-\-Q
989 / / / / /
990 I B / D /
991 \e / / / /
992 `\-\-\-\-\-\-\-\-\-\-\-\-\-\*(Aq
993 .fi
994 .if n \{\
995 .RE
996 .\}
997 .sp
998 Compare to
999 \fB\-\-full\-history\fR
1000 without rewriting above\&. Note that
1001 \fBE\fR
1002 was pruned away because it is TREESAME, but the parent list of P was rewritten to contain
1003 \fBE\fR\*(Aqs parent
1004 \fBI\fR\&. The same happened for
1005 \fBC\fR
1006 and
1007 \fBN\fR, and
1008 \fBX\fR,
1009 \fBY\fR
1010 and
1011 \fBQ\fR\&.
1012 .RE
1013 .sp
1014 In addition to the above settings, you can change whether TREESAME affects inclusion:
1015 .PP
1016 \-\-dense
1017 .RS 4
1018 Commits that are walked are included if they are not TREESAME to any parent\&.
1019 .RE
1020 .PP
1021 \-\-sparse
1022 .RS 4
1023 All commits that are walked are included\&.
1024 .sp
1025 Note that without
1026 \fB\-\-full\-history\fR, this still simplifies merges: if one of the parents is TREESAME, we follow only that one, so the other sides of the merge are never walked\&.
1027 .RE
1028 .PP
1029 \-\-simplify\-merges
1030 .RS 4
1031 First, build a history graph in the same way that
1032 \fB\-\-full\-history\fR
1033 with parent rewriting does (see above)\&.
1034 .sp
1035 Then simplify each commit
1036 \fBC\fR
1037 to its replacement
1038 \fBC\*(Aq\fR
1039 in the final history according to the following rules:
1040 .sp
1041 .RS 4
1042 .ie n \{\
1043 \h'-04'\(bu\h'+03'\c
1044 .\}
1045 .el \{\
1046 .sp -1
1047 .IP \(bu 2.3
1048 .\}
1049 Set
1050 \fBC\*(Aq\fR
1051 to
1052 \fBC\fR\&.
1053 .RE
1054 .sp
1055 .RS 4
1056 .ie n \{\
1057 \h'-04'\(bu\h'+03'\c
1058 .\}
1059 .el \{\
1060 .sp -1
1061 .IP \(bu 2.3
1062 .\}
1063 Replace each parent
1064 \fBP\fR
1065 of
1066 \fBC\*(Aq\fR
1067 with its simplification
1068 \fBP\*(Aq\fR\&. In the process, drop parents that are ancestors of other parents or that are root commits TREESAME to an empty tree, and remove duplicates, but take care to never drop all parents that we are TREESAME to\&.
1069 .RE
1070 .sp
1071 .RS 4
1072 .ie n \{\
1073 \h'-04'\(bu\h'+03'\c
1074 .\}
1075 .el \{\
1076 .sp -1
1077 .IP \(bu 2.3
1078 .\}
1079 If after this parent rewriting,
1080 \fBC\*(Aq\fR
1081 is a root or merge commit (has zero or >1 parents), a boundary commit, or !TREESAME, it remains\&. Otherwise, it is replaced with its only parent\&.
1082 .RE
1083 .sp
1084 The effect of this is best shown by way of comparing to
1085 \fB\-\-full\-history\fR
1086 with parent rewriting\&. The example turns into:
1087 .sp
1088 .if n \{\
1089 .RS 4
1090 .\}
1091 .nf
1092 \&.\-A\-\-\-M\-\-\-N\-\-\-O
1093 / / /
1094 I B D
1095 \e / /
1096 `\-\-\-\-\-\-\-\-\-\*(Aq
1097 .fi
1098 .if n \{\
1099 .RE
1100 .\}
1101 .sp
1102 Note the major differences in
1103 \fBN\fR,
1104 \fBP\fR, and
1105 \fBQ\fR
1106 over
1107 \fB\-\-full\-history\fR:
1108 .sp
1109 .RS 4
1110 .ie n \{\
1111 \h'-04'\(bu\h'+03'\c
1112 .\}
1113 .el \{\
1114 .sp -1
1115 .IP \(bu 2.3
1116 .\}
1117 \fBN\fR\*(Aqs parent list had
1118 \fBI\fR
1119 removed, because it is an ancestor of the other parent
1120 \fBM\fR\&. Still,
1121 \fBN\fR
1122 remained because it is !TREESAME\&.
1123 .RE
1124 .sp
1125 .RS 4
1126 .ie n \{\
1127 \h'-04'\(bu\h'+03'\c
1128 .\}
1129 .el \{\
1130 .sp -1
1131 .IP \(bu 2.3
1132 .\}
1133 \fBP\fR\*(Aqs parent list similarly had
1134 \fBI\fR
1135 removed\&.
1136 \fBP\fR
1137 was then removed completely, because it had one parent and is TREESAME\&.
1138 .RE
1139 .sp
1140 .RS 4
1141 .ie n \{\
1142 \h'-04'\(bu\h'+03'\c
1143 .\}
1144 .el \{\
1145 .sp -1
1146 .IP \(bu 2.3
1147 .\}
1148 \fBQ\fR\*(Aqs parent list had
1149 \fBY\fR
1150 simplified to
1151 \fBX\fR\&.
1152 \fBX\fR
1153 was then removed, because it was a TREESAME root\&.
1154 \fBQ\fR
1155 was then removed completely, because it had one parent and is TREESAME\&.
1156 .RE
1157 .RE
1158 .sp
1159 There is another simplification mode available:
1160 .PP
1161 \-\-ancestry\-path[=<commit>]
1162 .RS 4
1163 Limit the displayed commits to those which are an ancestor of <commit>, or which are a descendant of <commit>, or are <commit> itself\&.
1164 .sp
1165 As an example use case, consider the following commit history:
1166 .sp
1167 .if n \{\
1168 .RS 4
1169 .\}
1170 .nf
1171 D\-\-\-E\-\-\-\-\-\-\-F
1172 / \e \e
1173 B\-\-\-C\-\-\-G\-\-\-H\-\-\-I\-\-\-J
1174 / \e
1175 A\-\-\-\-\-\-\-K\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-L\-\-M
1176 .fi
1177 .if n \{\
1178 .RE
1179 .\}
1180 .sp
1181 A regular
1182 \fID\&.\&.M\fR
1183 computes the set of commits that are ancestors of
1184 \fBM\fR, but excludes the ones that are ancestors of
1185 \fBD\fR\&. This is useful to see what happened to the history leading to
1186 \fBM\fR
1187 since
1188 \fBD\fR, in the sense that \(lqwhat does
1189 \fBM\fR
1190 have that did not exist in
1191 \fBD\fR\(rq\&. The result in this example would be all the commits, except
1192 \fBA\fR
1193 and
1194 \fBB\fR
1195 (and
1196 \fBD\fR
1197 itself, of course)\&.
1198 .sp
1199 When we want to find out what commits in
1200 \fBM\fR
1201 are contaminated with the bug introduced by
1202 \fBD\fR
1203 and need fixing, however, we might want to view only the subset of
1204 \fID\&.\&.M\fR
1205 that are actually descendants of
1206 \fBD\fR, i\&.e\&. excluding
1207 \fBC\fR
1208 and
1209 \fBK\fR\&. This is exactly what the
1210 \fB\-\-ancestry\-path\fR
1211 option does\&. Applied to the
1212 \fID\&.\&.M\fR
1213 range, it results in:
1214 .sp
1215 .if n \{\
1216 .RS 4
1217 .\}
1218 .nf
1219 E\-\-\-\-\-\-\-F
1220 \e \e
1221 G\-\-\-H\-\-\-I\-\-\-J
1222 \e
1223 L\-\-M
1224 .fi
1225 .if n \{\
1226 .RE
1227 .\}
1228 .sp
1229 We can also use
1230 \fB\-\-ancestry\-path=D\fR
1231 instead of
1232 \fB\-\-ancestry\-path\fR
1233 which means the same thing when applied to the
1234 \fID\&.\&.M\fR
1235 range but is just more explicit\&.
1236 .sp
1237 If we instead are interested in a given topic within this range, and all commits affected by that topic, we may only want to view the subset of
1238 \fBD\&.\&.M\fR
1239 which contain that topic in their ancestry path\&. So, using
1240 \fB\-\-ancestry\-path=H D\&.\&.M\fR
1241 for example would result in:
1242 .sp
1243 .if n \{\
1244 .RS 4
1245 .\}
1246 .nf
1247 E
1248 \e
1249 G\-\-\-H\-\-\-I\-\-\-J
1250 \e
1251 L\-\-M
1252 .fi
1253 .if n \{\
1254 .RE
1255 .\}
1256 .sp
1257 Whereas
1258 \fB\-\-ancestry\-path=K D\&.\&.M\fR
1259 would result in
1260 .sp
1261 .if n \{\
1262 .RS 4
1263 .\}
1264 .nf
1265 K\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-L\-\-M
1266 .fi
1267 .if n \{\
1268 .RE
1269 .\}
1270 .sp
1271 .RE
1272 .sp
1273 Before discussing another option, \fB\-\-show\-pulls\fR, we need to create a new example history\&.
1274 .sp
1275 A common problem users face when looking at simplified history is that a commit they know changed a file somehow does not appear in the file\(cqs simplified history\&. Let\(cqs demonstrate a new example and show how options such as \fB\-\-full\-history\fR and \fB\-\-simplify\-merges\fR works in that case:
1276 .sp
1277 .if n \{\
1278 .RS 4
1279 .\}
1280 .nf
1281 \&.\-A\-\-\-M\-\-\-\-\-C\-\-N\-\-\-O\-\-\-P
1282 / / \e \e \e/ / /
1283 I B \e R\-\*(Aq`\-Z\*(Aq /
1284 \e / \e/ /
1285 \e / /\e /
1286 `\-\-\-X\-\-\*(Aq `\-\-\-Y\-\-\*(Aq
1287 .fi
1288 .if n \{\
1289 .RE
1290 .\}
1291 .sp
1292 .sp
1293 For this example, suppose \fBI\fR created \fBfile\&.txt\fR which was modified by \fBA\fR, \fBB\fR, and \fBX\fR in different ways\&. The single\-parent commits \fBC\fR, \fBZ\fR, and \fBY\fR do not change \fBfile\&.txt\fR\&. The merge commit \fBM\fR was created by resolving the merge conflict to include both changes from \fBA\fR and \fBB\fR and hence is not TREESAME to either\&. The merge commit \fBR\fR, however, was created by ignoring the contents of \fBfile\&.txt\fR at \fBM\fR and taking only the contents of \fBfile\&.txt\fR at \fBX\fR\&. Hence, \fBR\fR is TREESAME to \fBX\fR but not \fBM\fR\&. Finally, the natural merge resolution to create \fBN\fR is to take the contents of \fBfile\&.txt\fR at \fBR\fR, so \fBN\fR is TREESAME to \fBR\fR but not \fBC\fR\&. The merge commits \fBO\fR and \fBP\fR are TREESAME to their first parents, but not to their second parents, \fBZ\fR and \fBY\fR respectively\&.
1294 .sp
1295 When using the default mode, \fBN\fR and \fBR\fR both have a TREESAME parent, so those edges are walked and the others are ignored\&. The resulting history graph is:
1296 .sp
1297 .if n \{\
1298 .RS 4
1299 .\}
1300 .nf
1301 I\-\-\-X
1302 .fi
1303 .if n \{\
1304 .RE
1305 .\}
1306 .sp
1307 .sp
1308 When using \fB\-\-full\-history\fR, Git walks every edge\&. This will discover the commits \fBA\fR and \fBB\fR and the merge \fBM\fR, but also will reveal the merge commits \fBO\fR and \fBP\fR\&. With parent rewriting, the resulting graph is:
1309 .sp
1310 .if n \{\
1311 .RS 4
1312 .\}
1313 .nf
1314 \&.\-A\-\-\-M\-\-\-\-\-\-\-\-N\-\-\-O\-\-\-P
1315 / / \e \e \e/ / /
1316 I B \e R\-\*(Aq`\-\-\*(Aq /
1317 \e / \e/ /
1318 \e / /\e /
1319 `\-\-\-X\-\-\*(Aq `\-\-\-\-\-\-\*(Aq
1320 .fi
1321 .if n \{\
1322 .RE
1323 .\}
1324 .sp
1325 .sp
1326 Here, the merge commits \fBO\fR and \fBP\fR contribute extra noise, as they did not actually contribute a change to \fBfile\&.txt\fR\&. They only merged a topic that was based on an older version of \fBfile\&.txt\fR\&. This is a common issue in repositories using a workflow where many contributors work in parallel and merge their topic branches along a single trunk: many unrelated merges appear in the \fB\-\-full\-history\fR results\&.
1327 .sp
1328 When using the \fB\-\-simplify\-merges\fR option, the commits \fBO\fR and \fBP\fR disappear from the results\&. This is because the rewritten second parents of \fBO\fR and \fBP\fR are reachable from their first parents\&. Those edges are removed and then the commits look like single\-parent commits that are TREESAME to their parent\&. This also happens to the commit \fBN\fR, resulting in a history view as follows:
1329 .sp
1330 .if n \{\
1331 .RS 4
1332 .\}
1333 .nf
1334 \&.\-A\-\-\-M\-\-\&.
1335 / / \e
1336 I B R
1337 \e / /
1338 \e / /
1339 `\-\-\-X\-\-\*(Aq
1340 .fi
1341 .if n \{\
1342 .RE
1343 .\}
1344 .sp
1345 .sp
1346 In this view, we see all of the important single\-parent changes from \fBA\fR, \fBB\fR, and \fBX\fR\&. We also see the carefully\-resolved merge \fBM\fR and the not\-so\-carefully\-resolved merge \fBR\fR\&. This is usually enough information to determine why the commits \fBA\fR and \fBB\fR "disappeared" from history in the default view\&. However, there are a few issues with this approach\&.
1347 .sp
1348 The first issue is performance\&. Unlike any previous option, the \fB\-\-simplify\-merges\fR option requires walking the entire commit history before returning a single result\&. This can make the option difficult to use for very large repositories\&.
1349 .sp
1350 The second issue is one of auditing\&. When many contributors are working on the same repository, it is important which merge commits introduced a change into an important branch\&. The problematic merge \fBR\fR above is not likely to be the merge commit that was used to merge into an important branch\&. Instead, the merge \fBN\fR was used to merge \fBR\fR and \fBX\fR into the important branch\&. This commit may have information about why the change \fBX\fR came to override the changes from \fBA\fR and \fBB\fR in its commit message\&.
1351 .PP
1352 \-\-show\-pulls
1353 .RS 4
1354 In addition to the commits shown in the default history, show each merge commit that is not TREESAME to its first parent but is TREESAME to a later parent\&.
1355 .sp
1356 When a merge commit is included by
1357 \fB\-\-show\-pulls\fR, the merge is treated as if it "pulled" the change from another branch\&. When using
1358 \fB\-\-show\-pulls\fR
1359 on this example (and no other options) the resulting graph is:
1360 .sp
1361 .if n \{\
1362 .RS 4
1363 .\}
1364 .nf
1365 I\-\-\-X\-\-\-R\-\-\-N
1366 .fi
1367 .if n \{\
1368 .RE
1369 .\}
1370 .sp
1371 Here, the merge commits
1372 \fBR\fR
1373 and
1374 \fBN\fR
1375 are included because they pulled the commits
1376 \fBX\fR
1377 and
1378 \fBR\fR
1379 into the base branch, respectively\&. These merges are the reason the commits
1380 \fBA\fR
1381 and
1382 \fBB\fR
1383 do not appear in the default history\&.
1384 .sp
1385 When
1386 \fB\-\-show\-pulls\fR
1387 is paired with
1388 \fB\-\-simplify\-merges\fR, the graph includes all of the necessary information:
1389 .sp
1390 .if n \{\
1391 .RS 4
1392 .\}
1393 .nf
1394 \&.\-A\-\-\-M\-\-\&. N
1395 / / \e /
1396 I B R
1397 \e / /
1398 \e / /
1399 `\-\-\-X\-\-\*(Aq
1400 .fi
1401 .if n \{\
1402 .RE
1403 .\}
1404 .sp
1405 Notice that since
1406 \fBM\fR
1407 is reachable from
1408 \fBR\fR, the edge from
1409 \fBN\fR
1410 to
1411 \fBM\fR
1412 was simplified away\&. However,
1413 \fBN\fR
1414 still appears in the history as an important commit because it "pulled" the change
1415 \fBR\fR
1416 into the main branch\&.
1417 .RE
1418 .sp
1419 The \fB\-\-simplify\-by\-decoration\fR option allows you to view only the big picture of the topology of the history, by omitting commits that are not referenced by tags\&. Commits are marked as !TREESAME (in other words, kept after history simplification rules described above) if (1) they are referenced by tags, or (2) they change the contents of the paths given on the command line\&. All other commits are marked as TREESAME (subject to be simplified away)\&.
1420 .SH "MAPPING AUTHORS"
1421 .sp
1422 See \fBgitmailmap\fR(5)\&.
1423 .sp
1424 Note that if \fBgit shortlog\fR is run outside of a repository (to process log contents on standard input), it will look for a \fB\&.mailmap\fR file in the current directory\&.
1425 .SH "GIT"
1426 .sp
1427 Part of the \fBgit\fR(1) suite