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