1GIT-REV-LIST(1) Git Manual GIT-REV-LIST(1)
2
6 git-rev-list - Lists commit objects in reverse chronological order
7
9 git rev-list [ --max-count=<number> ]
10 [ --skip=<number> ]
11 [ --max-age=<timestamp> ]
12 [ --min-age=<timestamp> ]
13 [ --sparse ]
14 [ --merges ]
15 [ --no-merges ]
16 [ --min-parents=<number> ]
17 [ --no-min-parents ]
18 [ --max-parents=<number> ]
19 [ --no-max-parents ]
20 [ --first-parent ]
21 [ --remove-empty ]
22 [ --full-history ]
23 [ --not ]
24 [ --all ]
25 [ --branches[=<pattern>] ]
26 [ --tags[=<pattern>] ]
27 [ --remotes[=<pattern>] ]
28 [ --glob=<glob-pattern> ]
29 [ --ignore-missing ]
30 [ --stdin ]
31 [ --quiet ]
32 [ --topo-order ]
33 [ --parents ]
34 [ --timestamp ]
35 [ --left-right ]
36 [ --left-only ]
37 [ --right-only ]
38 [ --cherry-mark ]
39 [ --cherry-pick ]
40 [ --encoding=<encoding> ]
41 [ --(author|committer|grep)=<pattern> ]
42 [ --regexp-ignore-case | -i ]
43 [ --extended-regexp | -E ]
44 [ --fixed-strings | -F ]
45 [ --date=<format>]
46 [ [ --objects | --objects-edge | --objects-edge-aggressive ]
47 [ --unpacked ]
48 [ --filter=<filter-spec> [ --filter-print-omitted ] ] ]
49 [ --missing=<missing-action> ]
50 [ --pretty | --header ]
51 [ --bisect ]
52 [ --bisect-vars ]
53 [ --bisect-all ]
54 [ --merge ]
55 [ --reverse ]
56 [ --walk-reflogs ]
57 [ --no-walk ] [ --do-walk ]
58 [ --count ]
59 [ --use-bitmap-index ]
60 <commit>... [ -- <paths>... ]
61
64 List commits that are reachable by following the parent links from the
65 given commit(s), but exclude commits that are reachable from the one(s)
66 given with a ^ in front of them. The output is given in reverse
67 chronological order by default.
68 You can think of this as a set operation. Commits given on the command
70 line form a set of commits that are reachable from any of them, and
71 then commits reachable from any of the ones given with ^ in front are
72 subtracted from that set. The remaining commits are what comes out in
73 the command’s output. Various other options and paths parameters can be
74 used to further limit the result.
75 Thus, the following command:
77 $ git rev-list foo bar ^baz
79 means "list all the commits which are reachable from foo or bar, but
82 not from baz".
83 A special notation "<commit1>..<commit2>" can be used as a short-hand
85 for "^'<commit1>' <commit2>". For example, either of the following may
86 be used interchangeably:
87 $ git rev-list origin..HEAD
89 $ git rev-list HEAD ^origin
90 Another special notation is "<commit1>...<commit2>" which is useful for
93 merges. The resulting set of commits is the symmetric difference
94 between the two operands. The following two commands are equivalent:
95 $ git rev-list A B --not $(git merge-base --all A B)
97 $ git rev-list A...B
98 rev-list is a very essential Git command, since it provides the ability
101 to build and traverse commit ancestry graphs. For this reason, it has a
102 lot of different options that enables it to be used by commands as
103 different as git bisect and git repack.
104
106 Commit Limiting
107 Besides specifying a range of commits that should be listed using the
108 special notations explained in the description, additional commit
109 limiting may be applied.
110 Using more options generally further limits the output (e.g.
112 --since=<date1> limits to commits newer than <date1>, and using it with
113 --grep=<pattern> further limits to commits whose log message has a line
114 that matches <pattern>), unless otherwise noted.
115 Note that these are applied before commit ordering and formatting
117 options, such as --reverse.
118 -<number>, -n <number>, --max-count=<number>
120 Limit the number of commits to output.
121 --skip=<number>
123 Skip number commits before starting to show the commit output.
124 --since=<date>, --after=<date>
126 Show commits more recent than a specific date.
127 --until=<date>, --before=<date>
129 Show commits older than a specific date.
130 --max-age=<timestamp>, --min-age=<timestamp>
132 Limit the commits output to specified time range.
133 --author=<pattern>, --committer=<pattern>
135 Limit the commits output to ones with author/committer header lines
136 that match the specified pattern (regular expression). With more
137 than one --author=<pattern>, commits whose author matches any of
138 the given patterns are chosen (similarly for multiple
139 --committer=<pattern>).
140 --grep-reflog=<pattern>
142 Limit the commits output to ones with reflog entries that match the
143 specified pattern (regular expression). With more than one
144 --grep-reflog, commits whose reflog message matches any of the
145 given patterns are chosen. It is an error to use this option unless
146 --walk-reflogs is in use.
147 --grep=<pattern>
149 Limit the commits output to ones with log message that matches the
150 specified pattern (regular expression). With more than one
151 --grep=<pattern>, commits whose message matches any of the given
152 patterns are chosen (but see --all-match).
153 --all-match
155 Limit the commits output to ones that match all given --grep,
156 instead of ones that match at least one.
157 --invert-grep
159 Limit the commits output to ones with log message that do not match
160 the pattern specified with --grep=<pattern>.
161 -i, --regexp-ignore-case
163 Match the regular expression limiting patterns without regard to
164 letter case.
165 --basic-regexp
167 Consider the limiting patterns to be basic regular expressions;
168 this is the default.
169 -E, --extended-regexp
171 Consider the limiting patterns to be extended regular expressions
172 instead of the default basic regular expressions.
173 -F, --fixed-strings
175 Consider the limiting patterns to be fixed strings (don’t interpret
176 pattern as a regular expression).
177 -P, --perl-regexp
179 Consider the limiting patterns to be Perl-compatible regular
180 expressions.
181 Support for these types of regular expressions is an optional
183 compile-time dependency. If Git wasn’t compiled with support for
184 them providing this option will cause it to die.
185 --remove-empty
187 Stop when a given path disappears from the tree.
188 --merges
190 Print only merge commits. This is exactly the same as
191 --min-parents=2.
192 --no-merges
194 Do not print commits with more than one parent. This is exactly the
195 same as --max-parents=1.
196 --min-parents=<number>, --max-parents=<number>, --no-min-parents,
198 --no-max-parents
199 Show only commits which have at least (or at most) that many parent
200 commits. In particular, --max-parents=1 is the same as --no-merges,
201 --min-parents=2 is the same as --merges. --max-parents=0 gives all
202 root commits and --min-parents=3 all octopus merges.
203 --no-min-parents and --no-max-parents reset these limits (to no
205 limit) again. Equivalent forms are --min-parents=0 (any commit has
206 0 or more parents) and --max-parents=-1 (negative numbers denote no
207 upper limit).
208 --first-parent
210 Follow only the first parent commit upon seeing a merge commit.
211 This option can give a better overview when viewing the evolution
212 of a particular topic branch, because merges into a topic branch
213 tend to be only about adjusting to updated upstream from time to
214 time, and this option allows you to ignore the individual commits
215 brought in to your history by such a merge. Cannot be combined with
216 --bisect.
217 --not
219 Reverses the meaning of the ^ prefix (or lack thereof) for all
220 following revision specifiers, up to the next --not.
221 --all
223 Pretend as if all the refs in refs/, along with HEAD, are listed on
224 the command line as <commit>.
225 --branches[=<pattern>]
227 Pretend as if all the refs in refs/heads are listed on the command
228 line as <commit>. If <pattern> is given, limit branches to ones
229 matching given shell glob. If pattern lacks ?, *, or [, /* at the
230 end is implied.
231 --tags[=<pattern>]
233 Pretend as if all the refs in refs/tags are listed on the command
234 line as <commit>. If <pattern> is given, limit tags to ones
235 matching given shell glob. If pattern lacks ?, *, or [, /* at the
236 end is implied.
237 --remotes[=<pattern>]
239 Pretend as if all the refs in refs/remotes are listed on the
240 command line as <commit>. If <pattern> is given, limit
241 remote-tracking branches to ones matching given shell glob. If
242 pattern lacks ?, *, or [, /* at the end is implied.
243 --glob=<glob-pattern>
245 Pretend as if all the refs matching shell glob <glob-pattern> are
246 listed on the command line as <commit>. Leading refs/, is
247 automatically prepended if missing. If pattern lacks ?, *, or [, /*
248 at the end is implied.
249 --exclude=<glob-pattern>
251 Do not include refs matching <glob-pattern> that the next --all,
252 --branches, --tags, --remotes, or --glob would otherwise consider.
253 Repetitions of this option accumulate exclusion patterns up to the
254 next --all, --branches, --tags, --remotes, or --glob option (other
255 options or arguments do not clear accumulated patterns).
256 The patterns given should not begin with refs/heads, refs/tags, or
258 refs/remotes when applied to --branches, --tags, or --remotes,
259 respectively, and they must begin with refs/ when applied to --glob
260 or --all. If a trailing /* is intended, it must be given
261 explicitly.
262 --reflog
264 Pretend as if all objects mentioned by reflogs are listed on the
265 command line as <commit>.
266 --single-worktree
268 By default, all working trees will be examined by the following
269 options when there are more than one (see git-worktree(1)): --all,
270 --reflog and --indexed-objects. This option forces them to examine
271 the current working tree only.
272 --ignore-missing
274 Upon seeing an invalid object name in the input, pretend as if the
275 bad input was not given.
276 --stdin
278 In addition to the <commit> listed on the command line, read them
279 from the standard input. If a -- separator is seen, stop reading
280 commits and start reading paths to limit the result.
281 --quiet
283 Don’t print anything to standard output. This form is primarily
284 meant to allow the caller to test the exit status to see if a range
285 of objects is fully connected (or not). It is faster than
286 redirecting stdout to /dev/null as the output does not have to be
287 formatted.
288 --cherry-mark
290 Like --cherry-pick (see below) but mark equivalent commits with =
291 rather than omitting them, and inequivalent ones with +.
292 --cherry-pick
294 Omit any commit that introduces the same change as another commit
295 on the “other side” when the set of commits are limited with
296 symmetric difference.
297 For example, if you have two branches, A and B, a usual way to list
299 all commits on only one side of them is with --left-right (see the
300 example below in the description of the --left-right option).
301 However, it shows the commits that were cherry-picked from the
302 other branch (for example, “3rd on b” may be cherry-picked from
303 branch A). With this option, such pairs of commits are excluded
304 from the output.
305 --left-only, --right-only
307 List only commits on the respective side of a symmetric difference,
308 i.e. only those which would be marked < resp. > by --left-right.
309 For example, --cherry-pick --right-only A...B omits those commits
311 from B which are in A or are patch-equivalent to a commit in A. In
312 other words, this lists the + commits from git cherry A B. More
313 precisely, --cherry-pick --right-only --no-merges gives the exact
314 list.
315 --cherry
317 A synonym for --right-only --cherry-mark --no-merges; useful to
318 limit the output to the commits on our side and mark those that
319 have been applied to the other side of a forked history with git
320 log --cherry upstream...mybranch, similar to git cherry upstream
321 mybranch.
322 -g, --walk-reflogs
324 Instead of walking the commit ancestry chain, walk reflog entries
325 from the most recent one to older ones. When this option is used
326 you cannot specify commits to exclude (that is, ^commit,
327 commit1..commit2, and commit1...commit2 notations cannot be used).
328 With --pretty format other than oneline (for obvious reasons), this
330 causes the output to have two extra lines of information taken from
331 the reflog. The reflog designator in the output may be shown as
332 ref@{Nth} (where Nth is the reverse-chronological index in the
333 reflog) or as ref@{timestamp} (with the timestamp for that entry),
334 depending on a few rules:
335 1. If the starting point is specified as ref@{Nth}, show the index
337 format.
338 2. If the starting point was specified as ref@{now}, show the
340 timestamp format.
341 3. If neither was used, but --date was given on the command line,
343 show the timestamp in the format requested by --date.
344 4. Otherwise, show the index format.
346 Under --pretty=oneline, the commit message is prefixed with this
348 information on the same line. This option cannot be combined with
349 --reverse. See also git-reflog(1).
350 --merge
352 After a failed merge, show refs that touch files having a conflict
353 and don’t exist on all heads to merge.
354 --boundary
356 Output excluded boundary commits. Boundary commits are prefixed
357 with -.
358 --use-bitmap-index
360 Try to speed up the traversal using the pack bitmap index (if one
361 is available). Note that when traversing with --objects, trees and
362 blobs will not have their associated path printed.
363 --progress=<header>
365 Show progress reports on stderr as objects are considered. The
366 <header> text will be printed with each progress update.
367 History Simplification
369 Sometimes you are only interested in parts of the history, for example
370 the commits modifying a particular <path>. But there are two parts of
371 History Simplification, one part is selecting the commits and the other
372 is how to do it, as there are various strategies to simplify the
373 history.
374 The following options select the commits to be shown:
376 <paths>
378 Commits modifying the given <paths> are selected.
379 --simplify-by-decoration
381 Commits that are referred by some branch or tag are selected.
382 Note that extra commits can be shown to give a meaningful history.
384 The following options affect the way the simplification is performed:
386 Default mode
388 Simplifies the history to the simplest history explaining the final
389 state of the tree. Simplest because it prunes some side branches if
390 the end result is the same (i.e. merging branches with the same
391 content)
392 --full-history
394 Same as the default mode, but does not prune some history.
395 --dense
397 Only the selected commits are shown, plus some to have a meaningful
398 history.
399 --sparse
401 All commits in the simplified history are shown.
402 --simplify-merges
404 Additional option to --full-history to remove some needless merges
405 from the resulting history, as there are no selected commits
406 contributing to this merge.
407 --ancestry-path
409 When given a range of commits to display (e.g. commit1..commit2 or
410 commit2 ^commit1), only display commits that exist directly on the
411 ancestry chain between the commit1 and commit2, i.e. commits that
412 are both descendants of commit1, and ancestors of commit2.
413 A more detailed explanation follows.
415 Suppose you specified foo as the <paths>. We shall call commits that
417 modify foo !TREESAME, and the rest TREESAME. (In a diff filtered for
418 foo, they look different and equal, respectively.)
419 In the following, we will always refer to the same example history to
421 illustrate the differences between simplification settings. We assume
422 that you are filtering for a file foo in this commit graph:
423 .-A---M---N---O---P---Q
425 / / / / / /
426 I B C D E Y
427 \ / / / / /
428 `-------------' X
429 The horizontal line of history A---Q is taken to be the first parent of
432 each merge. The commits are:
433 · I is the initial commit, in which foo exists with contents “asdf”,
435 and a file quux exists with contents “quux”. Initial commits are
436 compared to an empty tree, so I is !TREESAME.
437 · In A, foo contains just “foo”.
439 · B contains the same change as A. Its merge M is trivial and hence
441 TREESAME to all parents.
442 · C does not change foo, but its merge N changes it to “foobar”, so
444 it is not TREESAME to any parent.
445 · D sets foo to “baz”. Its merge O combines the strings from N and D
447 to “foobarbaz”; i.e., it is not TREESAME to any parent.
448 · E changes quux to “xyzzy”, and its merge P combines the strings to
450 “quux xyzzy”. P is TREESAME to O, but not to E.
451 · X is an independent root commit that added a new file side, and Y
453 modified it. Y is TREESAME to X. Its merge Q added side to P, and
454 Q is TREESAME to P, but not to Y.
455 rev-list walks backwards through history, including or excluding
457 commits based on whether --full-history and/or parent rewriting (via
458 --parents or --children) are used. The following settings are
459 available.
460 Default mode
462 Commits are included if they are not TREESAME to any parent (though
463 this can be changed, see --sparse below). If the commit was a
464 merge, and it was TREESAME to one parent, follow only that parent.
465 (Even if there are several TREESAME parents, follow only one of
466 them.) Otherwise, follow all parents.
467 This results in:
469 .-A---N---O
471 / / /
472 I---------D
473 Note how the rule to only follow the TREESAME parent, if one is
475 available, removed B from consideration entirely. C was considered
476 via N, but is TREESAME. Root commits are compared to an empty tree,
477 so I is !TREESAME.
478 Parent/child relations are only visible with --parents, but that
480 does not affect the commits selected in default mode, so we have
481 shown the parent lines.
482 --full-history without parent rewriting
484 This mode differs from the default in one point: always follow all
485 parents of a merge, even if it is TREESAME to one of them. Even if
486 more than one side of the merge has commits that are included, this
487 does not imply that the merge itself is! In the example, we get
488 I A B N D O P Q
490 M was excluded because it is TREESAME to both parents. E, C and B
492 were all walked, but only B was !TREESAME, so the others do not
493 appear.
494 Note that without parent rewriting, it is not really possible to
496 talk about the parent/child relationships between the commits, so
497 we show them disconnected.
498 --full-history with parent rewriting
500 Ordinary commits are only included if they are !TREESAME (though
501 this can be changed, see --sparse below).
502 Merges are always included. However, their parent list is
504 rewritten: Along each parent, prune away commits that are not
505 included themselves. This results in
506 .-A---M---N---O---P---Q
508 / / / / /
509 I B / D /
510 \ / / / /
511 `-------------'
512 Compare to --full-history without rewriting above. Note that E was
514 pruned away because it is TREESAME, but the parent list of P was
515 rewritten to contain E's parent I. The same happened for C and N,
516 and X, Y and Q.
517 In addition to the above settings, you can change whether TREESAME
519 affects inclusion:
520 --dense
522 Commits that are walked are included if they are not TREESAME to
523 any parent.
524 --sparse
526 All commits that are walked are included.
527 Note that without --full-history, this still simplifies merges: if
529 one of the parents is TREESAME, we follow only that one, so the
530 other sides of the merge are never walked.
531 --simplify-merges
533 First, build a history graph in the same way that --full-history
534 with parent rewriting does (see above).
535 Then simplify each commit C to its replacement C' in the final
537 history according to the following rules:
538 · Set C' to C.
540 · Replace each parent P of C' with its simplification P'. In the
542 process, drop parents that are ancestors of other parents or
543 that are root commits TREESAME to an empty tree, and remove
544 duplicates, but take care to never drop all parents that we are
545 TREESAME to.
546 · If after this parent rewriting, C' is a root or merge commit
548 (has zero or >1 parents), a boundary commit, or !TREESAME, it
549 remains. Otherwise, it is replaced with its only parent.
550 The effect of this is best shown by way of comparing to
552 --full-history with parent rewriting. The example turns into:
553 .-A---M---N---O
555 / / /
556 I B D
557 \ / /
558 `---------'
559 Note the major differences in N, P, and Q over --full-history:
561 · N's parent list had I removed, because it is an ancestor of the
563 other parent M. Still, N remained because it is !TREESAME.
564 · P's parent list similarly had I removed. P was then removed
566 completely, because it had one parent and is TREESAME.
567 · Q's parent list had Y simplified to X. X was then removed,
569 because it was a TREESAME root. Q was then removed completely,
570 because it had one parent and is TREESAME.
571 Finally, there is a fifth simplification mode available:
573 --ancestry-path
575 Limit the displayed commits to those directly on the ancestry chain
576 between the “from” and “to” commits in the given commit range. I.e.
577 only display commits that are ancestor of the “to” commit and
578 descendants of the “from” commit.
579 As an example use case, consider the following commit history:
581 D---E-------F
583 / \ \
584 B---C---G---H---I---J
585 / \
586 A-------K---------------L--M
587 A regular D..M computes the set of commits that are ancestors of M,
589 but excludes the ones that are ancestors of D. This is useful to
590 see what happened to the history leading to M since D, in the sense
591 that “what does M have that did not exist in D”. The result in this
592 example would be all the commits, except A and B (and D itself, of
593 course).
594 When we want to find out what commits in M are contaminated with
596 the bug introduced by D and need fixing, however, we might want to
597 view only the subset of D..M that are actually descendants of D,
598 i.e. excluding C and K. This is exactly what the --ancestry-path
599 option does. Applied to the D..M range, it results in:
600 E-------F
602 \ \
603 G---H---I---J
604 \
605 L--M
606 The --simplify-by-decoration option allows you to view only the big
609 picture of the topology of the history, by omitting commits that are
610 not referenced by tags. Commits are marked as !TREESAME (in other
611 words, kept after history simplification rules described above) if (1)
612 they are referenced by tags, or (2) they change the contents of the
613 paths given on the command line. All other commits are marked as
614 TREESAME (subject to be simplified away).
615 Bisection Helpers
617 --bisect
618 Limit output to the one commit object which is roughly halfway
619 between included and excluded commits. Note that the bad bisection
620 ref refs/bisect/bad is added to the included commits (if it exists)
621 and the good bisection refs refs/bisect/good-* are added to the
622 excluded commits (if they exist). Thus, supposing there are no refs
623 in refs/bisect/, if
624 $ git rev-list --bisect foo ^bar ^baz
626 outputs midpoint, the output of the two commands
628 $ git rev-list foo ^midpoint
630 $ git rev-list midpoint ^bar ^baz
631 would be of roughly the same length. Finding the change which
633 introduces a regression is thus reduced to a binary search:
634 repeatedly generate and test new 'midpoint’s until the commit chain
635 is of length one. Cannot be combined with --first-parent.
636 --bisect-vars
638 This calculates the same as --bisect, except that refs in
639 refs/bisect/ are not used, and except that this outputs text ready
640 to be eval’ed by the shell. These lines will assign the name of the
641 midpoint revision to the variable bisect_rev, and the expected
642 number of commits to be tested after bisect_rev is tested to
643 bisect_nr, the expected number of commits to be tested if
644 bisect_rev turns out to be good to bisect_good, the expected number
645 of commits to be tested if bisect_rev turns out to be bad to
646 bisect_bad, and the number of commits we are bisecting right now to
647 bisect_all.
648 --bisect-all
650 This outputs all the commit objects between the included and
651 excluded commits, ordered by their distance to the included and
652 excluded commits. Refs in refs/bisect/ are not used. The farthest
653 from them is displayed first. (This is the only one displayed by
654 --bisect.)
655 This is useful because it makes it easy to choose a good commit to
657 test when you want to avoid to test some of them for some reason
658 (they may not compile for example).
659 This option can be used along with --bisect-vars, in this case,
661 after all the sorted commit objects, there will be the same text as
662 if --bisect-vars had been used alone.
663 Commit Ordering
665 By default, the commits are shown in reverse chronological order.
666 --date-order
668 Show no parents before all of its children are shown, but otherwise
669 show commits in the commit timestamp order.
670 --author-date-order
672 Show no parents before all of its children are shown, but otherwise
673 show commits in the author timestamp order.
674 --topo-order
676 Show no parents before all of its children are shown, and avoid
677 showing commits on multiple lines of history intermixed.
678 For example, in a commit history like this:
680 ---1----2----4----7
682 \ \
683 3----5----6----8---
684 where the numbers denote the order of commit timestamps, git
686 rev-list and friends with --date-order show the commits in the
687 timestamp order: 8 7 6 5 4 3 2 1.
688 With --topo-order, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5
690 3 1); some older commits are shown before newer ones in order to
691 avoid showing the commits from two parallel development track mixed
692 together.
693 --reverse
695 Output the commits chosen to be shown (see Commit Limiting section
696 above) in reverse order. Cannot be combined with --walk-reflogs.
697 Object Traversal
699 These options are mostly targeted for packing of Git repositories.
700 --objects
702 Print the object IDs of any object referenced by the listed
703 commits. --objects foo ^bar thus means “send me all object IDs
704 which I need to download if I have the commit object bar but not
705 foo”.
706 --in-commit-order
708 Print tree and blob ids in order of the commits. The tree and blob
709 ids are printed after they are first referenced by a commit.
710 --objects-edge
712 Similar to --objects, but also print the IDs of excluded commits
713 prefixed with a “-” character. This is used by git-pack-objects(1)
714 to build a “thin” pack, which records objects in deltified form
715 based on objects contained in these excluded commits to reduce
716 network traffic.
717 --objects-edge-aggressive
719 Similar to --objects-edge, but it tries harder to find excluded
720 commits at the cost of increased time. This is used instead of
721 --objects-edge to build “thin” packs for shallow repositories.
722 --indexed-objects
724 Pretend as if all trees and blobs used by the index are listed on
725 the command line. Note that you probably want to use --objects,
726 too.
727 --unpacked
729 Only useful with --objects; print the object IDs that are not in
730 packs.
731 --filter=<filter-spec>
733 Only useful with one of the --objects*; omits objects (usually
734 blobs) from the list of printed objects. The <filter-spec> may be
735 one of the following:
736 The form --filter=blob:none omits all blobs.
738 The form --filter=blob:limit=<n>[kmg] omits blobs larger than n
740 bytes or units. n may be zero. The suffixes k, m, and g can be used
741 to name units in KiB, MiB, or GiB. For example, blob:limit=1k is
742 the same as blob:limit=1024.
743 The form --filter=sparse:oid=<blob-ish> uses a sparse-checkout
745 specification contained in the blob (or blob-expression) <blob-ish>
746 to omit blobs that would not be not required for a sparse checkout
747 on the requested refs.
748 The form --filter=sparse:path=<path> similarly uses a
750 sparse-checkout specification contained in <path>.
751 The form --filter=tree:<depth> omits all blobs and trees whose
753 depth from the root tree is >= <depth> (minimum depth if an object
754 is located at multiple depths in the commits traversed). Currently,
755 only <depth>=0 is supported, which omits all blobs and trees.
756 --no-filter
758 Turn off any previous --filter= argument.
759 --filter-print-omitted
761 Only useful with --filter=; prints a list of the objects omitted by
762 the filter. Object IDs are prefixed with a “~” character.
763 --missing=<missing-action>
765 A debug option to help with future "partial clone" development.
766 This option specifies how missing objects are handled.
767 The form --missing=error requests that rev-list stop with an error
769 if a missing object is encountered. This is the default action.
770 The form --missing=allow-any will allow object traversal to
772 continue if a missing object is encountered. Missing objects will
773 silently be omitted from the results.
774 The form --missing=allow-promisor is like allow-any, but will only
776 allow object traversal to continue for EXPECTED promisor missing
777 objects. Unexpected missing objects will raise an error.
778 The form --missing=print is like allow-any, but will also print a
780 list of the missing objects. Object IDs are prefixed with a “?”
781 character.
782 --exclude-promisor-objects
784 (For internal use only.) Prefilter object traversal at promisor
785 boundary. This is used with partial clone. This is stronger than
786 --missing=allow-promisor because it limits the traversal, rather
787 than just silencing errors about missing objects.
788 --no-walk[=(sorted|unsorted)]
790 Only show the given commits, but do not traverse their ancestors.
791 This has no effect if a range is specified. If the argument
792 unsorted is given, the commits are shown in the order they were
793 given on the command line. Otherwise (if sorted or no argument was
794 given), the commits are shown in reverse chronological order by
795 commit time. Cannot be combined with --graph.
796 --do-walk
798 Overrides a previous --no-walk.
799 Commit Formatting
801 Using these options, git-rev-list(1) will act similar to the more
802 specialized family of commit log tools: git-log(1), git-show(1), and
803 git-whatchanged(1)
804 --pretty[=<format>], --format=<format>
806 Pretty-print the contents of the commit logs in a given format,
807 where <format> can be one of oneline, short, medium, full, fuller,
808 email, raw, format:<string> and tformat:<string>. When <format> is
809 none of the above, and has %placeholder in it, it acts as if
810 --pretty=tformat:<format> were given.
811 See the "PRETTY FORMATS" section for some additional details for
813 each format. When =<format> part is omitted, it defaults to medium.
814 Note: you can specify the default pretty format in the repository
816 configuration (see git-config(1)).
817 --abbrev-commit
819 Instead of showing the full 40-byte hexadecimal commit object name,
820 show only a partial prefix. Non default number of digits can be
821 specified with "--abbrev=<n>" (which also modifies diff output, if
822 it is displayed).
823 This should make "--pretty=oneline" a whole lot more readable for
825 people using 80-column terminals.
826 --no-abbrev-commit
828 Show the full 40-byte hexadecimal commit object name. This negates
829 --abbrev-commit and those options which imply it such as
830 "--oneline". It also overrides the log.abbrevCommit variable.
831 --oneline
833 This is a shorthand for "--pretty=oneline --abbrev-commit" used
834 together.
835 --encoding=<encoding>
837 The commit objects record the encoding used for the log message in
838 their encoding header; this option can be used to tell the command
839 to re-code the commit log message in the encoding preferred by the
840 user. For non plumbing commands this defaults to UTF-8. Note that
841 if an object claims to be encoded in X and we are outputting in X,
842 we will output the object verbatim; this means that invalid
843 sequences in the original commit may be copied to the output.
844 --expand-tabs=<n>, --expand-tabs, --no-expand-tabs
846 Perform a tab expansion (replace each tab with enough spaces to
847 fill to the next display column that is multiple of <n>) in the log
848 message before showing it in the output. --expand-tabs is a
849 short-hand for --expand-tabs=8, and --no-expand-tabs is a
850 short-hand for --expand-tabs=0, which disables tab expansion.
851 By default, tabs are expanded in pretty formats that indent the log
853 message by 4 spaces (i.e. medium, which is the default, full, and
854 fuller).
855 --show-signature
857 Check the validity of a signed commit object by passing the
858 signature to gpg --verify and show the output.
859 --relative-date
861 Synonym for --date=relative.
862 --date=<format>
864 Only takes effect for dates shown in human-readable format, such as
865 when using --pretty. log.date config variable sets a default value
866 for the log command’s --date option. By default, dates are shown in
867 the original time zone (either committer’s or author’s). If -local
868 is appended to the format (e.g., iso-local), the user’s local time
869 zone is used instead.
870 --date=relative shows dates relative to the current time, e.g. “2
872 hours ago”. The -local option has no effect for --date=relative.
873 --date=local is an alias for --date=default-local.
875 --date=iso (or --date=iso8601) shows timestamps in a ISO 8601-like
877 format. The differences to the strict ISO 8601 format are:
878 · a space instead of the T date/time delimiter
880 · a space between time and time zone
882 · no colon between hours and minutes of the time zone
884 --date=iso-strict (or --date=iso8601-strict) shows timestamps in
886 strict ISO 8601 format.
887 --date=rfc (or --date=rfc2822) shows timestamps in RFC 2822 format,
889 often found in email messages.
890 --date=short shows only the date, but not the time, in YYYY-MM-DD
892 format.
893 --date=raw shows the date as seconds since the epoch (1970-01-01
895 00:00:00 UTC), followed by a space, and then the timezone as an
896 offset from UTC (a + or - with four digits; the first two are
897 hours, and the second two are minutes). I.e., as if the timestamp
898 were formatted with strftime("%s %z")). Note that the -local option
899 does not affect the seconds-since-epoch value (which is always
900 measured in UTC), but does switch the accompanying timezone value.
901 --date=unix shows the date as a Unix epoch timestamp (seconds since
903 1970). As with --raw, this is always in UTC and therefore -local
904 has no effect.
905 --date=format:... feeds the format ... to your system strftime,
907 except for %z and %Z, which are handled internally. Use
908 --date=format:%c to show the date in your system locale’s preferred
909 format. See the strftime manual for a complete list of format
910 placeholders. When using -local, the correct syntax is
911 --date=format-local:....
912 --date=default is the default format, and is similar to
914 --date=rfc2822, with a few exceptions:
915 · there is no comma after the day-of-week
917 · the time zone is omitted when the local time zone is used
919 --header
921 Print the contents of the commit in raw-format; each record is
922 separated with a NUL character.
923 --parents
925 Print also the parents of the commit (in the form "commit
926 parent..."). Also enables parent rewriting, see History
927 Simplification above.
928 --children
930 Print also the children of the commit (in the form "commit
931 child..."). Also enables parent rewriting, see History
932 Simplification above.
933 --timestamp
935 Print the raw commit timestamp.
936 --left-right
938 Mark which side of a symmetric difference a commit is reachable
939 from. Commits from the left side are prefixed with < and those from
940 the right with >. If combined with --boundary, those commits are
941 prefixed with -.
942 For example, if you have this topology:
944 y---b---b branch B
946 / \ /
947 / .
948 / / \
949 o---x---a---a branch A
950 you would get an output like this:
952 $ git rev-list --left-right --boundary --pretty=oneline A...B
954 >bbbbbbb... 3rd on b
956 >bbbbbbb... 2nd on b
957 <aaaaaaa... 3rd on a
958 <aaaaaaa... 2nd on a
959 -yyyyyyy... 1st on b
960 -xxxxxxx... 1st on a
961 --graph
964 Draw a text-based graphical representation of the commit history on
965 the left hand side of the output. This may cause extra lines to be
966 printed in between commits, in order for the graph history to be
967 drawn properly. Cannot be combined with --no-walk.
968 This enables parent rewriting, see History Simplification above.
970 This implies the --topo-order option by default, but the
972 --date-order option may also be specified.
973 --show-linear-break[=<barrier>]
975 When --graph is not used, all history branches are flattened which
976 can make it hard to see that the two consecutive commits do not
977 belong to a linear branch. This option puts a barrier in between
978 them in that case. If <barrier> is specified, it is the string that
979 will be shown instead of the default one.
980 --count
982 Print a number stating how many commits would have been listed, and
983 suppress all other output. When used together with --left-right,
984 instead print the counts for left and right commits, separated by a
985 tab. When used together with --cherry-mark, omit patch equivalent
986 commits from these counts and print the count for equivalent
987 commits separated by a tab.
988
990 If the commit is a merge, and if the pretty-format is not oneline,
991 email or raw, an additional line is inserted before the Author: line.
992 This line begins with "Merge: " and the sha1s of ancestral commits are
993 printed, separated by spaces. Note that the listed commits may not
994 necessarily be the list of the direct parent commits if you have
995 limited your view of history: for example, if you are only interested
996 in changes related to a certain directory or file.
997 There are several built-in formats, and you can define additional
999 formats by setting a pretty.<name> config option to either another
1000 format name, or a format: string, as described below (see git-
1001 config(1)). Here are the details of the built-in formats:
1002 · oneline
1004 <sha1> <title line>
1006 This is designed to be as compact as possible.
1008 · short
1010 commit <sha1>
1012 Author: <author>
1013 <title line>
1015 · medium
1017 commit <sha1>
1019 Author: <author>
1020 Date: <author date>
1021 <title line>
1023 <full commit message>
1025 · full
1027 commit <sha1>
1029 Author: <author>
1030 Commit: <committer>
1031 <title line>
1033 <full commit message>
1035 · fuller
1037 commit <sha1>
1039 Author: <author>
1040 AuthorDate: <author date>
1041 Commit: <committer>
1042 CommitDate: <committer date>
1043 <title line>
1045 <full commit message>
1047 · email
1049 From <sha1> <date>
1051 From: <author>
1052 Date: <author date>
1053 Subject: [PATCH] <title line>
1054 <full commit message>
1056 · raw
1058 The raw format shows the entire commit exactly as stored in the
1060 commit object. Notably, the SHA-1s are displayed in full,
1061 regardless of whether --abbrev or --no-abbrev are used, and parents
1062 information show the true parent commits, without taking grafts or
1063 history simplification into account. Note that this format affects
1064 the way commits are displayed, but not the way the diff is shown
1065 e.g. with git log --raw. To get full object names in a raw diff
1066 format, use --no-abbrev.
1067 · format:<string>
1069 The format:<string> format allows you to specify which information
1071 you want to show. It works a little bit like printf format, with
1072 the notable exception that you get a newline with %n instead of \n.
1073 E.g, format:"The author of %h was %an, %ar%nThe title was >>%s<<%n"
1075 would show something like this:
1076 The author of fe6e0ee was Junio C Hamano, 23 hours ago
1078 The title was >>t4119: test autocomputing -p<n> for traditional diff input.<<
1079 The placeholders are:
1081 · %H: commit hash
1083 · %h: abbreviated commit hash
1085 · %T: tree hash
1087 · %t: abbreviated tree hash
1089 · %P: parent hashes
1091 · %p: abbreviated parent hashes
1093 · %an: author name
1095 · %aN: author name (respecting .mailmap, see git-shortlog(1) or
1097 git-blame(1))
1098 · %ae: author email
1100 · %aE: author email (respecting .mailmap, see git-shortlog(1) or
1102 git-blame(1))
1103 · %ad: author date (format respects --date= option)
1105 · %aD: author date, RFC2822 style
1107 · %ar: author date, relative
1109 · %at: author date, UNIX timestamp
1111 · %ai: author date, ISO 8601-like format
1113 · %aI: author date, strict ISO 8601 format
1115 · %cn: committer name
1117 · %cN: committer name (respecting .mailmap, see git-shortlog(1)
1119 or git-blame(1))
1120 · %ce: committer email
1122 · %cE: committer email (respecting .mailmap, see git-shortlog(1)
1124 or git-blame(1))
1125 · %cd: committer date (format respects --date= option)
1127 · %cD: committer date, RFC2822 style
1129 · %cr: committer date, relative
1131 · %ct: committer date, UNIX timestamp
1133 · %ci: committer date, ISO 8601-like format
1135 · %cI: committer date, strict ISO 8601 format
1137 · %d: ref names, like the --decorate option of git-log(1)
1139 · %D: ref names without the " (", ")" wrapping.
1141 · %e: encoding
1143 · %s: subject
1145 · %f: sanitized subject line, suitable for a filename
1147 · %b: body
1149 · %B: raw body (unwrapped subject and body)
1151 · %GG: raw verification message from GPG for a signed commit
1153 · %G?: show "G" for a good (valid) signature, "B" for a bad
1155 signature, "U" for a good signature with unknown validity, "X"
1156 for a good signature that has expired, "Y" for a good signature
1157 made by an expired key, "R" for a good signature made by a
1158 revoked key, "E" if the signature cannot be checked (e.g.
1159 missing key) and "N" for no signature
1160 · %GS: show the name of the signer for a signed commit
1162 · %GK: show the key used to sign a signed commit
1164 · %GF: show the fingerprint of the key used to sign a signed
1166 commit
1167 · %GP: show the fingerprint of the primary key whose subkey was
1169 used to sign a signed commit
1170 · %gD: reflog selector, e.g., refs/stash@{1} or refs/stash@{2
1172 minutes ago}; the format follows the rules described for the -g
1173 option. The portion before the @ is the refname as given on the
1174 command line (so git log -g refs/heads/master would yield
1175 refs/heads/master@{0}).
1176 · %gd: shortened reflog selector; same as %gD, but the refname
1178 portion is shortened for human readability (so
1179 refs/heads/master becomes just master).
1180 · %gn: reflog identity name
1182 · %gN: reflog identity name (respecting .mailmap, see git-
1184 shortlog(1) or git-blame(1))
1185 · %ge: reflog identity email
1187 · %gE: reflog identity email (respecting .mailmap, see git-
1189 shortlog(1) or git-blame(1))
1190 · %gs: reflog subject
1192 · %Cred: switch color to red
1194 · %Cgreen: switch color to green
1196 · %Cblue: switch color to blue
1198 · %Creset: reset color
1200 · %C(...): color specification, as described under Values in the
1202 "CONFIGURATION FILE" section of git-config(1). By default,
1203 colors are shown only when enabled for log output (by
1204 color.diff, color.ui, or --color, and respecting the auto
1205 settings of the former if we are going to a terminal).
1206 %C(auto,...) is accepted as a historical synonym for the
1207 default (e.g., %C(auto,red)). Specifying %C(always,...) will
1208 show the colors even when color is not otherwise enabled
1209 (though consider just using `--color=always to enable color for
1210 the whole output, including this format and anything else git
1211 might color). auto alone (i.e. %C(auto)) will turn on auto
1212 coloring on the next placeholders until the color is switched
1213 again.
1214 · %m: left (<), right (>) or boundary (-) mark
1216 · %n: newline
1218 · %%: a raw %
1220 · %x00: print a byte from a hex code
1222 · %w([<w>[,<i1>[,<i2>]]]): switch line wrapping, like the -w
1224 option of git-shortlog(1).
1225 · %<(<N>[,trunc|ltrunc|mtrunc]): make the next placeholder take
1227 at least N columns, padding spaces on the right if necessary.
1228 Optionally truncate at the beginning (ltrunc), the middle
1229 (mtrunc) or the end (trunc) if the output is longer than N
1230 columns. Note that truncating only works correctly with N >= 2.
1231 · %<|(<N>): make the next placeholder take at least until Nth
1233 columns, padding spaces on the right if necessary
1234 · %>(<N>), %>|(<N>): similar to %<(<N>), %<|(<N>) respectively,
1236 but padding spaces on the left
1237 · %>>(<N>), %>>|(<N>): similar to %>(<N>), %>|(<N>) respectively,
1239 except that if the next placeholder takes more spaces than
1240 given and there are spaces on its left, use those spaces
1241 · %><(<N>), %><|(<N>): similar to %<(<N>), %<|(<N>) respectively,
1243 but padding both sides (i.e. the text is centered)
1244 · %(trailers[:options]): display the trailers of the body as
1246 interpreted by git-interpret-trailers(1). The trailers string
1247 may be followed by a colon and zero or more comma-separated
1248 options. If the only option is given, omit non-trailer lines
1249 from the trailer block. If the unfold option is given, behave
1250 as if interpret-trailer’s --unfold option was given. E.g.,
1251 %(trailers:only,unfold) to do both.
1252 Note
1254 Some placeholders may depend on other options given to the revision
1255 traversal engine. For example, the %g* reflog options will insert
1256 an empty string unless we are traversing reflog entries (e.g., by
1257 git log -g). The %d and %D placeholders will use the "short"
1258 decoration format if --decorate was not already provided on the
1259 command line.
1260 If you add a + (plus sign) after % of a placeholder, a line-feed is
1262 inserted immediately before the expansion if and only if the
1263 placeholder expands to a non-empty string.
1264 If you add a - (minus sign) after % of a placeholder, all consecutive
1266 line-feeds immediately preceding the expansion are deleted if and only
1267 if the placeholder expands to an empty string.
1268 If you add a ` ` (space) after % of a placeholder, a space is inserted
1270 immediately before the expansion if and only if the placeholder expands
1271 to a non-empty string.
1272 · tformat:
1274 The tformat: format works exactly like format:, except that it
1276 provides "terminator" semantics instead of "separator" semantics.
1277 In other words, each commit has the message terminator character
1278 (usually a newline) appended, rather than a separator placed
1279 between entries. This means that the final entry of a single-line
1280 format will be properly terminated with a new line, just as the
1281 "oneline" format does. For example:
1282 $ git log -2 --pretty=format:%h 4da45bef \
1284 | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
1285 4da45be
1286 7134973 -- NO NEWLINE
1287 $ git log -2 --pretty=tformat:%h 4da45bef \
1289 | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
1290 4da45be
1291 7134973
1292 In addition, any unrecognized string that has a % in it is
1294 interpreted as if it has tformat: in front of it. For example,
1295 these two are equivalent:
1296 $ git log -2 --pretty=tformat:%h 4da45bef
1298 $ git log -2 --pretty=%h 4da45bef
1299
1302 Part of the git(1) suite
1303Git 2.20.1 12/15/2018 GIT-REV-LIST(1)