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). <depth>=0
755 will not include any trees or blobs unless included explicitly in
756 the command-line (or standard input when --stdin is used).
757 <depth>=1 will include only the tree and blobs which are referenced
758 directly by a commit reachable from <commit> or an explicitly-given
759 object. <depth>=2 is like <depth>=1 while also including trees and
760 blobs one more level removed from an explicitly-given commit or
761 tree.
762 --no-filter
764 Turn off any previous --filter= argument.
765 --filter-print-omitted
767 Only useful with --filter=; prints a list of the objects omitted by
768 the filter. Object IDs are prefixed with a “~” character.
769 --missing=<missing-action>
771 A debug option to help with future "partial clone" development.
772 This option specifies how missing objects are handled.
773 The form --missing=error requests that rev-list stop with an error
775 if a missing object is encountered. This is the default action.
776 The form --missing=allow-any will allow object traversal to
778 continue if a missing object is encountered. Missing objects will
779 silently be omitted from the results.
780 The form --missing=allow-promisor is like allow-any, but will only
782 allow object traversal to continue for EXPECTED promisor missing
783 objects. Unexpected missing objects will raise an error.
784 The form --missing=print is like allow-any, but will also print a
786 list of the missing objects. Object IDs are prefixed with a “?”
787 character.
788 --exclude-promisor-objects
790 (For internal use only.) Prefilter object traversal at promisor
791 boundary. This is used with partial clone. This is stronger than
792 --missing=allow-promisor because it limits the traversal, rather
793 than just silencing errors about missing objects.
794 --no-walk[=(sorted|unsorted)]
796 Only show the given commits, but do not traverse their ancestors.
797 This has no effect if a range is specified. If the argument
798 unsorted is given, the commits are shown in the order they were
799 given on the command line. Otherwise (if sorted or no argument was
800 given), the commits are shown in reverse chronological order by
801 commit time. Cannot be combined with --graph.
802 --do-walk
804 Overrides a previous --no-walk.
805 Commit Formatting
807 Using these options, git-rev-list(1) will act similar to the more
808 specialized family of commit log tools: git-log(1), git-show(1), and
809 git-whatchanged(1)
810 --pretty[=<format>], --format=<format>
812 Pretty-print the contents of the commit logs in a given format,
813 where <format> can be one of oneline, short, medium, full, fuller,
814 email, raw, format:<string> and tformat:<string>. When <format> is
815 none of the above, and has %placeholder in it, it acts as if
816 --pretty=tformat:<format> were given.
817 See the "PRETTY FORMATS" section for some additional details for
819 each format. When =<format> part is omitted, it defaults to medium.
820 Note: you can specify the default pretty format in the repository
822 configuration (see git-config(1)).
823 --abbrev-commit
825 Instead of showing the full 40-byte hexadecimal commit object name,
826 show only a partial prefix. Non default number of digits can be
827 specified with "--abbrev=<n>" (which also modifies diff output, if
828 it is displayed).
829 This should make "--pretty=oneline" a whole lot more readable for
831 people using 80-column terminals.
832 --no-abbrev-commit
834 Show the full 40-byte hexadecimal commit object name. This negates
835 --abbrev-commit and those options which imply it such as
836 "--oneline". It also overrides the log.abbrevCommit variable.
837 --oneline
839 This is a shorthand for "--pretty=oneline --abbrev-commit" used
840 together.
841 --encoding=<encoding>
843 The commit objects record the encoding used for the log message in
844 their encoding header; this option can be used to tell the command
845 to re-code the commit log message in the encoding preferred by the
846 user. For non plumbing commands this defaults to UTF-8. Note that
847 if an object claims to be encoded in X and we are outputting in X,
848 we will output the object verbatim; this means that invalid
849 sequences in the original commit may be copied to the output.
850 --expand-tabs=<n>, --expand-tabs, --no-expand-tabs
852 Perform a tab expansion (replace each tab with enough spaces to
853 fill to the next display column that is multiple of <n>) in the log
854 message before showing it in the output. --expand-tabs is a
855 short-hand for --expand-tabs=8, and --no-expand-tabs is a
856 short-hand for --expand-tabs=0, which disables tab expansion.
857 By default, tabs are expanded in pretty formats that indent the log
859 message by 4 spaces (i.e. medium, which is the default, full, and
860 fuller).
861 --show-signature
863 Check the validity of a signed commit object by passing the
864 signature to gpg --verify and show the output.
865 --relative-date
867 Synonym for --date=relative.
868 --date=<format>
870 Only takes effect for dates shown in human-readable format, such as
871 when using --pretty. log.date config variable sets a default value
872 for the log command’s --date option. By default, dates are shown in
873 the original time zone (either committer’s or author’s). If -local
874 is appended to the format (e.g., iso-local), the user’s local time
875 zone is used instead.
876 --date=relative shows dates relative to the current time, e.g. “2
878 hours ago”. The -local option has no effect for --date=relative.
879 --date=local is an alias for --date=default-local.
881 --date=iso (or --date=iso8601) shows timestamps in a ISO 8601-like
883 format. The differences to the strict ISO 8601 format are:
884 · a space instead of the T date/time delimiter
886 · a space between time and time zone
888 · no colon between hours and minutes of the time zone
890 --date=iso-strict (or --date=iso8601-strict) shows timestamps in
892 strict ISO 8601 format.
893 --date=rfc (or --date=rfc2822) shows timestamps in RFC 2822 format,
895 often found in email messages.
896 --date=short shows only the date, but not the time, in YYYY-MM-DD
898 format.
899 --date=raw shows the date as seconds since the epoch (1970-01-01
901 00:00:00 UTC), followed by a space, and then the timezone as an
902 offset from UTC (a + or - with four digits; the first two are
903 hours, and the second two are minutes). I.e., as if the timestamp
904 were formatted with strftime("%s %z")). Note that the -local option
905 does not affect the seconds-since-epoch value (which is always
906 measured in UTC), but does switch the accompanying timezone value.
907 --date=human shows the timezone if the timezone does not match the
909 current time-zone, and doesn’t print the whole date if that matches
910 (ie skip printing year for dates that are "this year", but also
911 skip the whole date itself if it’s in the last few days and we can
912 just say what weekday it was). For older dates the hour and minute
913 is also omitted.
914 --date=unix shows the date as a Unix epoch timestamp (seconds since
916 1970). As with --raw, this is always in UTC and therefore -local
917 has no effect.
918 --date=format:... feeds the format ... to your system strftime,
920 except for %z and %Z, which are handled internally. Use
921 --date=format:%c to show the date in your system locale’s preferred
922 format. See the strftime manual for a complete list of format
923 placeholders. When using -local, the correct syntax is
924 --date=format-local:....
925 --date=default is the default format, and is similar to
927 --date=rfc2822, with a few exceptions:
928 · there is no comma after the day-of-week
930 · the time zone is omitted when the local time zone is used
932 --header
934 Print the contents of the commit in raw-format; each record is
935 separated with a NUL character.
936 --parents
938 Print also the parents of the commit (in the form "commit
939 parent..."). Also enables parent rewriting, see History
940 Simplification above.
941 --children
943 Print also the children of the commit (in the form "commit
944 child..."). Also enables parent rewriting, see History
945 Simplification above.
946 --timestamp
948 Print the raw commit timestamp.
949 --left-right
951 Mark which side of a symmetric difference a commit is reachable
952 from. Commits from the left side are prefixed with < and those from
953 the right with >. If combined with --boundary, those commits are
954 prefixed with -.
955 For example, if you have this topology:
957 y---b---b branch B
959 / \ /
960 / .
961 / / \
962 o---x---a---a branch A
963 you would get an output like this:
965 $ git rev-list --left-right --boundary --pretty=oneline A...B
967 >bbbbbbb... 3rd on b
969 >bbbbbbb... 2nd on b
970 <aaaaaaa... 3rd on a
971 <aaaaaaa... 2nd on a
972 -yyyyyyy... 1st on b
973 -xxxxxxx... 1st on a
974 --graph
977 Draw a text-based graphical representation of the commit history on
978 the left hand side of the output. This may cause extra lines to be
979 printed in between commits, in order for the graph history to be
980 drawn properly. Cannot be combined with --no-walk.
981 This enables parent rewriting, see History Simplification above.
983 This implies the --topo-order option by default, but the
985 --date-order option may also be specified.
986 --show-linear-break[=<barrier>]
988 When --graph is not used, all history branches are flattened which
989 can make it hard to see that the two consecutive commits do not
990 belong to a linear branch. This option puts a barrier in between
991 them in that case. If <barrier> is specified, it is the string that
992 will be shown instead of the default one.
993 --count
995 Print a number stating how many commits would have been listed, and
996 suppress all other output. When used together with --left-right,
997 instead print the counts for left and right commits, separated by a
998 tab. When used together with --cherry-mark, omit patch equivalent
999 commits from these counts and print the count for equivalent
1000 commits separated by a tab.
1001
1003 If the commit is a merge, and if the pretty-format is not oneline,
1004 email or raw, an additional line is inserted before the Author: line.
1005 This line begins with "Merge: " and the sha1s of ancestral commits are
1006 printed, separated by spaces. Note that the listed commits may not
1007 necessarily be the list of the direct parent commits if you have
1008 limited your view of history: for example, if you are only interested
1009 in changes related to a certain directory or file.
1010 There are several built-in formats, and you can define additional
1012 formats by setting a pretty.<name> config option to either another
1013 format name, or a format: string, as described below (see git-
1014 config(1)). Here are the details of the built-in formats:
1015 · oneline
1017 <sha1> <title line>
1019 This is designed to be as compact as possible.
1021 · short
1023 commit <sha1>
1025 Author: <author>
1026 <title line>
1028 · medium
1030 commit <sha1>
1032 Author: <author>
1033 Date: <author date>
1034 <title line>
1036 <full commit message>
1038 · full
1040 commit <sha1>
1042 Author: <author>
1043 Commit: <committer>
1044 <title line>
1046 <full commit message>
1048 · fuller
1050 commit <sha1>
1052 Author: <author>
1053 AuthorDate: <author date>
1054 Commit: <committer>
1055 CommitDate: <committer date>
1056 <title line>
1058 <full commit message>
1060 · email
1062 From <sha1> <date>
1064 From: <author>
1065 Date: <author date>
1066 Subject: [PATCH] <title line>
1067 <full commit message>
1069 · raw
1071 The raw format shows the entire commit exactly as stored in the
1073 commit object. Notably, the SHA-1s are displayed in full,
1074 regardless of whether --abbrev or --no-abbrev are used, and parents
1075 information show the true parent commits, without taking grafts or
1076 history simplification into account. Note that this format affects
1077 the way commits are displayed, but not the way the diff is shown
1078 e.g. with git log --raw. To get full object names in a raw diff
1079 format, use --no-abbrev.
1080 · format:<string>
1082 The format:<string> format allows you to specify which information
1084 you want to show. It works a little bit like printf format, with
1085 the notable exception that you get a newline with %n instead of \n.
1086 E.g, format:"The author of %h was %an, %ar%nThe title was >>%s<<%n"
1088 would show something like this:
1089 The author of fe6e0ee was Junio C Hamano, 23 hours ago
1091 The title was >>t4119: test autocomputing -p<n> for traditional diff input.<<
1092 The placeholders are:
1094 · %H: commit hash
1096 · %h: abbreviated commit hash
1098 · %T: tree hash
1100 · %t: abbreviated tree hash
1102 · %P: parent hashes
1104 · %p: abbreviated parent hashes
1106 · %an: author name
1108 · %aN: author name (respecting .mailmap, see git-shortlog(1) or
1110 git-blame(1))
1111 · %ae: author email
1113 · %aE: author email (respecting .mailmap, see git-shortlog(1) or
1115 git-blame(1))
1116 · %ad: author date (format respects --date= option)
1118 · %aD: author date, RFC2822 style
1120 · %ar: author date, relative
1122 · %at: author date, UNIX timestamp
1124 · %ai: author date, ISO 8601-like format
1126 · %aI: author date, strict ISO 8601 format
1128 · %cn: committer name
1130 · %cN: committer name (respecting .mailmap, see git-shortlog(1)
1132 or git-blame(1))
1133 · %ce: committer email
1135 · %cE: committer email (respecting .mailmap, see git-shortlog(1)
1137 or git-blame(1))
1138 · %cd: committer date (format respects --date= option)
1140 · %cD: committer date, RFC2822 style
1142 · %cr: committer date, relative
1144 · %ct: committer date, UNIX timestamp
1146 · %ci: committer date, ISO 8601-like format
1148 · %cI: committer date, strict ISO 8601 format
1150 · %d: ref names, like the --decorate option of git-log(1)
1152 · %D: ref names without the " (", ")" wrapping.
1154 · %S: ref name given on the command line by which the commit was
1156 reached (like git log --source), only works with git log
1157 · %e: encoding
1159 · %s: subject
1161 · %f: sanitized subject line, suitable for a filename
1163 · %b: body
1165 · %B: raw body (unwrapped subject and body)
1167 · %GG: raw verification message from GPG for a signed commit
1169 · %G?: show "G" for a good (valid) signature, "B" for a bad
1171 signature, "U" for a good signature with unknown validity, "X"
1172 for a good signature that has expired, "Y" for a good signature
1173 made by an expired key, "R" for a good signature made by a
1174 revoked key, "E" if the signature cannot be checked (e.g.
1175 missing key) and "N" for no signature
1176 · %GS: show the name of the signer for a signed commit
1178 · %GK: show the key used to sign a signed commit
1180 · %GF: show the fingerprint of the key used to sign a signed
1182 commit
1183 · %GP: show the fingerprint of the primary key whose subkey was
1185 used to sign a signed commit
1186 · %gD: reflog selector, e.g., refs/stash@{1} or refs/stash@{2
1188 minutes ago}; the format follows the rules described for the -g
1189 option. The portion before the @ is the refname as given on the
1190 command line (so git log -g refs/heads/master would yield
1191 refs/heads/master@{0}).
1192 · %gd: shortened reflog selector; same as %gD, but the refname
1194 portion is shortened for human readability (so
1195 refs/heads/master becomes just master).
1196 · %gn: reflog identity name
1198 · %gN: reflog identity name (respecting .mailmap, see git-
1200 shortlog(1) or git-blame(1))
1201 · %ge: reflog identity email
1203 · %gE: reflog identity email (respecting .mailmap, see git-
1205 shortlog(1) or git-blame(1))
1206 · %gs: reflog subject
1208 · %Cred: switch color to red
1210 · %Cgreen: switch color to green
1212 · %Cblue: switch color to blue
1214 · %Creset: reset color
1216 · %C(...): color specification, as described under Values in the
1218 "CONFIGURATION FILE" section of git-config(1). By default,
1219 colors are shown only when enabled for log output (by
1220 color.diff, color.ui, or --color, and respecting the auto
1221 settings of the former if we are going to a terminal).
1222 %C(auto,...) is accepted as a historical synonym for the
1223 default (e.g., %C(auto,red)). Specifying %C(always,...) will
1224 show the colors even when color is not otherwise enabled
1225 (though consider just using --color=always to enable color for
1226 the whole output, including this format and anything else git
1227 might color). auto alone (i.e. %C(auto)) will turn on auto
1228 coloring on the next placeholders until the color is switched
1229 again.
1230 · %m: left (<), right (>) or boundary (-) mark
1232 · %n: newline
1234 · %%: a raw %
1236 · %x00: print a byte from a hex code
1238 · %w([<w>[,<i1>[,<i2>]]]): switch line wrapping, like the -w
1240 option of git-shortlog(1).
1241 · %<(<N>[,trunc|ltrunc|mtrunc]): make the next placeholder take
1243 at least N columns, padding spaces on the right if necessary.
1244 Optionally truncate at the beginning (ltrunc), the middle
1245 (mtrunc) or the end (trunc) if the output is longer than N
1246 columns. Note that truncating only works correctly with N >= 2.
1247 · %<|(<N>): make the next placeholder take at least until Nth
1249 columns, padding spaces on the right if necessary
1250 · %>(<N>), %>|(<N>): similar to %<(<N>), %<|(<N>) respectively,
1252 but padding spaces on the left
1253 · %>>(<N>), %>>|(<N>): similar to %>(<N>), %>|(<N>) respectively,
1255 except that if the next placeholder takes more spaces than
1256 given and there are spaces on its left, use those spaces
1257 · %><(<N>), %><|(<N>): similar to %<(<N>), %<|(<N>) respectively,
1259 but padding both sides (i.e. the text is centered)
1260 · %(trailers[:options]): display the trailers of the body as
1262 interpreted by git-interpret-trailers(1). The trailers string
1263 may be followed by a colon and zero or more comma-separated
1264 options. If the only option is given, omit non-trailer lines
1265 from the trailer block. If the unfold option is given, behave
1266 as if interpret-trailer’s --unfold option was given. E.g.,
1267 %(trailers:only,unfold) to do both.
1268 Note
1270 Some placeholders may depend on other options given to the revision
1271 traversal engine. For example, the %g* reflog options will insert
1272 an empty string unless we are traversing reflog entries (e.g., by
1273 git log -g). The %d and %D placeholders will use the "short"
1274 decoration format if --decorate was not already provided on the
1275 command line.
1276 If you add a + (plus sign) after % of a placeholder, a line-feed is
1278 inserted immediately before the expansion if and only if the
1279 placeholder expands to a non-empty string.
1280 If you add a - (minus sign) after % of a placeholder, all consecutive
1282 line-feeds immediately preceding the expansion are deleted if and only
1283 if the placeholder expands to an empty string.
1284 If you add a ` ` (space) after % of a placeholder, a space is inserted
1286 immediately before the expansion if and only if the placeholder expands
1287 to a non-empty string.
1288 · tformat:
1290 The tformat: format works exactly like format:, except that it
1292 provides "terminator" semantics instead of "separator" semantics.
1293 In other words, each commit has the message terminator character
1294 (usually a newline) appended, rather than a separator placed
1295 between entries. This means that the final entry of a single-line
1296 format will be properly terminated with a new line, just as the
1297 "oneline" format does. For example:
1298 $ git log -2 --pretty=format:%h 4da45bef \
1300 | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
1301 4da45be
1302 7134973 -- NO NEWLINE
1303 $ git log -2 --pretty=tformat:%h 4da45bef \
1305 | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
1306 4da45be
1307 7134973
1308 In addition, any unrecognized string that has a % in it is
1310 interpreted as if it has tformat: in front of it. For example,
1311 these two are equivalent:
1312 $ git log -2 --pretty=tformat:%h 4da45bef
1314 $ git log -2 --pretty=%h 4da45bef
1315
1318 Part of the git(1) suite
1319Git 2.21.0 02/24/2019 GIT-REV-LIST(1)