doc/rev-list-options: clarify "commit@{Nth}" for "-g" option
[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
2b68222d 255taken from the reflog. By default, `ref@{Nth}` notation is
fdcf39e5 256used in the output. When the starting commit is specified as
2b68222d 257`ref@{now}`, output also uses `ref@{timestamp}` notation
4528aa1a 258instead. Under `--pretty=oneline`, the commit message is
fdcf39e5 259prefixed with this information on the same line.
4528aa1a 260This option cannot be combined with `--reverse`.
fdcf39e5
MV
261See also linkgit:git-reflog[1].
262
263--merge::
fdcf39e5
MV
264 After a failed merge, show refs that touch files having a
265 conflict and don't exist on all heads to merge.
266
267--boundary::
e32db66d
KB
268 Output excluded boundary commits. Boundary commits are
269 prefixed with `-`.
fdcf39e5 270
aa32939f
VM
271ifdef::git-rev-list[]
272--use-bitmap-index::
273
274 Try to speed up the traversal using the pack bitmap index (if
275 one is available). Note that when traversing with `--objects`,
276 trees and blobs will not have their associated path printed.
277endif::git-rev-list[]
278
70d9895e
TR
279--
280
281History Simplification
282~~~~~~~~~~~~~~~~~~~~~~
283
7bc2508b
SB
284Sometimes you are only interested in parts of the history, for example the
285commits modifying a particular <path>. But there are two parts of
286'History Simplification', one part is selecting the commits and the other
287is how to do it, as there are various strategies to simplify the history.
288
289The following options select the commits to be shown:
290
291<paths>::
7bc2508b
SB
292 Commits modifying the given <paths> are selected.
293
294--simplify-by-decoration::
7bc2508b
SB
295 Commits that are referred by some branch or tag are selected.
296
297Note that extra commits can be shown to give a meaningful history.
298
299The following options affect the way the simplification is performed:
300
301Default mode::
7bc2508b
SB
302 Simplifies the history to the simplest history explaining the
303 final state of the tree. Simplest because it prunes some side
304 branches if the end result is the same (i.e. merging branches
305 with the same content)
306
307--full-history::
df6b0cad 308 Same as the default mode, but does not prune some history.
7bc2508b
SB
309
310--dense::
7bc2508b
SB
311 Only the selected commits are shown, plus some to have a
312 meaningful history.
313
314--sparse::
7bc2508b
SB
315 All commits in the simplified history are shown.
316
317--simplify-merges::
4528aa1a 318 Additional option to `--full-history` to remove some needless
7bc2508b
SB
319 merges from the resulting history, as there are no selected
320 commits contributing to this merge.
321
57456ef4 322--ancestry-path::
57456ef4
JH
323 When given a range of commits to display (e.g. 'commit1..commit2'
324 or 'commit2 {caret}commit1'), only display commits that exist
325 directly on the ancestry chain between the 'commit1' and
326 'commit2', i.e. commits that are both descendants of 'commit1',
327 and ancestors of 'commit2'.
328
7bc2508b 329A more detailed explanation follows.
70d9895e
TR
330
331Suppose you specified `foo` as the <paths>. We shall call commits
332that modify `foo` !TREESAME, and the rest TREESAME. (In a diff
333filtered for `foo`, they look different and equal, respectively.)
334
335In the following, we will always refer to the same example history to
336illustrate the differences between simplification settings. We assume
337that you are filtering for a file `foo` in this commit graph:
338-----------------------------------------------------------------------
143f1eaf
KB
339 .-A---M---N---O---P---Q
340 / / / / / /
341 I B C D E Y
342 \ / / / / /
343 `-------------' X
70d9895e 344-----------------------------------------------------------------------
143f1eaf 345The horizontal line of history A---Q is taken to be the first parent of
70d9895e
TR
346each merge. The commits are:
347
348* `I` is the initial commit, in which `foo` exists with contents
4528aa1a 349 ``asdf'', and a file `quux` exists with contents ``quux''. Initial
70d9895e
TR
350 commits are compared to an empty tree, so `I` is !TREESAME.
351
4528aa1a 352* In `A`, `foo` contains just ``foo''.
70d9895e
TR
353
354* `B` contains the same change as `A`. Its merge `M` is trivial and
355 hence TREESAME to all parents.
356
4528aa1a 357* `C` does not change `foo`, but its merge `N` changes it to ``foobar'',
70d9895e
TR
358 so it is not TREESAME to any parent.
359
4528aa1a
JSJ
360* `D` sets `foo` to ``baz''. Its merge `O` combines the strings from
361 `N` and `D` to ``foobarbaz''; i.e., it is not TREESAME to any parent.
70d9895e 362
4528aa1a
JSJ
363* `E` changes `quux` to ``xyzzy'', and its merge `P` combines the
364 strings to ``quux xyzzy''. `P` is TREESAME to `O`, but not to `E`.
70d9895e 365
17b83d71 366* `X` is an independent root commit that added a new file `side`, and `Y`
143f1eaf
KB
367 modified it. `Y` is TREESAME to `X`. Its merge `Q` added `side` to `P`, and
368 `Q` is TREESAME to `P`, but not to `Y`.
369
4528aa1a
JSJ
370`rev-list` walks backwards through history, including or excluding
371commits based on whether `--full-history` and/or parent rewriting
372(via `--parents` or `--children`) are used. The following settings
70d9895e
TR
373are available.
374
375Default mode::
70d9895e 376 Commits are included if they are not TREESAME to any parent
4528aa1a 377 (though this can be changed, see `--sparse` below). If the
70d9895e
TR
378 commit was a merge, and it was TREESAME to one parent, follow
379 only that parent. (Even if there are several TREESAME
380 parents, follow only one of them.) Otherwise, follow all
381 parents.
382+
383This results in:
384+
385-----------------------------------------------------------------------
386 .-A---N---O
f70d0586 387 / / /
70d9895e
TR
388 I---------D
389-----------------------------------------------------------------------
390+
391Note how the rule to only follow the TREESAME parent, if one is
392available, removed `B` from consideration entirely. `C` was
393considered via `N`, but is TREESAME. Root commits are compared to an
394empty tree, so `I` is !TREESAME.
395+
4528aa1a 396Parent/child relations are only visible with `--parents`, but that does
70d9895e
TR
397not affect the commits selected in default mode, so we have shown the
398parent lines.
399
400--full-history without parent rewriting::
70d9895e
TR
401 This mode differs from the default in one point: always follow
402 all parents of a merge, even if it is TREESAME to one of them.
403 Even if more than one side of the merge has commits that are
404 included, this does not imply that the merge itself is! In
405 the example, we get
406+
407-----------------------------------------------------------------------
143f1eaf 408 I A B N D O P Q
70d9895e
TR
409-----------------------------------------------------------------------
410+
d0af663e 411`M` was excluded because it is TREESAME to both parents. `E`,
70d9895e
TR
412`C` and `B` were all walked, but only `B` was !TREESAME, so the others
413do not appear.
414+
415Note that without parent rewriting, it is not really possible to talk
416about the parent/child relationships between the commits, so we show
417them disconnected.
418
419--full-history with parent rewriting::
70d9895e 420 Ordinary commits are only included if they are !TREESAME
4528aa1a 421 (though this can be changed, see `--sparse` below).
70d9895e
TR
422+
423Merges are always included. However, their parent list is rewritten:
424Along each parent, prune away commits that are not included
425themselves. This results in
426+
427-----------------------------------------------------------------------
143f1eaf 428 .-A---M---N---O---P---Q
70d9895e
TR
429 / / / / /
430 I B / D /
431 \ / / / /
432 `-------------'
433-----------------------------------------------------------------------
434+
4528aa1a 435Compare to `--full-history` without rewriting above. Note that `E`
70d9895e
TR
436was pruned away because it is TREESAME, but the parent list of P was
437rewritten to contain `E`'s parent `I`. The same happened for `C` and
143f1eaf 438`N`, and `X`, `Y` and `Q`.
70d9895e
TR
439
440In addition to the above settings, you can change whether TREESAME
441affects inclusion:
442
3240240f 443--dense::
70d9895e
TR
444 Commits that are walked are included if they are not TREESAME
445 to any parent.
446
3240240f 447--sparse::
70d9895e
TR
448 All commits that are walked are included.
449+
4528aa1a 450Note that without `--full-history`, this still simplifies merges: if
70d9895e
TR
451one of the parents is TREESAME, we follow only that one, so the other
452sides of the merge are never walked.
fdcf39e5 453
d266a988 454--simplify-merges::
d266a988 455 First, build a history graph in the same way that
4528aa1a 456 `--full-history` with parent rewriting does (see above).
d266a988
TR
457+
458Then simplify each commit `C` to its replacement `C'` in the final
459history according to the following rules:
460+
461--
462* Set `C'` to `C`.
463+
464* Replace each parent `P` of `C'` with its simplification `P'`. In
143f1eaf
KB
465 the process, drop parents that are ancestors of other parents or that are
466 root commits TREESAME to an empty tree, and remove duplicates, but take care
467 to never drop all parents that we are TREESAME to.
d266a988
TR
468+
469* If after this parent rewriting, `C'` is a root or merge commit (has
470 zero or >1 parents), a boundary commit, or !TREESAME, it remains.
471 Otherwise, it is replaced with its only parent.
472--
473+
474The effect of this is best shown by way of comparing to
4528aa1a 475`--full-history` with parent rewriting. The example turns into:
d266a988
TR
476+
477-----------------------------------------------------------------------
478 .-A---M---N---O
479 / / /
480 I B D
481 \ / /
482 `---------'
483-----------------------------------------------------------------------
484+
19d6eb41 485Note the major differences in `N`, `P`, and `Q` over `--full-history`:
d266a988
TR
486+
487--
488* `N`'s parent list had `I` removed, because it is an ancestor of the
489 other parent `M`. Still, `N` remained because it is !TREESAME.
490+
491* `P`'s parent list similarly had `I` removed. `P` was then
492 removed completely, because it had one parent and is TREESAME.
143f1eaf
KB
493+
494* `Q`'s parent list had `Y` simplified to `X`. `X` was then removed, because it
495 was a TREESAME root. `Q` was then removed completely, because it had one
496 parent and is TREESAME.
d266a988 497--
fdcf39e5 498
57456ef4
JH
499Finally, there is a fifth simplification mode available:
500
501--ancestry-path::
57456ef4 502 Limit the displayed commits to those directly on the ancestry
4528aa1a
JSJ
503 chain between the ``from'' and ``to'' commits in the given commit
504 range. I.e. only display commits that are ancestor of the ``to''
19d6eb41 505 commit and descendants of the ``from'' commit.
57456ef4
JH
506+
507As an example use case, consider the following commit history:
508+
509-----------------------------------------------------------------------
510 D---E-------F
511 / \ \
512 B---C---G---H---I---J
513 / \
514 A-------K---------------L--M
515-----------------------------------------------------------------------
516+
517A regular 'D..M' computes the set of commits that are ancestors of `M`,
518but excludes the ones that are ancestors of `D`. This is useful to see
519what happened to the history leading to `M` since `D`, in the sense
4528aa1a 520that ``what does `M` have that did not exist in `D`''. The result in this
57456ef4
JH
521example would be all the commits, except `A` and `B` (and `D` itself,
522of course).
523+
524When we want to find out what commits in `M` are contaminated with the
525bug introduced by `D` and need fixing, however, we might want to view
526only the subset of 'D..M' that are actually descendants of `D`, i.e.
4528aa1a 527excluding `C` and `K`. This is exactly what the `--ancestry-path`
57456ef4
JH
528option does. Applied to the 'D..M' range, it results in:
529+
530-----------------------------------------------------------------------
531 E-------F
532 \ \
533 G---H---I---J
534 \
535 L--M
536-----------------------------------------------------------------------
537
4528aa1a 538The `--simplify-by-decoration` option allows you to view only the
3fcfd662
NS
539big picture of the topology of the history, by omitting commits
540that are not referenced by tags. Commits are marked as !TREESAME
541(in other words, kept after history simplification rules described
542above) if (1) they are referenced by tags, or (2) they change the
543contents of the paths given on the command line. All other
544commits are marked as TREESAME (subject to be simplified away).
545
fdcf39e5 546ifdef::git-rev-list[]
70d9895e
TR
547Bisection Helpers
548~~~~~~~~~~~~~~~~~
549
fdcf39e5 550--bisect::
4528aa1a
JSJ
551 Limit output to the one commit object which is roughly halfway between
552 included and excluded commits. Note that the bad bisection ref
553 `refs/bisect/bad` is added to the included commits (if it
554 exists) and the good bisection refs `refs/bisect/good-*` are
555 added to the excluded commits (if they exist). Thus, supposing there
556 are no refs in `refs/bisect/`, if
557+
fdcf39e5 558-----------------------------------------------------------------------
6514aa36 559 $ git rev-list --bisect foo ^bar ^baz
fdcf39e5 560-----------------------------------------------------------------------
4528aa1a 561+
fdcf39e5 562outputs 'midpoint', the output of the two commands
4528aa1a 563+
fdcf39e5 564-----------------------------------------------------------------------
6514aa36
CC
565 $ git rev-list foo ^midpoint
566 $ git rev-list midpoint ^bar ^baz
fdcf39e5 567-----------------------------------------------------------------------
4528aa1a 568+
fdcf39e5
MV
569would be of roughly the same length. Finding the change which
570introduces a regression is thus reduced to a binary search: repeatedly
571generate and test new 'midpoint's until the commit chain is of length
f88851c6 572one. Cannot be combined with --first-parent.
fdcf39e5
MV
573
574--bisect-vars::
4528aa1a
JSJ
575 This calculates the same as `--bisect`, except that refs in
576 `refs/bisect/` are not used, and except that this outputs
577 text ready to be eval'ed by the shell. These lines will assign the
578 name of the midpoint revision to the variable `bisect_rev`, and the
579 expected number of commits to be tested after `bisect_rev` is tested
580 to `bisect_nr`, the expected number of commits to be tested if
581 `bisect_rev` turns out to be good to `bisect_good`, the expected
582 number of commits to be tested if `bisect_rev` turns out to be bad to
583 `bisect_bad`, and the number of commits we are bisecting right now to
584 `bisect_all`.
fdcf39e5
MV
585
586--bisect-all::
4528aa1a
JSJ
587 This outputs all the commit objects between the included and excluded
588 commits, ordered by their distance to the included and excluded
589 commits. Refs in `refs/bisect/` are not used. The farthest
590 from them is displayed first. (This is the only one displayed by
591 `--bisect`.)
3d2d4f96 592+
fdcf39e5
MV
593This is useful because it makes it easy to choose a good commit to
594test when you want to avoid to test some of them for some reason (they
595may not compile for example).
3d2d4f96 596+
fdcf39e5
MV
597This option can be used along with `--bisect-vars`, in this case,
598after all the sorted commit objects, there will be the same text as if
599`--bisect-vars` had been used alone.
600endif::git-rev-list[]
601
fdcf39e5
MV
602
603Commit Ordering
604~~~~~~~~~~~~~~~
605
606By default, the commits are shown in reverse chronological order.
607
3f0350cc
JH
608--date-order::
609 Show no parents before all of its children are shown, but
610 otherwise show commits in the commit timestamp order.
fdcf39e5 611
81c6b38b
JH
612--author-date-order::
613 Show no parents before all of its children are shown, but
614 otherwise show commits in the author timestamp order.
615
3f0350cc
JH
616--topo-order::
617 Show no parents before all of its children are shown, and
618 avoid showing commits on multiple lines of history
619 intermixed.
620+
621For example, in a commit history like this:
622+
623----------------------------------------------------------------
fdcf39e5 624
3f0350cc
JH
625 ---1----2----4----7
626 \ \
627 3----5----6----8---
fdcf39e5 628
3f0350cc
JH
629----------------------------------------------------------------
630+
631where the numbers denote the order of commit timestamps, `git
632rev-list` and friends with `--date-order` show the commits in the
633timestamp order: 8 7 6 5 4 3 2 1.
634+
635With `--topo-order`, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5
6363 1); some older commits are shown before newer ones in order to
637avoid showing the commits from two parallel development track mixed
638together.
fdcf39e5
MV
639
640--reverse::
fdcf39e5 641 Output the commits in reverse order.
4528aa1a 642 Cannot be combined with `--walk-reflogs`.
fdcf39e5
MV
643
644Object Traversal
645~~~~~~~~~~~~~~~~
646
2de9b711 647These options are mostly targeted for packing of Git repositories.
fdcf39e5 648
3cab02de 649ifdef::git-rev-list[]
fdcf39e5 650--objects::
fdcf39e5 651 Print the object IDs of any object referenced by the listed
4528aa1a 652 commits. `--objects foo ^bar` thus means ``send me
fdcf39e5 653 all object IDs which I need to download if I have the commit
4528aa1a 654 object _bar_ but not _foo_''.
fdcf39e5
MV
655
656--objects-edge::
4528aa1a
JSJ
657 Similar to `--objects`, but also print the IDs of excluded
658 commits prefixed with a ``-'' character. This is used by
8297643f 659 linkgit:git-pack-objects[1] to build a ``thin'' pack, which records
fdcf39e5
MV
660 objects in deltified form based on objects contained in these
661 excluded commits to reduce network traffic.
662
1684c1b2 663--objects-edge-aggressive::
664 Similar to `--objects-edge`, but it tries harder to find excluded
2dacf26d 665 commits at the cost of increased time. This is used instead of
666 `--objects-edge` to build ``thin'' packs for shallow repositories.
1684c1b2 667
3cab02de
JH
668--indexed-objects::
669 Pretend as if all trees and blobs used by the index are listed
670 on the command line. Note that you probably want to use
671 `--objects`, too.
672
fdcf39e5 673--unpacked::
4528aa1a 674 Only useful with `--objects`; print the object IDs that are not
fdcf39e5 675 in packs.
3cab02de 676endif::git-rev-list[]
fdcf39e5 677
ca92e59e 678--no-walk[=(sorted|unsorted)]::
ca92e59e
MZ
679 Only show the given commits, but do not traverse their ancestors.
680 This has no effect if a range is specified. If the argument
19d6eb41 681 `unsorted` is given, the commits are shown in the order they were
4528aa1a 682 given on the command line. Otherwise (if `sorted` or no argument
19d6eb41 683 was given), the commits are shown in reverse chronological order
ca92e59e 684 by commit time.
695985f4 685 Cannot be combined with `--graph`.
fdcf39e5
MV
686
687--do-walk::
4528aa1a 688 Overrides a previous `--no-walk`.
f98fd436
MG
689
690Commit Formatting
691~~~~~~~~~~~~~~~~~
692
693ifdef::git-rev-list[]
694Using these options, linkgit:git-rev-list[1] will act similar to the
695more specialized family of commit log tools: linkgit:git-log[1],
696linkgit:git-show[1], and linkgit:git-whatchanged[1]
697endif::git-rev-list[]
698
699include::pretty-options.txt[]
700
701--relative-date::
f98fd436
MG
702 Synonym for `--date=relative`.
703
4b1c5e1d 704--date=<format>::
f98fd436 705 Only takes effect for dates shown in human-readable format, such
4528aa1a 706 as when using `--pretty`. `log.date` config variable sets a default
add00ba2
JK
707 value for the log command's `--date` option. By default, dates
708 are shown in the original time zone (either committer's or
709 author's). If `-local` is appended to the format (e.g.,
710 `iso-local`), the user's local time zone is used instead.
f98fd436
MG
711+
712`--date=relative` shows dates relative to the current time,
add00ba2
JK
713e.g. ``2 hours ago''. The `-local` option cannot be used with
714`--raw` or `--relative`.
f98fd436 715+
add00ba2 716`--date=local` is an alias for `--date=default-local`.
f98fd436 717+
466fb674
BB
718`--date=iso` (or `--date=iso8601`) shows timestamps in a ISO 8601-like format.
719The differences to the strict ISO 8601 format are:
720
721 - a space instead of the `T` date/time delimiter
722 - a space between time and time zone
723 - no colon between hours and minutes of the time zone
724
725+
726`--date=iso-strict` (or `--date=iso8601-strict`) shows timestamps in strict
727ISO 8601 format.
f98fd436
MG
728+
729`--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822
19d6eb41 730format, often found in email messages.
f98fd436 731+
19d6eb41 732`--date=short` shows only the date, but not the time, in `YYYY-MM-DD` format.
f98fd436 733+
2de9b711 734`--date=raw` shows the date in the internal raw Git format `%s %z` format.
f98fd436 735+
aa1462cc
JK
736`--date=format:...` feeds the format `...` to your system `strftime`.
737Use `--date=format:%c` to show the date in your system locale's
738preferred format. See the `strftime` manual for a complete list of
add00ba2
JK
739format placeholders. When using `-local`, the correct syntax is
740`--date=format-local:...`.
aa1462cc 741+
add00ba2
JK
742`--date=default` is the default format, and is similar to
743`--date=rfc2822`, with a few exceptions:
744
745 - there is no comma after the day-of-week
746
747 - the time zone is omitted when the local time zone is used
f98fd436
MG
748
749ifdef::git-rev-list[]
750--header::
f98fd436
MG
751 Print the contents of the commit in raw-format; each record is
752 separated with a NUL character.
753endif::git-rev-list[]
754
755--parents::
f98fd436
MG
756 Print also the parents of the commit (in the form "commit parent...").
757 Also enables parent rewriting, see 'History Simplification' below.
758
759--children::
f98fd436
MG
760 Print also the children of the commit (in the form "commit child...").
761 Also enables parent rewriting, see 'History Simplification' below.
762
763ifdef::git-rev-list[]
764--timestamp::
765 Print the raw commit timestamp.
766endif::git-rev-list[]
767
768--left-right::
f98fd436
MG
769 Mark which side of a symmetric diff a commit is reachable from.
770 Commits from the left side are prefixed with `<` and those from
771 the right with `>`. If combined with `--boundary`, those
772 commits are prefixed with `-`.
773+
774For example, if you have this topology:
775+
776-----------------------------------------------------------------------
777 y---b---b branch B
778 / \ /
779 / .
780 / / \
781 o---x---a---a branch A
782-----------------------------------------------------------------------
783+
784you would get an output like this:
785+
786-----------------------------------------------------------------------
787 $ git rev-list --left-right --boundary --pretty=oneline A...B
788
789 >bbbbbbb... 3rd on b
790 >bbbbbbb... 2nd on b
791 <aaaaaaa... 3rd on a
792 <aaaaaaa... 2nd on a
793 -yyyyyyy... 1st on b
794 -xxxxxxx... 1st on a
795-----------------------------------------------------------------------
796
797--graph::
f98fd436
MG
798 Draw a text-based graphical representation of the commit history
799 on the left hand side of the output. This may cause extra lines
800 to be printed in between commits, in order for the graph history
801 to be drawn properly.
695985f4 802 Cannot be combined with `--no-walk`.
f98fd436
MG
803+
804This enables parent rewriting, see 'History Simplification' below.
805+
4528aa1a
JSJ
806This implies the `--topo-order` option by default, but the
807`--date-order` option may also be specified.
f98fd436 808
1b32dece
NTND
809--show-linear-break[=<barrier>]::
810 When --graph is not used, all history branches are flattened
811 which can make it hard to see that the two consecutive commits
812 do not belong to a linear branch. This option puts a barrier
813 in between them in that case. If `<barrier>` is specified, it
814 is the string that will be shown instead of the default one.
815
f98fd436
MG
816ifdef::git-rev-list[]
817--count::
818 Print a number stating how many commits would have been
819 listed, and suppress all other output. When used together
4528aa1a 820 with `--left-right`, instead print the counts for left and
b388e14b 821 right commits, separated by a tab. When used together with
4528aa1a 822 `--cherry-mark`, omit patch equivalent commits from these
b388e14b
MG
823 counts and print the count for equivalent commits separated
824 by a tab.
f98fd436
MG
825endif::git-rev-list[]
826
f98fd436
MG
827ifndef::git-rev-list[]
828Diff Formatting
829~~~~~~~~~~~~~~~
830
19d6eb41 831Listed below are options that control the formatting of diff output.
f98fd436
MG
832Some of them are specific to linkgit:git-rev-list[1], however other diff
833options may be given. See linkgit:git-diff-files[1] for more options.
834
835-c::
f98fd436
MG
836 With this option, diff output for a merge commit
837 shows the differences from each of the parents to the merge result
838 simultaneously instead of showing pairwise diff between a parent
839 and the result one at a time. Furthermore, it lists only files
840 which were modified from all parents.
841
842--cc::
4528aa1a 843 This flag implies the `-c` option and further compresses the
f98fd436
MG
844 patch output by omitting uninteresting hunks whose contents in
845 the parents have only two variants and the merge result picks
846 one of them without modification.
847
848-m::
f98fd436
MG
849 This flag makes the merge commits show the full diff like
850 regular commits; for each merge parent, a separate log entry
851 and diff is generated. An exception is that only diff against
4528aa1a 852 the first parent is shown when `--first-parent` option is given;
f98fd436
MG
853 in that case, the output represents the changes the merge
854 brought _into_ the then-current branch.
855
856-r::
f98fd436
MG
857 Show recursive diffs.
858
859-t::
4528aa1a 860 Show the tree objects in the diff output. This implies `-r`.
f98fd436 861endif::git-rev-list[]