doc/pretty-formats: explain shortening of %gd
[git/git.git] / Documentation / rev-list-options.txt
CommitLineData
fdcf39e5
MV
1Commit Limiting
2~~~~~~~~~~~~~~~
3
4Besides specifying a range of commits that should be listed using the
5special notations explained in the description, additional commit
a23e3138
JH
6limiting may be applied.
7
8Using more options generally further limits the output (e.g.
9`--since=<date1>` limits to commits newer than `<date1>`, and using it
10with `--grep=<pattern>` further limits to commits whose log message
11has a line that matches `<pattern>`), unless otherwise noted.
12
13Note that these are applied before commit
14ordering and formatting options, such as `--reverse`.
fdcf39e5
MV
15
16--
17
70c2a258
NTND
18-<number>::
19-n <number>::
982962ce 20--max-count=<number>::
841d8118 21 Limit the number of commits to output.
fdcf39e5 22
982962ce 23--skip=<number>::
fdcf39e5
MV
24 Skip 'number' commits before starting to show the commit output.
25
982962ce
MM
26--since=<date>::
27--after=<date>::
fdcf39e5
MV
28 Show commits more recent than a specific date.
29
982962ce
MM
30--until=<date>::
31--before=<date>::
fdcf39e5
MV
32 Show commits older than a specific date.
33
56b6d01d 34ifdef::git-rev-list[]
982962ce
MM
35--max-age=<timestamp>::
36--min-age=<timestamp>::
fdcf39e5 37 Limit the commits output to specified time range.
56b6d01d 38endif::git-rev-list[]
fdcf39e5 39
982962ce
MM
40--author=<pattern>::
41--committer=<pattern>::
fdcf39e5 42 Limit the commits output to ones with author/committer
a23e3138
JH
43 header lines that match the specified pattern (regular
44 expression). With more than one `--author=<pattern>`,
45 commits whose author matches any of the given patterns are
46 chosen (similarly for multiple `--committer=<pattern>`).
fdcf39e5 47
72fd13f7 48--grep-reflog=<pattern>::
72fd13f7
NTND
49 Limit the commits output to ones with reflog entries that
50 match the specified pattern (regular expression). With
51 more than one `--grep-reflog`, commits whose reflog message
baa6378f
JH
52 matches any of the given patterns are chosen. It is an
53 error to use this option unless `--walk-reflogs` is in use.
72fd13f7 54
982962ce 55--grep=<pattern>::
fdcf39e5 56 Limit the commits output to ones with log message that
a23e3138
JH
57 matches the specified pattern (regular expression). With
58 more than one `--grep=<pattern>`, commits whose message
59 matches any of the given patterns are chosen (but see
60 `--all-match`).
2aea7a51 61ifndef::git-rev-list[]
38cfe915 62+
7348cdeb
MG
63When `--show-notes` is in effect, the message from the notes is
64matched as if it were part of the log message.
2aea7a51 65endif::git-rev-list[]
fdcf39e5 66
7756ba74 67--all-match::
4528aa1a 68 Limit the commits output to ones that match all given `--grep`,
a23e3138 69 instead of ones that match at least one.
7756ba74 70
22dfa8a2
CJ
71--invert-grep::
72 Limit the commits output to ones with log message that do not
73 match the pattern specified with `--grep=<pattern>`.
74
3240240f
SB
75-i::
76--regexp-ignore-case::
19d6eb41
JSJ
77 Match the regular expression limiting patterns without regard to letter
78 case.
fdcf39e5 79
727b6fc3 80--basic-regexp::
727b6fc3
JH
81 Consider the limiting patterns to be basic regular expressions;
82 this is the default.
83
3240240f
SB
84-E::
85--extended-regexp::
fdcf39e5
MV
86 Consider the limiting patterns to be extended regular expressions
87 instead of the default basic regular expressions.
88
3240240f
SB
89-F::
90--fixed-strings::
dc1c0fff
JN
91 Consider the limiting patterns to be fixed strings (don't interpret
92 pattern as a regular expression).
93
727b6fc3 94--perl-regexp::
19d6eb41 95 Consider the limiting patterns to be Perl-compatible regular expressions.
727b6fc3
JH
96 Requires libpcre to be compiled in.
97
fdcf39e5 98--remove-empty::
fdcf39e5
MV
99 Stop when a given path disappears from the tree.
100
2657420d 101--merges::
6a6ebded 102 Print only merge commits. This is exactly the same as `--min-parents=2`.
2657420d 103
fdcf39e5 104--no-merges::
6a6ebded
MG
105 Do not print commits with more than one parent. This is
106 exactly the same as `--max-parents=1`.
107
108--min-parents=<number>::
109--max-parents=<number>::
110--no-min-parents::
111--no-max-parents::
5104d21f 112 Show only commits which have at least (or at most) that many parent
6a6ebded
MG
113 commits. In particular, `--max-parents=1` is the same as `--no-merges`,
114 `--min-parents=2` is the same as `--merges`. `--max-parents=0`
115 gives all root commits and `--min-parents=3` all octopus merges.
116+
117`--no-min-parents` and `--no-max-parents` reset these limits (to no limit)
118again. Equivalent forms are `--min-parents=0` (any commit has 0 or more
119parents) and `--max-parents=-1` (negative numbers denote no upper limit).
fdcf39e5
MV
120
121--first-parent::
122 Follow only the first parent commit upon seeing a merge
123 commit. This option can give a better overview when
124 viewing the evolution of a particular topic branch,
125 because merges into a topic branch tend to be only about
126 adjusting to updated upstream from time to time, and
127 this option allows you to ignore the individual commits
f88851c6
KD
128 brought in to your history by such a merge. Cannot be
129 combined with --bisect.
fdcf39e5
MV
130
131--not::
fdcf39e5 132 Reverses the meaning of the '{caret}' prefix (or lack thereof)
4528aa1a 133 for all following revision specifiers, up to the next `--not`.
fdcf39e5
MV
134
135--all::
cc1b8d8b 136 Pretend as if all the refs in `refs/` are listed on the
fdcf39e5 137 command line as '<commit>'.
c2e6385d 138
62b4698e 139--branches[=<pattern>]::
cc1b8d8b 140 Pretend as if all the refs in `refs/heads` are listed
62b4698e 141 on the command line as '<commit>'. If '<pattern>' is given, limit
b09fe971 142 branches to ones matching given shell glob. If pattern lacks '?',
e34bb2e7 143 '{asterisk}', or '[', '/{asterisk}' at the end is implied.
c2e6385d 144
62b4698e 145--tags[=<pattern>]::
cc1b8d8b 146 Pretend as if all the refs in `refs/tags` are listed
62b4698e 147 on the command line as '<commit>'. If '<pattern>' is given, limit
e34bb2e7
CMN
148 tags to ones matching given shell glob. If pattern lacks '?', '{asterisk}',
149 or '[', '/{asterisk}' at the end is implied.
c2e6385d 150
62b4698e 151--remotes[=<pattern>]::
cc1b8d8b 152 Pretend as if all the refs in `refs/remotes` are listed
62b4698e 153 on the command line as '<commit>'. If '<pattern>' is given, limit
0e615b25 154 remote-tracking branches to ones matching given shell glob.
e34bb2e7 155 If pattern lacks '?', '{asterisk}', or '[', '/{asterisk}' at the end is implied.
fdcf39e5 156
62b4698e
ŠN
157--glob=<glob-pattern>::
158 Pretend as if all the refs matching shell glob '<glob-pattern>'
d08bae7e 159 are listed on the command line as '<commit>'. Leading 'refs/',
e34bb2e7
CMN
160 is automatically prepended if missing. If pattern lacks '?', '{asterisk}',
161 or '[', '/{asterisk}' at the end is implied.
d08bae7e 162
574d370b
JS
163--exclude=<glob-pattern>::
164
165 Do not include refs matching '<glob-pattern>' that the next `--all`,
166 `--branches`, `--tags`, `--remotes`, or `--glob` would otherwise
167 consider. Repetitions of this option accumulate exclusion patterns
168 up to the next `--all`, `--branches`, `--tags`, `--remotes`, or
169 `--glob` option (other options or arguments do not clear
f745acb0 170 accumulated patterns).
574d370b
JS
171+
172The patterns given should not begin with `refs/heads`, `refs/tags`, or
173`refs/remotes` when applied to `--branches`, `--tags`, or `--remotes`,
174respectively, and they must begin with `refs/` when applied to `--glob`
175or `--all`. If a trailing '/{asterisk}' is intended, it must be given
176explicitly.
177
41d018d1
JK
178--reflog::
179 Pretend as if all objects mentioned by reflogs are listed on the
180 command line as `<commit>`.
181
cc243c3c 182--ignore-missing::
cc243c3c
JH
183 Upon seeing an invalid object name in the input, pretend as if
184 the bad input was not given.
d08bae7e 185
af06e93a
CC
186ifndef::git-rev-list[]
187--bisect::
cc1b8d8b 188 Pretend as if the bad bisection ref `refs/bisect/bad`
af06e93a 189 was listed and as if it was followed by `--not` and the good
cc1b8d8b 190 bisection refs `refs/bisect/good-*` on the command
f88851c6 191 line. Cannot be combined with --first-parent.
af06e93a
CC
192endif::git-rev-list[]
193
fdcf39e5 194--stdin::
fdcf39e5 195 In addition to the '<commit>' listed on the command
60da8b15
JH
196 line, read them from the standard input. If a '--' separator is
197 seen, stop reading commits and start reading paths to limit the
198 result.
fdcf39e5 199
8b3dce56 200ifdef::git-rev-list[]
fdcf39e5 201--quiet::
fdcf39e5
MV
202 Don't print anything to standard output. This form
203 is primarily meant to allow the caller to
204 test the exit status to see if a range of objects is fully
205 connected (or not). It is faster than redirecting stdout
4528aa1a 206 to `/dev/null` as the output does not have to be formatted.
adf60f14 207endif::git-rev-list[]
fdcf39e5 208
cb56e309 209--cherry-mark::
cb56e309
MG
210 Like `--cherry-pick` (see below) but mark equivalent commits
211 with `=` rather than omitting them, and inequivalent ones with `+`.
212
fdcf39e5 213--cherry-pick::
fdcf39e5 214 Omit any commit that introduces the same change as
4528aa1a 215 another commit on the ``other side'' when the set of
fdcf39e5
MV
216 commits are limited with symmetric difference.
217+
218For example, if you have two branches, `A` and `B`, a usual way
219to list all commits on only one side of them is with
3add01bb 220`--left-right` (see the example below in the description of
19d6eb41
JSJ
221the `--left-right` option). However, it shows the commits that were
222cherry-picked from the other branch (for example, ``3rd on b'' may be
223cherry-picked from branch A). With this option, such pairs of commits are
fdcf39e5
MV
224excluded from the output.
225
59c8afdf
MG
226--left-only::
227--right-only::
59c8afdf
MG
228 List only commits on the respective side of a symmetric range,
229 i.e. only those which would be marked `<` resp. `>` by
230 `--left-right`.
231+
232For example, `--cherry-pick --right-only A...B` omits those
233commits from `B` which are in `A` or are patch-equivalent to a commit in
6cf378f0 234`A`. In other words, this lists the `+` commits from `git cherry A B`.
59c8afdf
MG
235More precisely, `--cherry-pick --right-only --no-merges` gives the exact
236list.
237
94f605ec 238--cherry::
94f605ec
MG
239 A synonym for `--right-only --cherry-mark --no-merges`; useful to
240 limit the output to the commits on our side and mark those that
241 have been applied to the other side of a forked history with
242 `git log --cherry upstream...mybranch`, similar to
243 `git cherry upstream mybranch`.
244
3240240f
SB
245-g::
246--walk-reflogs::
fdcf39e5
MV
247 Instead of walking the commit ancestry chain, walk
248 reflog entries from the most recent one to older ones.
249 When this option is used you cannot specify commits to
250 exclude (that is, '{caret}commit', 'commit1..commit2',
a58088ab 251 and 'commit1\...commit2' notations cannot be used).
fdcf39e5 252+
4528aa1a 253With `--pretty` format other than `oneline` (for obvious reasons),
fdcf39e5 254this causes the output to have two extra lines of information
83c9f95c
JK
255taken from the reflog. The reflog designator in the output may be shown
256as `ref@{Nth}` (where `Nth` is the reverse-chronological index in the
257reflog) or as `ref@{timestamp}` (with the timestamp for that entry),
258depending on a few rules:
259+
260--
2611. If the starting point is specified as `ref@{Nth}`, show the index
262format.
263+
2642. If the starting point was specified as `ref@{now}`, show the
265timestamp format.
266+
2673. If neither was used, but `--date` was given on the command line, show
268the timestamp in the format requested by `--date`.
269+
2704. Otherwise, show the index format.
271--
272+
273Under `--pretty=oneline`, the commit message is
fdcf39e5 274prefixed with this information on the same line.
4528aa1a 275This option cannot be combined with `--reverse`.
fdcf39e5
MV
276See also linkgit:git-reflog[1].
277
278--merge::
fdcf39e5
MV
279 After a failed merge, show refs that touch files having a
280 conflict and don't exist on all heads to merge.
281
282--boundary::
e32db66d
KB
283 Output excluded boundary commits. Boundary commits are
284 prefixed with `-`.
fdcf39e5 285
aa32939f
VM
286ifdef::git-rev-list[]
287--use-bitmap-index::
288
289 Try to speed up the traversal using the pack bitmap index (if
290 one is available). Note that when traversing with `--objects`,
291 trees and blobs will not have their associated path printed.
292endif::git-rev-list[]
293
70d9895e
TR
294--
295
296History Simplification
297~~~~~~~~~~~~~~~~~~~~~~
298
7bc2508b
SB
299Sometimes you are only interested in parts of the history, for example the
300commits modifying a particular <path>. But there are two parts of
301'History Simplification', one part is selecting the commits and the other
302is how to do it, as there are various strategies to simplify the history.
303
304The following options select the commits to be shown:
305
306<paths>::
7bc2508b
SB
307 Commits modifying the given <paths> are selected.
308
309--simplify-by-decoration::
7bc2508b
SB
310 Commits that are referred by some branch or tag are selected.
311
312Note that extra commits can be shown to give a meaningful history.
313
314The following options affect the way the simplification is performed:
315
316Default mode::
7bc2508b
SB
317 Simplifies the history to the simplest history explaining the
318 final state of the tree. Simplest because it prunes some side
319 branches if the end result is the same (i.e. merging branches
320 with the same content)
321
322--full-history::
df6b0cad 323 Same as the default mode, but does not prune some history.
7bc2508b
SB
324
325--dense::
7bc2508b
SB
326 Only the selected commits are shown, plus some to have a
327 meaningful history.
328
329--sparse::
7bc2508b
SB
330 All commits in the simplified history are shown.
331
332--simplify-merges::
4528aa1a 333 Additional option to `--full-history` to remove some needless
7bc2508b
SB
334 merges from the resulting history, as there are no selected
335 commits contributing to this merge.
336
57456ef4 337--ancestry-path::
57456ef4
JH
338 When given a range of commits to display (e.g. 'commit1..commit2'
339 or 'commit2 {caret}commit1'), only display commits that exist
340 directly on the ancestry chain between the 'commit1' and
341 'commit2', i.e. commits that are both descendants of 'commit1',
342 and ancestors of 'commit2'.
343
7bc2508b 344A more detailed explanation follows.
70d9895e
TR
345
346Suppose you specified `foo` as the <paths>. We shall call commits
347that modify `foo` !TREESAME, and the rest TREESAME. (In a diff
348filtered for `foo`, they look different and equal, respectively.)
349
350In the following, we will always refer to the same example history to
351illustrate the differences between simplification settings. We assume
352that you are filtering for a file `foo` in this commit graph:
353-----------------------------------------------------------------------
143f1eaf
KB
354 .-A---M---N---O---P---Q
355 / / / / / /
356 I B C D E Y
357 \ / / / / /
358 `-------------' X
70d9895e 359-----------------------------------------------------------------------
143f1eaf 360The horizontal line of history A---Q is taken to be the first parent of
70d9895e
TR
361each merge. The commits are:
362
363* `I` is the initial commit, in which `foo` exists with contents
4528aa1a 364 ``asdf'', and a file `quux` exists with contents ``quux''. Initial
70d9895e
TR
365 commits are compared to an empty tree, so `I` is !TREESAME.
366
4528aa1a 367* In `A`, `foo` contains just ``foo''.
70d9895e
TR
368
369* `B` contains the same change as `A`. Its merge `M` is trivial and
370 hence TREESAME to all parents.
371
4528aa1a 372* `C` does not change `foo`, but its merge `N` changes it to ``foobar'',
70d9895e
TR
373 so it is not TREESAME to any parent.
374
4528aa1a
JSJ
375* `D` sets `foo` to ``baz''. Its merge `O` combines the strings from
376 `N` and `D` to ``foobarbaz''; i.e., it is not TREESAME to any parent.
70d9895e 377
4528aa1a
JSJ
378* `E` changes `quux` to ``xyzzy'', and its merge `P` combines the
379 strings to ``quux xyzzy''. `P` is TREESAME to `O`, but not to `E`.
70d9895e 380
17b83d71 381* `X` is an independent root commit that added a new file `side`, and `Y`
143f1eaf
KB
382 modified it. `Y` is TREESAME to `X`. Its merge `Q` added `side` to `P`, and
383 `Q` is TREESAME to `P`, but not to `Y`.
384
4528aa1a
JSJ
385`rev-list` walks backwards through history, including or excluding
386commits based on whether `--full-history` and/or parent rewriting
387(via `--parents` or `--children`) are used. The following settings
70d9895e
TR
388are available.
389
390Default mode::
70d9895e 391 Commits are included if they are not TREESAME to any parent
4528aa1a 392 (though this can be changed, see `--sparse` below). If the
70d9895e
TR
393 commit was a merge, and it was TREESAME to one parent, follow
394 only that parent. (Even if there are several TREESAME
395 parents, follow only one of them.) Otherwise, follow all
396 parents.
397+
398This results in:
399+
400-----------------------------------------------------------------------
401 .-A---N---O
f70d0586 402 / / /
70d9895e
TR
403 I---------D
404-----------------------------------------------------------------------
405+
406Note how the rule to only follow the TREESAME parent, if one is
407available, removed `B` from consideration entirely. `C` was
408considered via `N`, but is TREESAME. Root commits are compared to an
409empty tree, so `I` is !TREESAME.
410+
4528aa1a 411Parent/child relations are only visible with `--parents`, but that does
70d9895e
TR
412not affect the commits selected in default mode, so we have shown the
413parent lines.
414
415--full-history without parent rewriting::
70d9895e
TR
416 This mode differs from the default in one point: always follow
417 all parents of a merge, even if it is TREESAME to one of them.
418 Even if more than one side of the merge has commits that are
419 included, this does not imply that the merge itself is! In
420 the example, we get
421+
422-----------------------------------------------------------------------
143f1eaf 423 I A B N D O P Q
70d9895e
TR
424-----------------------------------------------------------------------
425+
d0af663e 426`M` was excluded because it is TREESAME to both parents. `E`,
70d9895e
TR
427`C` and `B` were all walked, but only `B` was !TREESAME, so the others
428do not appear.
429+
430Note that without parent rewriting, it is not really possible to talk
431about the parent/child relationships between the commits, so we show
432them disconnected.
433
434--full-history with parent rewriting::
70d9895e 435 Ordinary commits are only included if they are !TREESAME
4528aa1a 436 (though this can be changed, see `--sparse` below).
70d9895e
TR
437+
438Merges are always included. However, their parent list is rewritten:
439Along each parent, prune away commits that are not included
440themselves. This results in
441+
442-----------------------------------------------------------------------
143f1eaf 443 .-A---M---N---O---P---Q
70d9895e
TR
444 / / / / /
445 I B / D /
446 \ / / / /
447 `-------------'
448-----------------------------------------------------------------------
449+
4528aa1a 450Compare to `--full-history` without rewriting above. Note that `E`
70d9895e
TR
451was pruned away because it is TREESAME, but the parent list of P was
452rewritten to contain `E`'s parent `I`. The same happened for `C` and
143f1eaf 453`N`, and `X`, `Y` and `Q`.
70d9895e
TR
454
455In addition to the above settings, you can change whether TREESAME
456affects inclusion:
457
3240240f 458--dense::
70d9895e
TR
459 Commits that are walked are included if they are not TREESAME
460 to any parent.
461
3240240f 462--sparse::
70d9895e
TR
463 All commits that are walked are included.
464+
4528aa1a 465Note that without `--full-history`, this still simplifies merges: if
70d9895e
TR
466one of the parents is TREESAME, we follow only that one, so the other
467sides of the merge are never walked.
fdcf39e5 468
d266a988 469--simplify-merges::
d266a988 470 First, build a history graph in the same way that
4528aa1a 471 `--full-history` with parent rewriting does (see above).
d266a988
TR
472+
473Then simplify each commit `C` to its replacement `C'` in the final
474history according to the following rules:
475+
476--
477* Set `C'` to `C`.
478+
479* Replace each parent `P` of `C'` with its simplification `P'`. In
143f1eaf
KB
480 the process, drop parents that are ancestors of other parents or that are
481 root commits TREESAME to an empty tree, and remove duplicates, but take care
482 to never drop all parents that we are TREESAME to.
d266a988
TR
483+
484* If after this parent rewriting, `C'` is a root or merge commit (has
485 zero or >1 parents), a boundary commit, or !TREESAME, it remains.
486 Otherwise, it is replaced with its only parent.
487--
488+
489The effect of this is best shown by way of comparing to
4528aa1a 490`--full-history` with parent rewriting. The example turns into:
d266a988
TR
491+
492-----------------------------------------------------------------------
493 .-A---M---N---O
494 / / /
495 I B D
496 \ / /
497 `---------'
498-----------------------------------------------------------------------
499+
19d6eb41 500Note the major differences in `N`, `P`, and `Q` over `--full-history`:
d266a988
TR
501+
502--
503* `N`'s parent list had `I` removed, because it is an ancestor of the
504 other parent `M`. Still, `N` remained because it is !TREESAME.
505+
506* `P`'s parent list similarly had `I` removed. `P` was then
507 removed completely, because it had one parent and is TREESAME.
143f1eaf
KB
508+
509* `Q`'s parent list had `Y` simplified to `X`. `X` was then removed, because it
510 was a TREESAME root. `Q` was then removed completely, because it had one
511 parent and is TREESAME.
d266a988 512--
fdcf39e5 513
57456ef4
JH
514Finally, there is a fifth simplification mode available:
515
516--ancestry-path::
57456ef4 517 Limit the displayed commits to those directly on the ancestry
4528aa1a
JSJ
518 chain between the ``from'' and ``to'' commits in the given commit
519 range. I.e. only display commits that are ancestor of the ``to''
19d6eb41 520 commit and descendants of the ``from'' commit.
57456ef4
JH
521+
522As an example use case, consider the following commit history:
523+
524-----------------------------------------------------------------------
525 D---E-------F
526 / \ \
527 B---C---G---H---I---J
528 / \
529 A-------K---------------L--M
530-----------------------------------------------------------------------
531+
532A regular 'D..M' computes the set of commits that are ancestors of `M`,
533but excludes the ones that are ancestors of `D`. This is useful to see
534what happened to the history leading to `M` since `D`, in the sense
4528aa1a 535that ``what does `M` have that did not exist in `D`''. The result in this
57456ef4
JH
536example would be all the commits, except `A` and `B` (and `D` itself,
537of course).
538+
539When we want to find out what commits in `M` are contaminated with the
540bug introduced by `D` and need fixing, however, we might want to view
541only the subset of 'D..M' that are actually descendants of `D`, i.e.
4528aa1a 542excluding `C` and `K`. This is exactly what the `--ancestry-path`
57456ef4
JH
543option does. Applied to the 'D..M' range, it results in:
544+
545-----------------------------------------------------------------------
546 E-------F
547 \ \
548 G---H---I---J
549 \
550 L--M
551-----------------------------------------------------------------------
552
4528aa1a 553The `--simplify-by-decoration` option allows you to view only the
3fcfd662
NS
554big picture of the topology of the history, by omitting commits
555that are not referenced by tags. Commits are marked as !TREESAME
556(in other words, kept after history simplification rules described
557above) if (1) they are referenced by tags, or (2) they change the
558contents of the paths given on the command line. All other
559commits are marked as TREESAME (subject to be simplified away).
560
fdcf39e5 561ifdef::git-rev-list[]
70d9895e
TR
562Bisection Helpers
563~~~~~~~~~~~~~~~~~
564
fdcf39e5 565--bisect::
4528aa1a
JSJ
566 Limit output to the one commit object which is roughly halfway between
567 included and excluded commits. Note that the bad bisection ref
568 `refs/bisect/bad` is added to the included commits (if it
569 exists) and the good bisection refs `refs/bisect/good-*` are
570 added to the excluded commits (if they exist). Thus, supposing there
571 are no refs in `refs/bisect/`, if
572+
fdcf39e5 573-----------------------------------------------------------------------
6514aa36 574 $ git rev-list --bisect foo ^bar ^baz
fdcf39e5 575-----------------------------------------------------------------------
4528aa1a 576+
fdcf39e5 577outputs 'midpoint', the output of the two commands
4528aa1a 578+
fdcf39e5 579-----------------------------------------------------------------------
6514aa36
CC
580 $ git rev-list foo ^midpoint
581 $ git rev-list midpoint ^bar ^baz
fdcf39e5 582-----------------------------------------------------------------------
4528aa1a 583+
fdcf39e5
MV
584would be of roughly the same length. Finding the change which
585introduces a regression is thus reduced to a binary search: repeatedly
586generate and test new 'midpoint's until the commit chain is of length
f88851c6 587one. Cannot be combined with --first-parent.
fdcf39e5
MV
588
589--bisect-vars::
4528aa1a
JSJ
590 This calculates the same as `--bisect`, except that refs in
591 `refs/bisect/` are not used, and except that this outputs
592 text ready to be eval'ed by the shell. These lines will assign the
593 name of the midpoint revision to the variable `bisect_rev`, and the
594 expected number of commits to be tested after `bisect_rev` is tested
595 to `bisect_nr`, the expected number of commits to be tested if
596 `bisect_rev` turns out to be good to `bisect_good`, the expected
597 number of commits to be tested if `bisect_rev` turns out to be bad to
598 `bisect_bad`, and the number of commits we are bisecting right now to
599 `bisect_all`.
fdcf39e5
MV
600
601--bisect-all::
4528aa1a
JSJ
602 This outputs all the commit objects between the included and excluded
603 commits, ordered by their distance to the included and excluded
604 commits. Refs in `refs/bisect/` are not used. The farthest
605 from them is displayed first. (This is the only one displayed by
606 `--bisect`.)
3d2d4f96 607+
fdcf39e5
MV
608This is useful because it makes it easy to choose a good commit to
609test when you want to avoid to test some of them for some reason (they
610may not compile for example).
3d2d4f96 611+
fdcf39e5
MV
612This option can be used along with `--bisect-vars`, in this case,
613after all the sorted commit objects, there will be the same text as if
614`--bisect-vars` had been used alone.
615endif::git-rev-list[]
616
fdcf39e5
MV
617
618Commit Ordering
619~~~~~~~~~~~~~~~
620
621By default, the commits are shown in reverse chronological order.
622
3f0350cc
JH
623--date-order::
624 Show no parents before all of its children are shown, but
625 otherwise show commits in the commit timestamp order.
fdcf39e5 626
81c6b38b
JH
627--author-date-order::
628 Show no parents before all of its children are shown, but
629 otherwise show commits in the author timestamp order.
630
3f0350cc
JH
631--topo-order::
632 Show no parents before all of its children are shown, and
633 avoid showing commits on multiple lines of history
634 intermixed.
635+
636For example, in a commit history like this:
637+
638----------------------------------------------------------------
fdcf39e5 639
3f0350cc
JH
640 ---1----2----4----7
641 \ \
642 3----5----6----8---
fdcf39e5 643
3f0350cc
JH
644----------------------------------------------------------------
645+
646where the numbers denote the order of commit timestamps, `git
647rev-list` and friends with `--date-order` show the commits in the
648timestamp order: 8 7 6 5 4 3 2 1.
649+
650With `--topo-order`, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5
6513 1); some older commits are shown before newer ones in order to
652avoid showing the commits from two parallel development track mixed
653together.
fdcf39e5
MV
654
655--reverse::
fdcf39e5 656 Output the commits in reverse order.
4528aa1a 657 Cannot be combined with `--walk-reflogs`.
fdcf39e5
MV
658
659Object Traversal
660~~~~~~~~~~~~~~~~
661
2de9b711 662These options are mostly targeted for packing of Git repositories.
fdcf39e5 663
3cab02de 664ifdef::git-rev-list[]
fdcf39e5 665--objects::
fdcf39e5 666 Print the object IDs of any object referenced by the listed
4528aa1a 667 commits. `--objects foo ^bar` thus means ``send me
fdcf39e5 668 all object IDs which I need to download if I have the commit
4528aa1a 669 object _bar_ but not _foo_''.
fdcf39e5
MV
670
671--objects-edge::
4528aa1a
JSJ
672 Similar to `--objects`, but also print the IDs of excluded
673 commits prefixed with a ``-'' character. This is used by
8297643f 674 linkgit:git-pack-objects[1] to build a ``thin'' pack, which records
fdcf39e5
MV
675 objects in deltified form based on objects contained in these
676 excluded commits to reduce network traffic.
677
1684c1b2 678--objects-edge-aggressive::
679 Similar to `--objects-edge`, but it tries harder to find excluded
2dacf26d 680 commits at the cost of increased time. This is used instead of
681 `--objects-edge` to build ``thin'' packs for shallow repositories.
1684c1b2 682
3cab02de
JH
683--indexed-objects::
684 Pretend as if all trees and blobs used by the index are listed
685 on the command line. Note that you probably want to use
686 `--objects`, too.
687
fdcf39e5 688--unpacked::
4528aa1a 689 Only useful with `--objects`; print the object IDs that are not
fdcf39e5 690 in packs.
3cab02de 691endif::git-rev-list[]
fdcf39e5 692
ca92e59e 693--no-walk[=(sorted|unsorted)]::
ca92e59e
MZ
694 Only show the given commits, but do not traverse their ancestors.
695 This has no effect if a range is specified. If the argument
19d6eb41 696 `unsorted` is given, the commits are shown in the order they were
4528aa1a 697 given on the command line. Otherwise (if `sorted` or no argument
19d6eb41 698 was given), the commits are shown in reverse chronological order
ca92e59e 699 by commit time.
695985f4 700 Cannot be combined with `--graph`.
fdcf39e5
MV
701
702--do-walk::
4528aa1a 703 Overrides a previous `--no-walk`.
f98fd436
MG
704
705Commit Formatting
706~~~~~~~~~~~~~~~~~
707
708ifdef::git-rev-list[]
709Using these options, linkgit:git-rev-list[1] will act similar to the
710more specialized family of commit log tools: linkgit:git-log[1],
711linkgit:git-show[1], and linkgit:git-whatchanged[1]
712endif::git-rev-list[]
713
714include::pretty-options.txt[]
715
716--relative-date::
f98fd436
MG
717 Synonym for `--date=relative`.
718
4b1c5e1d 719--date=<format>::
f98fd436 720 Only takes effect for dates shown in human-readable format, such
4528aa1a 721 as when using `--pretty`. `log.date` config variable sets a default
add00ba2
JK
722 value for the log command's `--date` option. By default, dates
723 are shown in the original time zone (either committer's or
724 author's). If `-local` is appended to the format (e.g.,
725 `iso-local`), the user's local time zone is used instead.
f98fd436
MG
726+
727`--date=relative` shows dates relative to the current time,
add00ba2
JK
728e.g. ``2 hours ago''. The `-local` option cannot be used with
729`--raw` or `--relative`.
f98fd436 730+
add00ba2 731`--date=local` is an alias for `--date=default-local`.
f98fd436 732+
466fb674
BB
733`--date=iso` (or `--date=iso8601`) shows timestamps in a ISO 8601-like format.
734The differences to the strict ISO 8601 format are:
735
736 - a space instead of the `T` date/time delimiter
737 - a space between time and time zone
738 - no colon between hours and minutes of the time zone
739
740+
741`--date=iso-strict` (or `--date=iso8601-strict`) shows timestamps in strict
742ISO 8601 format.
f98fd436
MG
743+
744`--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822
19d6eb41 745format, often found in email messages.
f98fd436 746+
19d6eb41 747`--date=short` shows only the date, but not the time, in `YYYY-MM-DD` format.
f98fd436 748+
2de9b711 749`--date=raw` shows the date in the internal raw Git format `%s %z` format.
f98fd436 750+
aa1462cc
JK
751`--date=format:...` feeds the format `...` to your system `strftime`.
752Use `--date=format:%c` to show the date in your system locale's
753preferred format. See the `strftime` manual for a complete list of
add00ba2
JK
754format placeholders. When using `-local`, the correct syntax is
755`--date=format-local:...`.
aa1462cc 756+
add00ba2
JK
757`--date=default` is the default format, and is similar to
758`--date=rfc2822`, with a few exceptions:
759
760 - there is no comma after the day-of-week
761
762 - the time zone is omitted when the local time zone is used
f98fd436
MG
763
764ifdef::git-rev-list[]
765--header::
f98fd436
MG
766 Print the contents of the commit in raw-format; each record is
767 separated with a NUL character.
768endif::git-rev-list[]
769
770--parents::
f98fd436
MG
771 Print also the parents of the commit (in the form "commit parent...").
772 Also enables parent rewriting, see 'History Simplification' below.
773
774--children::
f98fd436
MG
775 Print also the children of the commit (in the form "commit child...").
776 Also enables parent rewriting, see 'History Simplification' below.
777
778ifdef::git-rev-list[]
779--timestamp::
780 Print the raw commit timestamp.
781endif::git-rev-list[]
782
783--left-right::
f98fd436
MG
784 Mark which side of a symmetric diff a commit is reachable from.
785 Commits from the left side are prefixed with `<` and those from
786 the right with `>`. If combined with `--boundary`, those
787 commits are prefixed with `-`.
788+
789For example, if you have this topology:
790+
791-----------------------------------------------------------------------
792 y---b---b branch B
793 / \ /
794 / .
795 / / \
796 o---x---a---a branch A
797-----------------------------------------------------------------------
798+
799you would get an output like this:
800+
801-----------------------------------------------------------------------
802 $ git rev-list --left-right --boundary --pretty=oneline A...B
803
804 >bbbbbbb... 3rd on b
805 >bbbbbbb... 2nd on b
806 <aaaaaaa... 3rd on a
807 <aaaaaaa... 2nd on a
808 -yyyyyyy... 1st on b
809 -xxxxxxx... 1st on a
810-----------------------------------------------------------------------
811
812--graph::
f98fd436
MG
813 Draw a text-based graphical representation of the commit history
814 on the left hand side of the output. This may cause extra lines
815 to be printed in between commits, in order for the graph history
816 to be drawn properly.
695985f4 817 Cannot be combined with `--no-walk`.
f98fd436
MG
818+
819This enables parent rewriting, see 'History Simplification' below.
820+
4528aa1a
JSJ
821This implies the `--topo-order` option by default, but the
822`--date-order` option may also be specified.
f98fd436 823
1b32dece
NTND
824--show-linear-break[=<barrier>]::
825 When --graph is not used, all history branches are flattened
826 which can make it hard to see that the two consecutive commits
827 do not belong to a linear branch. This option puts a barrier
828 in between them in that case. If `<barrier>` is specified, it
829 is the string that will be shown instead of the default one.
830
f98fd436
MG
831ifdef::git-rev-list[]
832--count::
833 Print a number stating how many commits would have been
834 listed, and suppress all other output. When used together
4528aa1a 835 with `--left-right`, instead print the counts for left and
b388e14b 836 right commits, separated by a tab. When used together with
4528aa1a 837 `--cherry-mark`, omit patch equivalent commits from these
b388e14b
MG
838 counts and print the count for equivalent commits separated
839 by a tab.
f98fd436
MG
840endif::git-rev-list[]
841
f98fd436
MG
842ifndef::git-rev-list[]
843Diff Formatting
844~~~~~~~~~~~~~~~
845
19d6eb41 846Listed below are options that control the formatting of diff output.
f98fd436
MG
847Some of them are specific to linkgit:git-rev-list[1], however other diff
848options may be given. See linkgit:git-diff-files[1] for more options.
849
850-c::
f98fd436
MG
851 With this option, diff output for a merge commit
852 shows the differences from each of the parents to the merge result
853 simultaneously instead of showing pairwise diff between a parent
854 and the result one at a time. Furthermore, it lists only files
855 which were modified from all parents.
856
857--cc::
4528aa1a 858 This flag implies the `-c` option and further compresses the
f98fd436
MG
859 patch output by omitting uninteresting hunks whose contents in
860 the parents have only two variants and the merge result picks
861 one of them without modification.
862
863-m::
f98fd436
MG
864 This flag makes the merge commits show the full diff like
865 regular commits; for each merge parent, a separate log entry
866 and diff is generated. An exception is that only diff against
4528aa1a 867 the first parent is shown when `--first-parent` option is given;
f98fd436
MG
868 in that case, the output represents the changes the merge
869 brought _into_ the then-current branch.
870
871-r::
f98fd436
MG
872 Show recursive diffs.
873
874-t::
4528aa1a 875 Show the tree objects in the diff output. This implies `-r`.
f98fd436 876endif::git-rev-list[]