| blob | 6b0be56af3f8656ddf981cebd32010878a8006df |
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-07-16
6 .\" Manual: Git Manual
7 .\" Source: Git 2.46.0.rc0.75.g04f5a52757
8 .\" Language: English
9 .\"
10 .TH "GIT\-SHORTLOG" "1" "2024\-07\-16" "Git 2\&.46\&.0\&.rc0\&.75\&.g0" "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 \fI<Nth>\fR
628 is the reverse\-chronological index in the reflog) or as
629 \fBref@{<timestamp>}\fR
630 (with the
631 \fI<timestamp>\fR
632 for that entry), depending on a few rules:
633 .sp
634 .RS 4
635 .ie n \{\
636 \h'-04' 1.\h'+01'\c
637 .\}
638 .el \{\
639 .sp -1
640 .IP " 1." 4.2
641 .\}
642 If the starting point is specified as
643 \fBref@{<Nth>}\fR, show the index format\&.
644 .RE
645 .sp
646 .RS 4
647 .ie n \{\
648 \h'-04' 2.\h'+01'\c
649 .\}
650 .el \{\
651 .sp -1
652 .IP " 2." 4.2
653 .\}
654 If the starting point was specified as
655 \fBref@{now}\fR, show the timestamp format\&.
656 .RE
657 .sp
658 .RS 4
659 .ie n \{\
660 \h'-04' 3.\h'+01'\c
661 .\}
662 .el \{\
663 .sp -1
664 .IP " 3." 4.2
665 .\}
666 If neither was used, but
667 \fB\-\-date\fR
668 was given on the command line, show the timestamp in the format requested by
669 \fB\-\-date\fR\&.
670 .RE
671 .sp
672 .RS 4
673 .ie n \{\
674 \h'-04' 4.\h'+01'\c
675 .\}
676 .el \{\
677 .sp -1
678 .IP " 4." 4.2
679 .\}
680 Otherwise, show the index format\&.
681 .RE
682 .sp
683 Under
684 \fB\-\-pretty=oneline\fR, the commit message is prefixed with this information on the same line\&. This option cannot be combined with
685 \fB\-\-reverse\fR\&. See also
686 \fBgit-reflog\fR(1)\&.
687 .sp
688 Under
689 \fB\-\-pretty=reference\fR, this information will not be shown at all\&.
690 .RE
691 .PP
692 \-\-merge
693 .RS 4
694 Show commits touching conflicted paths in the range
695 \fBHEAD\&.\&.\&.<other>\fR, where
696 \fB<other>\fR
697 is the first existing pseudoref in
698 \fBMERGE_HEAD\fR,
699 \fBCHERRY_PICK_HEAD\fR,
700 \fBREVERT_HEAD\fR
701 or
702 \fBREBASE_HEAD\fR\&. Only works when the index has unmerged entries\&. This option can be used to show relevant commits when resolving conflicts from a 3\-way merge\&.
703 .RE
704 .PP
705 \-\-boundary
706 .RS 4
707 Output excluded boundary commits\&. Boundary commits are prefixed with
708 \fB\-\fR\&.
709 .RE
710 .SS "History Simplification"
711 .sp
712 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\&.
713 .sp
714 The following options select the commits to be shown:
715 .PP
716 <paths>
717 .RS 4
718 Commits modifying the given <paths> are selected\&.
719 .RE
720 .PP
721 \-\-simplify\-by\-decoration
722 .RS 4
723 Commits that are referred by some branch or tag are selected\&.
724 .RE
725 .sp
726 Note that extra commits can be shown to give a meaningful history\&.
727 .sp
728 The following options affect the way the simplification is performed:
729 .PP
730 Default mode
731 .RS 4
732 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)
733 .RE
734 .PP
735 \-\-show\-pulls
736 .RS 4
737 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\&.
738 .RE
739 .PP
740 \-\-full\-history
741 .RS 4
742 Same as the default mode, but does not prune some history\&.
743 .RE
744 .PP
745 \-\-dense
746 .RS 4
747 Only the selected commits are shown, plus some to have a meaningful history\&.
748 .RE
749 .PP
750 \-\-sparse
751 .RS 4
752 All commits in the simplified history are shown\&.
753 .RE
754 .PP
755 \-\-simplify\-merges
756 .RS 4
757 Additional option to
758 \fB\-\-full\-history\fR
759 to remove some needless merges from the resulting history, as there are no selected commits contributing to this merge\&.
760 .RE
761 .PP
762 \-\-ancestry\-path[=<commit>]
763 .RS 4
764 When given a range of commits to display (e\&.g\&.
765 \fIcommit1\&.\&.commit2\fR
766 or
767 \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
768 \fIcommit1\fR
769 (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\&.
770 .RE
771 .sp
772 A more detailed explanation follows\&.
773 .sp
774 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\&.)
775 .sp
776 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:
777 .sp
778 .if n \{\
779 .RS 4
780 .\}
781 .nf
782 \&.\-A\-\-\-M\-\-\-N\-\-\-O\-\-\-P\-\-\-Q
783 / / / / / /
784 I B C D E Y
785 \e / / / / /
786 `\-\-\-\-\-\-\-\-\-\-\-\-\-\*(Aq X
787 .fi
788 .if n \{\
789 .RE
790 .\}
791 .sp
792 .sp
793 The horizontal line of history A\-\-\-Q is taken to be the first parent of each merge\&. The commits are:
794 .sp
795 .RS 4
796 .ie n \{\
797 \h'-04'\(bu\h'+03'\c
798 .\}
799 .el \{\
800 .sp -1
801 .IP \(bu 2.3
802 .\}
803 \fBI\fR
804 is the initial commit, in which
805 \fBfoo\fR
806 exists with contents \(lqasdf\(rq, and a file
807 \fBquux\fR
808 exists with contents \(lqquux\(rq\&. Initial commits are compared to an empty tree, so
809 \fBI\fR
810 is !TREESAME\&.
811 .RE
812 .sp
813 .RS 4
814 .ie n \{\
815 \h'-04'\(bu\h'+03'\c
816 .\}
817 .el \{\
818 .sp -1
819 .IP \(bu 2.3
820 .\}
821 In
822 \fBA\fR,
823 \fBfoo\fR
824 contains just \(lqfoo\(rq\&.
825 .RE
826 .sp
827 .RS 4
828 .ie n \{\
829 \h'-04'\(bu\h'+03'\c
830 .\}
831 .el \{\
832 .sp -1
833 .IP \(bu 2.3
834 .\}
835 \fBB\fR
836 contains the same change as
837 \fBA\fR\&. Its merge
838 \fBM\fR
839 is trivial and hence TREESAME to all parents\&.
840 .RE
841 .sp
842 .RS 4
843 .ie n \{\
844 \h'-04'\(bu\h'+03'\c
845 .\}
846 .el \{\
847 .sp -1
848 .IP \(bu 2.3
849 .\}
850 \fBC\fR
851 does not change
852 \fBfoo\fR, but its merge
853 \fBN\fR
854 changes it to \(lqfoobar\(rq, so it is not TREESAME to any parent\&.
855 .RE
856 .sp
857 .RS 4
858 .ie n \{\
859 \h'-04'\(bu\h'+03'\c
860 .\}
861 .el \{\
862 .sp -1
863 .IP \(bu 2.3
864 .\}
865 \fBD\fR
866 sets
867 \fBfoo\fR
868 to \(lqbaz\(rq\&. Its merge
869 \fBO\fR
870 combines the strings from
871 \fBN\fR
872 and
873 \fBD\fR
874 to \(lqfoobarbaz\(rq; i\&.e\&., it is not TREESAME to any parent\&.
875 .RE
876 .sp
877 .RS 4
878 .ie n \{\
879 \h'-04'\(bu\h'+03'\c
880 .\}
881 .el \{\
882 .sp -1
883 .IP \(bu 2.3
884 .\}
885 \fBE\fR
886 changes
887 \fBquux\fR
888 to \(lqxyzzy\(rq, and its merge
889 \fBP\fR
890 combines the strings to \(lqquux xyzzy\(rq\&.
891 \fBP\fR
892 is TREESAME to
893 \fBO\fR, but not to
894 \fBE\fR\&.
895 .RE
896 .sp
897 .RS 4
898 .ie n \{\
899 \h'-04'\(bu\h'+03'\c
900 .\}
901 .el \{\
902 .sp -1
903 .IP \(bu 2.3
904 .\}
905 \fBX\fR
906 is an independent root commit that added a new file
907 \fBside\fR, and
908 \fBY\fR
909 modified it\&.
910 \fBY\fR
911 is TREESAME to
912 \fBX\fR\&. Its merge
913 \fBQ\fR
914 added
915 \fBside\fR
916 to
917 \fBP\fR, and
918 \fBQ\fR
919 is TREESAME to
920 \fBP\fR, but not to
921 \fBY\fR\&.
922 .RE
923 .sp
924 \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\&.
925 .PP
926 Default mode
927 .RS 4
928 Commits are included if they are not TREESAME to any parent (though this can be changed, see
929 \fB\-\-sparse\fR
930 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\&.
931 .sp
932 This results in:
933 .sp
934 .if n \{\
935 .RS 4
936 .\}
937 .nf
938 \&.\-A\-\-\-N\-\-\-O
939 / / /
940 I\-\-\-\-\-\-\-\-\-D
941 .fi
942 .if n \{\
943 .RE
944 .\}
945 .sp
946 Note how the rule to only follow the TREESAME parent, if one is available, removed
947 \fBB\fR
948 from consideration entirely\&.
949 \fBC\fR
950 was considered via
951 \fBN\fR, but is TREESAME\&. Root commits are compared to an empty tree, so
952 \fBI\fR
953 is !TREESAME\&.
954 .sp
955 Parent/child relations are only visible with
956 \fB\-\-parents\fR, but that does not affect the commits selected in default mode, so we have shown the parent lines\&.
957 .RE
958 .PP
959 \-\-full\-history without parent rewriting
960 .RS 4
961 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
962 .sp
963 .if n \{\
964 .RS 4
965 .\}
966 .nf
967 I A B N D O P Q
968 .fi
969 .if n \{\
970 .RE
971 .\}
972 .sp
973 \fBM\fR
974 was excluded because it is TREESAME to both parents\&.
975 \fBE\fR,
976 \fBC\fR
977 and
978 \fBB\fR
979 were all walked, but only
980 \fBB\fR
981 was !TREESAME, so the others do not appear\&.
982 .sp
983 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\&.
984 .RE
985 .PP
986 \-\-full\-history with parent rewriting
987 .RS 4
988 Ordinary commits are only included if they are !TREESAME (though this can be changed, see
989 \fB\-\-sparse\fR
990 below)\&.
991 .sp
992 Merges are always included\&. However, their parent list is rewritten: Along each parent, prune away commits that are not included themselves\&. This results in
993 .sp
994 .if n \{\
995 .RS 4
996 .\}
997 .nf
998 \&.\-A\-\-\-M\-\-\-N\-\-\-O\-\-\-P\-\-\-Q
999 / / / / /
1000 I B / D /
1001 \e / / / /
1002 `\-\-\-\-\-\-\-\-\-\-\-\-\-\*(Aq
1003 .fi
1004 .if n \{\
1005 .RE
1006 .\}
1007 .sp
1008 Compare to
1009 \fB\-\-full\-history\fR
1010 without rewriting above\&. Note that
1011 \fBE\fR
1012 was pruned away because it is TREESAME, but the parent list of P was rewritten to contain
1013 \fBE\fR\*(Aqs parent
1014 \fBI\fR\&. The same happened for
1015 \fBC\fR
1016 and
1017 \fBN\fR, and
1018 \fBX\fR,
1019 \fBY\fR
1020 and
1021 \fBQ\fR\&.
1022 .RE
1023 .sp
1024 In addition to the above settings, you can change whether TREESAME affects inclusion:
1025 .PP
1026 \-\-dense
1027 .RS 4
1028 Commits that are walked are included if they are not TREESAME to any parent\&.
1029 .RE
1030 .PP
1031 \-\-sparse
1032 .RS 4
1033 All commits that are walked are included\&.
1034 .sp
1035 Note that without
1036 \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\&.
1037 .RE
1038 .PP
1039 \-\-simplify\-merges
1040 .RS 4
1041 First, build a history graph in the same way that
1042 \fB\-\-full\-history\fR
1043 with parent rewriting does (see above)\&.
1044 .sp
1045 Then simplify each commit
1046 \fBC\fR
1047 to its replacement
1048 \fBC\*(Aq\fR
1049 in the final history according to the following rules:
1050 .sp
1051 .RS 4
1052 .ie n \{\
1053 \h'-04'\(bu\h'+03'\c
1054 .\}
1055 .el \{\
1056 .sp -1
1057 .IP \(bu 2.3
1058 .\}
1059 Set
1060 \fBC\*(Aq\fR
1061 to
1062 \fBC\fR\&.
1063 .RE
1064 .sp
1065 .RS 4
1066 .ie n \{\
1067 \h'-04'\(bu\h'+03'\c
1068 .\}
1069 .el \{\
1070 .sp -1
1071 .IP \(bu 2.3
1072 .\}
1073 Replace each parent
1074 \fBP\fR
1075 of
1076 \fBC\*(Aq\fR
1077 with its simplification
1078 \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\&.
1079 .RE
1080 .sp
1081 .RS 4
1082 .ie n \{\
1083 \h'-04'\(bu\h'+03'\c
1084 .\}
1085 .el \{\
1086 .sp -1
1087 .IP \(bu 2.3
1088 .\}
1089 If after this parent rewriting,
1090 \fBC\*(Aq\fR
1091 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\&.
1092 .RE
1093 .sp
1094 The effect of this is best shown by way of comparing to
1095 \fB\-\-full\-history\fR
1096 with parent rewriting\&. The example turns into:
1097 .sp
1098 .if n \{\
1099 .RS 4
1100 .\}
1101 .nf
1102 \&.\-A\-\-\-M\-\-\-N\-\-\-O
1103 / / /
1104 I B D
1105 \e / /
1106 `\-\-\-\-\-\-\-\-\-\*(Aq
1107 .fi
1108 .if n \{\
1109 .RE
1110 .\}
1111 .sp
1112 Note the major differences in
1113 \fBN\fR,
1114 \fBP\fR, and
1115 \fBQ\fR
1116 over
1117 \fB\-\-full\-history\fR:
1118 .sp
1119 .RS 4
1120 .ie n \{\
1121 \h'-04'\(bu\h'+03'\c
1122 .\}
1123 .el \{\
1124 .sp -1
1125 .IP \(bu 2.3
1126 .\}
1127 \fBN\fR\*(Aqs parent list had
1128 \fBI\fR
1129 removed, because it is an ancestor of the other parent
1130 \fBM\fR\&. Still,
1131 \fBN\fR
1132 remained because it is !TREESAME\&.
1133 .RE
1134 .sp
1135 .RS 4
1136 .ie n \{\
1137 \h'-04'\(bu\h'+03'\c
1138 .\}
1139 .el \{\
1140 .sp -1
1141 .IP \(bu 2.3
1142 .\}
1143 \fBP\fR\*(Aqs parent list similarly had
1144 \fBI\fR
1145 removed\&.
1146 \fBP\fR
1147 was then removed completely, because it had one parent and is TREESAME\&.
1148 .RE
1149 .sp
1150 .RS 4
1151 .ie n \{\
1152 \h'-04'\(bu\h'+03'\c
1153 .\}
1154 .el \{\
1155 .sp -1
1156 .IP \(bu 2.3
1157 .\}
1158 \fBQ\fR\*(Aqs parent list had
1159 \fBY\fR
1160 simplified to
1161 \fBX\fR\&.
1162 \fBX\fR
1163 was then removed, because it was a TREESAME root\&.
1164 \fBQ\fR
1165 was then removed completely, because it had one parent and is TREESAME\&.
1166 .RE
1167 .RE
1168 .sp
1169 There is another simplification mode available:
1170 .PP
1171 \-\-ancestry\-path[=<commit>]
1172 .RS 4
1173 Limit the displayed commits to those which are an ancestor of <commit>, or which are a descendant of <commit>, or are <commit> itself\&.
1174 .sp
1175 As an example use case, consider the following commit history:
1176 .sp
1177 .if n \{\
1178 .RS 4
1179 .\}
1180 .nf
1181 D\-\-\-E\-\-\-\-\-\-\-F
1182 / \e \e
1183 B\-\-\-C\-\-\-G\-\-\-H\-\-\-I\-\-\-J
1184 / \e
1185 A\-\-\-\-\-\-\-K\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-L\-\-M
1186 .fi
1187 .if n \{\
1188 .RE
1189 .\}
1190 .sp
1191 A regular
1192 \fID\&.\&.M\fR
1193 computes the set of commits that are ancestors of
1194 \fBM\fR, but excludes the ones that are ancestors of
1195 \fBD\fR\&. This is useful to see what happened to the history leading to
1196 \fBM\fR
1197 since
1198 \fBD\fR, in the sense that \(lqwhat does
1199 \fBM\fR
1200 have that did not exist in
1201 \fBD\fR\(rq\&. The result in this example would be all the commits, except
1202 \fBA\fR
1203 and
1204 \fBB\fR
1205 (and
1206 \fBD\fR
1207 itself, of course)\&.
1208 .sp
1209 When we want to find out what commits in
1210 \fBM\fR
1211 are contaminated with the bug introduced by
1212 \fBD\fR
1213 and need fixing, however, we might want to view only the subset of
1214 \fID\&.\&.M\fR
1215 that are actually descendants of
1216 \fBD\fR, i\&.e\&. excluding
1217 \fBC\fR
1218 and
1219 \fBK\fR\&. This is exactly what the
1220 \fB\-\-ancestry\-path\fR
1221 option does\&. Applied to the
1222 \fID\&.\&.M\fR
1223 range, it results in:
1224 .sp
1225 .if n \{\
1226 .RS 4
1227 .\}
1228 .nf
1229 E\-\-\-\-\-\-\-F
1230 \e \e
1231 G\-\-\-H\-\-\-I\-\-\-J
1232 \e
1233 L\-\-M
1234 .fi
1235 .if n \{\
1236 .RE
1237 .\}
1238 .sp
1239 We can also use
1240 \fB\-\-ancestry\-path=D\fR
1241 instead of
1242 \fB\-\-ancestry\-path\fR
1243 which means the same thing when applied to the
1244 \fID\&.\&.M\fR
1245 range but is just more explicit\&.
1246 .sp
1247 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
1248 \fBD\&.\&.M\fR
1249 which contain that topic in their ancestry path\&. So, using
1250 \fB\-\-ancestry\-path=H D\&.\&.M\fR
1251 for example would result in:
1252 .sp
1253 .if n \{\
1254 .RS 4
1255 .\}
1256 .nf
1257 E
1258 \e
1259 G\-\-\-H\-\-\-I\-\-\-J
1260 \e
1261 L\-\-M
1262 .fi
1263 .if n \{\
1264 .RE
1265 .\}
1266 .sp
1267 Whereas
1268 \fB\-\-ancestry\-path=K D\&.\&.M\fR
1269 would result in
1270 .sp
1271 .if n \{\
1272 .RS 4
1273 .\}
1274 .nf
1275 K\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-L\-\-M
1276 .fi
1277 .if n \{\
1278 .RE
1279 .\}
1280 .sp
1281 .RE
1282 .sp
1283 Before discussing another option, \fB\-\-show\-pulls\fR, we need to create a new example history\&.
1284 .sp
1285 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:
1286 .sp
1287 .if n \{\
1288 .RS 4
1289 .\}
1290 .nf
1291 \&.\-A\-\-\-M\-\-\-\-\-C\-\-N\-\-\-O\-\-\-P
1292 / / \e \e \e/ / /
1293 I B \e R\-\*(Aq`\-Z\*(Aq /
1294 \e / \e/ /
1295 \e / /\e /
1296 `\-\-\-X\-\-\*(Aq `\-\-\-Y\-\-\*(Aq
1297 .fi
1298 .if n \{\
1299 .RE
1300 .\}
1301 .sp
1302 .sp
1303 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\&.
1304 .sp
1305 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:
1306 .sp
1307 .if n \{\
1308 .RS 4
1309 .\}
1310 .nf
1311 I\-\-\-X
1312 .fi
1313 .if n \{\
1314 .RE
1315 .\}
1316 .sp
1317 .sp
1318 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:
1319 .sp
1320 .if n \{\
1321 .RS 4
1322 .\}
1323 .nf
1324 \&.\-A\-\-\-M\-\-\-\-\-\-\-\-N\-\-\-O\-\-\-P
1325 / / \e \e \e/ / /
1326 I B \e R\-\*(Aq`\-\-\*(Aq /
1327 \e / \e/ /
1328 \e / /\e /
1329 `\-\-\-X\-\-\*(Aq `\-\-\-\-\-\-\*(Aq
1330 .fi
1331 .if n \{\
1332 .RE
1333 .\}
1334 .sp
1335 .sp
1336 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\&.
1337 .sp
1338 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:
1339 .sp
1340 .if n \{\
1341 .RS 4
1342 .\}
1343 .nf
1344 \&.\-A\-\-\-M\-\-\&.
1345 / / \e
1346 I B R
1347 \e / /
1348 \e / /
1349 `\-\-\-X\-\-\*(Aq
1350 .fi
1351 .if n \{\
1352 .RE
1353 .\}
1354 .sp
1355 .sp
1356 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\&.
1357 .sp
1358 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\&.
1359 .sp
1360 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\&.
1361 .PP
1362 \-\-show\-pulls
1363 .RS 4
1364 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\&.
1365 .sp
1366 When a merge commit is included by
1367 \fB\-\-show\-pulls\fR, the merge is treated as if it "pulled" the change from another branch\&. When using
1368 \fB\-\-show\-pulls\fR
1369 on this example (and no other options) the resulting graph is:
1370 .sp
1371 .if n \{\
1372 .RS 4
1373 .\}
1374 .nf
1375 I\-\-\-X\-\-\-R\-\-\-N
1376 .fi
1377 .if n \{\
1378 .RE
1379 .\}
1380 .sp
1381 Here, the merge commits
1382 \fBR\fR
1383 and
1384 \fBN\fR
1385 are included because they pulled the commits
1386 \fBX\fR
1387 and
1388 \fBR\fR
1389 into the base branch, respectively\&. These merges are the reason the commits
1390 \fBA\fR
1391 and
1392 \fBB\fR
1393 do not appear in the default history\&.
1394 .sp
1395 When
1396 \fB\-\-show\-pulls\fR
1397 is paired with
1398 \fB\-\-simplify\-merges\fR, the graph includes all of the necessary information:
1399 .sp
1400 .if n \{\
1401 .RS 4
1402 .\}
1403 .nf
1404 \&.\-A\-\-\-M\-\-\&. N
1405 / / \e /
1406 I B R
1407 \e / /
1408 \e / /
1409 `\-\-\-X\-\-\*(Aq
1410 .fi
1411 .if n \{\
1412 .RE
1413 .\}
1414 .sp
1415 Notice that since
1416 \fBM\fR
1417 is reachable from
1418 \fBR\fR, the edge from
1419 \fBN\fR
1420 to
1421 \fBM\fR
1422 was simplified away\&. However,
1423 \fBN\fR
1424 still appears in the history as an important commit because it "pulled" the change
1425 \fBR\fR
1426 into the main branch\&.
1427 .RE
1428 .sp
1429 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)\&.
1430 .SH "MAPPING AUTHORS"
1431 .sp
1432 See \fBgitmailmap\fR(5)\&.
1433 .sp
1434 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\&.
1435 .SH "GIT"
1436 .sp
1437 Part of the \fBgit\fR(1) suite