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