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