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 [<options>] <commit>... [[--] <path>...]
10
13 List commits that are reachable by following the parent links from the
14 given commit(s), but exclude commits that are reachable from the one(s)
15 given with a ^ in front of them. The output is given in reverse
16 chronological order by default.
17 You can think of this as a set operation. Commits given on the command
19 line form a set of commits that are reachable from any of them, and
20 then commits reachable from any of the ones given with ^ in front are
21 subtracted from that set. The remaining commits are what comes out in
22 the command’s output. Various other options and paths parameters can be
23 used to further limit the result.
24 Thus, the following command:
26 $ git rev-list foo bar ^baz
28 means "list all the commits which are reachable from foo or bar, but
31 not from baz".
32 A special notation "<commit1>..<commit2>" can be used as a short-hand
34 for "^'<commit1>' <commit2>". For example, either of the following may
35 be used interchangeably:
36 $ git rev-list origin..HEAD
38 $ git rev-list HEAD ^origin
39 Another special notation is "<commit1>...<commit2>" which is useful for
42 merges. The resulting set of commits is the symmetric difference
43 between the two operands. The following two commands are equivalent:
44 $ git rev-list A B --not $(git merge-base --all A B)
46 $ git rev-list A...B
47 rev-list is a very essential Git command, since it provides the ability
50 to build and traverse commit ancestry graphs. For this reason, it has a
51 lot of different options that enables it to be used by commands as
52 different as git bisect and git repack.
53
55 Commit Limiting
56 Besides specifying a range of commits that should be listed using the
57 special notations explained in the description, additional commit
58 limiting may be applied.
59 Using more options generally further limits the output (e.g.
61 --since=<date1> limits to commits newer than <date1>, and using it with
62 --grep=<pattern> further limits to commits whose log message has a line
63 that matches <pattern>), unless otherwise noted.
64 Note that these are applied before commit ordering and formatting
66 options, such as --reverse.
67 -<number>, -n <number>, --max-count=<number>
69 Limit the number of commits to output.
70 --skip=<number>
72 Skip number commits before starting to show the commit output.
73 --since=<date>, --after=<date>
75 Show commits more recent than a specific date.
76 --until=<date>, --before=<date>
78 Show commits older than a specific date.
79 --max-age=<timestamp>, --min-age=<timestamp>
81 Limit the commits output to specified time range.
82 --author=<pattern>, --committer=<pattern>
84 Limit the commits output to ones with author/committer header lines
85 that match the specified pattern (regular expression). With more
86 than one --author=<pattern>, commits whose author matches any of
87 the given patterns are chosen (similarly for multiple
88 --committer=<pattern>).
89 --grep-reflog=<pattern>
91 Limit the commits output to ones with reflog entries that match the
92 specified pattern (regular expression). With more than one
93 --grep-reflog, commits whose reflog message matches any of the
94 given patterns are chosen. It is an error to use this option unless
95 --walk-reflogs is in use.
96 --grep=<pattern>
98 Limit the commits output to ones with log message that matches the
99 specified pattern (regular expression). With more than one
100 --grep=<pattern>, commits whose message matches any of the given
101 patterns are chosen (but see --all-match).
102 --all-match
104 Limit the commits output to ones that match all given --grep,
105 instead of ones that match at least one.
106 --invert-grep
108 Limit the commits output to ones with log message that do not match
109 the pattern specified with --grep=<pattern>.
110 -i, --regexp-ignore-case
112 Match the regular expression limiting patterns without regard to
113 letter case.
114 --basic-regexp
116 Consider the limiting patterns to be basic regular expressions;
117 this is the default.
118 -E, --extended-regexp
120 Consider the limiting patterns to be extended regular expressions
121 instead of the default basic regular expressions.
122 -F, --fixed-strings
124 Consider the limiting patterns to be fixed strings (don’t interpret
125 pattern as a regular expression).
126 -P, --perl-regexp
128 Consider the limiting patterns to be Perl-compatible regular
129 expressions.
130 Support for these types of regular expressions is an optional
132 compile-time dependency. If Git wasn’t compiled with support for
133 them providing this option will cause it to die.
134 --remove-empty
136 Stop when a given path disappears from the tree.
137 --merges
139 Print only merge commits. This is exactly the same as
140 --min-parents=2.
141 --no-merges
143 Do not print commits with more than one parent. This is exactly the
144 same as --max-parents=1.
145 --min-parents=<number>, --max-parents=<number>, --no-min-parents,
147 --no-max-parents
148 Show only commits which have at least (or at most) that many parent
149 commits. In particular, --max-parents=1 is the same as --no-merges,
150 --min-parents=2 is the same as --merges. --max-parents=0 gives all
151 root commits and --min-parents=3 all octopus merges.
152 --no-min-parents and --no-max-parents reset these limits (to no
154 limit) again. Equivalent forms are --min-parents=0 (any commit has
155 0 or more parents) and --max-parents=-1 (negative numbers denote no
156 upper limit).
157 --first-parent
159 Follow only the first parent commit upon seeing a merge commit.
160 This option can give a better overview when viewing the evolution
161 of a particular topic branch, because merges into a topic branch
162 tend to be only about adjusting to updated upstream from time to
163 time, and this option allows you to ignore the individual commits
164 brought in to your history by such a merge. Cannot be combined with
165 --bisect.
166 --not
168 Reverses the meaning of the ^ prefix (or lack thereof) for all
169 following revision specifiers, up to the next --not.
170 --all
172 Pretend as if all the refs in refs/, along with HEAD, are listed on
173 the command line as <commit>.
174 --branches[=<pattern>]
176 Pretend as if all the refs in refs/heads are listed on the command
177 line as <commit>. If <pattern> is given, limit branches to ones
178 matching given shell glob. If pattern lacks ?, *, or [, /* at the
179 end is implied.
180 --tags[=<pattern>]
182 Pretend as if all the refs in refs/tags are listed on the command
183 line as <commit>. If <pattern> is given, limit tags to ones
184 matching given shell glob. If pattern lacks ?, *, or [, /* at the
185 end is implied.
186 --remotes[=<pattern>]
188 Pretend as if all the refs in refs/remotes are listed on the
189 command line as <commit>. If <pattern> is given, limit
190 remote-tracking branches to ones matching given shell glob. If
191 pattern lacks ?, *, or [, /* at the end is implied.
192 --glob=<glob-pattern>
194 Pretend as if all the refs matching shell glob <glob-pattern> are
195 listed on the command line as <commit>. Leading refs/, is
196 automatically prepended if missing. If pattern lacks ?, *, or [, /*
197 at the end is implied.
198 --exclude=<glob-pattern>
200 Do not include refs matching <glob-pattern> that the next --all,
201 --branches, --tags, --remotes, or --glob would otherwise consider.
202 Repetitions of this option accumulate exclusion patterns up to the
203 next --all, --branches, --tags, --remotes, or --glob option (other
204 options or arguments do not clear accumulated patterns).
205 The patterns given should not begin with refs/heads, refs/tags, or
207 refs/remotes when applied to --branches, --tags, or --remotes,
208 respectively, and they must begin with refs/ when applied to --glob
209 or --all. If a trailing /* is intended, it must be given
210 explicitly.
211 --reflog
213 Pretend as if all objects mentioned by reflogs are listed on the
214 command line as <commit>.
215 --alternate-refs
217 Pretend as if all objects mentioned as ref tips of alternate
218 repositories were listed on the command line. An alternate
219 repository is any repository whose object directory is specified in
220 objects/info/alternates. The set of included objects may be
221 modified by core.alternateRefsCommand, etc. See git-config(1).
222 --single-worktree
224 By default, all working trees will be examined by the following
225 options when there are more than one (see git-worktree(1)): --all,
226 --reflog and --indexed-objects. This option forces them to examine
227 the current working tree only.
228 --ignore-missing
230 Upon seeing an invalid object name in the input, pretend as if the
231 bad input was not given.
232 --stdin
234 In addition to the <commit> listed on the command line, read them
235 from the standard input. If a -- separator is seen, stop reading
236 commits and start reading paths to limit the result.
237 --quiet
239 Don’t print anything to standard output. This form is primarily
240 meant to allow the caller to test the exit status to see if a range
241 of objects is fully connected (or not). It is faster than
242 redirecting stdout to /dev/null as the output does not have to be
243 formatted.
244 --cherry-mark
246 Like --cherry-pick (see below) but mark equivalent commits with =
247 rather than omitting them, and inequivalent ones with +.
248 --cherry-pick
250 Omit any commit that introduces the same change as another commit
251 on the “other side” when the set of commits are limited with
252 symmetric difference.
253 For example, if you have two branches, A and B, a usual way to list
255 all commits on only one side of them is with --left-right (see the
256 example below in the description of the --left-right option).
257 However, it shows the commits that were cherry-picked from the
258 other branch (for example, “3rd on b” may be cherry-picked from
259 branch A). With this option, such pairs of commits are excluded
260 from the output.
261 --left-only, --right-only
263 List only commits on the respective side of a symmetric difference,
264 i.e. only those which would be marked < resp. > by --left-right.
265 For example, --cherry-pick --right-only A...B omits those commits
267 from B which are in A or are patch-equivalent to a commit in A. In
268 other words, this lists the + commits from git cherry A B. More
269 precisely, --cherry-pick --right-only --no-merges gives the exact
270 list.
271 --cherry
273 A synonym for --right-only --cherry-mark --no-merges; useful to
274 limit the output to the commits on our side and mark those that
275 have been applied to the other side of a forked history with git
276 log --cherry upstream...mybranch, similar to git cherry upstream
277 mybranch.
278 -g, --walk-reflogs
280 Instead of walking the commit ancestry chain, walk reflog entries
281 from the most recent one to older ones. When this option is used
282 you cannot specify commits to exclude (that is, ^commit,
283 commit1..commit2, and commit1...commit2 notations cannot be used).
284 With --pretty format other than oneline (for obvious reasons), this
286 causes the output to have two extra lines of information taken from
287 the reflog. The reflog designator in the output may be shown as
288 ref@{Nth} (where Nth is the reverse-chronological index in the
289 reflog) or as ref@{timestamp} (with the timestamp for that entry),
290 depending on a few rules:
291 1. If the starting point is specified as ref@{Nth}, show the index
293 format.
294 2. If the starting point was specified as ref@{now}, show the
296 timestamp format.
297 3. If neither was used, but --date was given on the command line,
299 show the timestamp in the format requested by --date.
300 4. Otherwise, show the index format.
302 Under --pretty=oneline, the commit message is prefixed with this
304 information on the same line. This option cannot be combined with
305 --reverse. See also git-reflog(1).
306 --merge
308 After a failed merge, show refs that touch files having a conflict
309 and don’t exist on all heads to merge.
310 --boundary
312 Output excluded boundary commits. Boundary commits are prefixed
313 with -.
314 --use-bitmap-index
316 Try to speed up the traversal using the pack bitmap index (if one
317 is available). Note that when traversing with --objects, trees and
318 blobs will not have their associated path printed.
319 --progress=<header>
321 Show progress reports on stderr as objects are considered. The
322 <header> text will be printed with each progress update.
323 History Simplification
325 Sometimes you are only interested in parts of the history, for example
326 the commits modifying a particular <path>. But there are two parts of
327 History Simplification, one part is selecting the commits and the other
328 is how to do it, as there are various strategies to simplify the
329 history.
330 The following options select the commits to be shown:
332 <paths>
334 Commits modifying the given <paths> are selected.
335 --simplify-by-decoration
337 Commits that are referred by some branch or tag are selected.
338 Note that extra commits can be shown to give a meaningful history.
340 The following options affect the way the simplification is performed:
342 Default mode
344 Simplifies the history to the simplest history explaining the final
345 state of the tree. Simplest because it prunes some side branches if
346 the end result is the same (i.e. merging branches with the same
347 content)
348 --full-history
350 Same as the default mode, but does not prune some history.
351 --dense
353 Only the selected commits are shown, plus some to have a meaningful
354 history.
355 --sparse
357 All commits in the simplified history are shown.
358 --simplify-merges
360 Additional option to --full-history to remove some needless merges
361 from the resulting history, as there are no selected commits
362 contributing to this merge.
363 --ancestry-path
365 When given a range of commits to display (e.g. commit1..commit2 or
366 commit2 ^commit1), only display commits that exist directly on the
367 ancestry chain between the commit1 and commit2, i.e. commits that
368 are both descendants of commit1, and ancestors of commit2.
369 A more detailed explanation follows.
371 Suppose you specified foo as the <paths>. We shall call commits that
373 modify foo !TREESAME, and the rest TREESAME. (In a diff filtered for
374 foo, they look different and equal, respectively.)
375 In the following, we will always refer to the same example history to
377 illustrate the differences between simplification settings. We assume
378 that you are filtering for a file foo in this commit graph:
379 .-A---M---N---O---P---Q
381 / / / / / /
382 I B C D E Y
383 \ / / / / /
384 `-------------' X
385 The horizontal line of history A---Q is taken to be the first parent of
388 each merge. The commits are:
389 · I is the initial commit, in which foo exists with contents “asdf”,
391 and a file quux exists with contents “quux”. Initial commits are
392 compared to an empty tree, so I is !TREESAME.
393 · In A, foo contains just “foo”.
395 · B contains the same change as A. Its merge M is trivial and hence
397 TREESAME to all parents.
398 · C does not change foo, but its merge N changes it to “foobar”, so
400 it is not TREESAME to any parent.
401 · D sets foo to “baz”. Its merge O combines the strings from N and D
403 to “foobarbaz”; i.e., it is not TREESAME to any parent.
404 · E changes quux to “xyzzy”, and its merge P combines the strings to
406 “quux xyzzy”. P is TREESAME to O, but not to E.
407 · X is an independent root commit that added a new file side, and Y
409 modified it. Y is TREESAME to X. Its merge Q added side to P, and
410 Q is TREESAME to P, but not to Y.
411 rev-list walks backwards through history, including or excluding
413 commits based on whether --full-history and/or parent rewriting (via
414 --parents or --children) are used. The following settings are
415 available.
416 Default mode
418 Commits are included if they are not TREESAME to any parent (though
419 this can be changed, see --sparse below). If the commit was a
420 merge, and it was TREESAME to one parent, follow only that parent.
421 (Even if there are several TREESAME parents, follow only one of
422 them.) Otherwise, follow all parents.
423 This results in:
425 .-A---N---O
427 / / /
428 I---------D
429 Note how the rule to only follow the TREESAME parent, if one is
431 available, removed B from consideration entirely. C was considered
432 via N, but is TREESAME. Root commits are compared to an empty tree,
433 so I is !TREESAME.
434 Parent/child relations are only visible with --parents, but that
436 does not affect the commits selected in default mode, so we have
437 shown the parent lines.
438 --full-history without parent rewriting
440 This mode differs from the default in one point: always follow all
441 parents of a merge, even if it is TREESAME to one of them. Even if
442 more than one side of the merge has commits that are included, this
443 does not imply that the merge itself is! In the example, we get
444 I A B N D O P Q
446 M was excluded because it is TREESAME to both parents. E, C and B
448 were all walked, but only B was !TREESAME, so the others do not
449 appear.
450 Note that without parent rewriting, it is not really possible to
452 talk about the parent/child relationships between the commits, so
453 we show them disconnected.
454 --full-history with parent rewriting
456 Ordinary commits are only included if they are !TREESAME (though
457 this can be changed, see --sparse below).
458 Merges are always included. However, their parent list is
460 rewritten: Along each parent, prune away commits that are not
461 included themselves. This results in
462 .-A---M---N---O---P---Q
464 / / / / /
465 I B / D /
466 \ / / / /
467 `-------------'
468 Compare to --full-history without rewriting above. Note that E was
470 pruned away because it is TREESAME, but the parent list of P was
471 rewritten to contain E's parent I. The same happened for C and N,
472 and X, Y and Q.
473 In addition to the above settings, you can change whether TREESAME
475 affects inclusion:
476 --dense
478 Commits that are walked are included if they are not TREESAME to
479 any parent.
480 --sparse
482 All commits that are walked are included.
483 Note that without --full-history, this still simplifies merges: if
485 one of the parents is TREESAME, we follow only that one, so the
486 other sides of the merge are never walked.
487 --simplify-merges
489 First, build a history graph in the same way that --full-history
490 with parent rewriting does (see above).
491 Then simplify each commit C to its replacement C' in the final
493 history according to the following rules:
494 · Set C' to C.
496 · Replace each parent P of C' with its simplification P'. In the
498 process, drop parents that are ancestors of other parents or
499 that are root commits TREESAME to an empty tree, and remove
500 duplicates, but take care to never drop all parents that we are
501 TREESAME to.
502 · If after this parent rewriting, C' is a root or merge commit
504 (has zero or >1 parents), a boundary commit, or !TREESAME, it
505 remains. Otherwise, it is replaced with its only parent.
506 The effect of this is best shown by way of comparing to
508 --full-history with parent rewriting. The example turns into:
509 .-A---M---N---O
511 / / /
512 I B D
513 \ / /
514 `---------'
515 Note the major differences in N, P, and Q over --full-history:
517 · N's parent list had I removed, because it is an ancestor of the
519 other parent M. Still, N remained because it is !TREESAME.
520 · P's parent list similarly had I removed. P was then removed
522 completely, because it had one parent and is TREESAME.
523 · Q's parent list had Y simplified to X. X was then removed,
525 because it was a TREESAME root. Q was then removed completely,
526 because it had one parent and is TREESAME.
527 Finally, there is a fifth simplification mode available:
529 --ancestry-path
531 Limit the displayed commits to those directly on the ancestry chain
532 between the “from” and “to” commits in the given commit range. I.e.
533 only display commits that are ancestor of the “to” commit and
534 descendants of the “from” commit.
535 As an example use case, consider the following commit history:
537 D---E-------F
539 / \ \
540 B---C---G---H---I---J
541 / \
542 A-------K---------------L--M
543 A regular D..M computes the set of commits that are ancestors of M,
545 but excludes the ones that are ancestors of D. This is useful to
546 see what happened to the history leading to M since D, in the sense
547 that “what does M have that did not exist in D”. The result in this
548 example would be all the commits, except A and B (and D itself, of
549 course).
550 When we want to find out what commits in M are contaminated with
552 the bug introduced by D and need fixing, however, we might want to
553 view only the subset of D..M that are actually descendants of D,
554 i.e. excluding C and K. This is exactly what the --ancestry-path
555 option does. Applied to the D..M range, it results in:
556 E-------F
558 \ \
559 G---H---I---J
560 \
561 L--M
562 The --simplify-by-decoration option allows you to view only the big
565 picture of the topology of the history, by omitting commits that are
566 not referenced by tags. Commits are marked as !TREESAME (in other
567 words, kept after history simplification rules described above) if (1)
568 they are referenced by tags, or (2) they change the contents of the
569 paths given on the command line. All other commits are marked as
570 TREESAME (subject to be simplified away).
571 Bisection Helpers
573 --bisect
574 Limit output to the one commit object which is roughly halfway
575 between included and excluded commits. Note that the bad bisection
576 ref refs/bisect/bad is added to the included commits (if it exists)
577 and the good bisection refs refs/bisect/good-* are added to the
578 excluded commits (if they exist). Thus, supposing there are no refs
579 in refs/bisect/, if
580 $ git rev-list --bisect foo ^bar ^baz
582 outputs midpoint, the output of the two commands
584 $ git rev-list foo ^midpoint
586 $ git rev-list midpoint ^bar ^baz
587 would be of roughly the same length. Finding the change which
589 introduces a regression is thus reduced to a binary search:
590 repeatedly generate and test new 'midpoint’s until the commit chain
591 is of length one. Cannot be combined with --first-parent.
592 --bisect-vars
594 This calculates the same as --bisect, except that refs in
595 refs/bisect/ are not used, and except that this outputs text ready
596 to be eval’ed by the shell. These lines will assign the name of the
597 midpoint revision to the variable bisect_rev, and the expected
598 number of commits to be tested after bisect_rev is tested to
599 bisect_nr, the expected number of commits to be tested if
600 bisect_rev turns out to be good to bisect_good, the expected number
601 of commits to be tested if bisect_rev turns out to be bad to
602 bisect_bad, and the number of commits we are bisecting right now to
603 bisect_all.
604 --bisect-all
606 This outputs all the commit objects between the included and
607 excluded commits, ordered by their distance to the included and
608 excluded commits. Refs in refs/bisect/ are not used. The farthest
609 from them is displayed first. (This is the only one displayed by
610 --bisect.)
611 This is useful because it makes it easy to choose a good commit to
613 test when you want to avoid to test some of them for some reason
614 (they may not compile for example).
615 This option can be used along with --bisect-vars, in this case,
617 after all the sorted commit objects, there will be the same text as
618 if --bisect-vars had been used alone.
619 Commit Ordering
621 By default, the commits are shown in reverse chronological order.
622 --date-order
624 Show no parents before all of its children are shown, but otherwise
625 show commits in the commit timestamp order.
626 --author-date-order
628 Show no parents before all of its children are shown, but otherwise
629 show commits in the author timestamp order.
630 --topo-order
632 Show no parents before all of its children are shown, and avoid
633 showing commits on multiple lines of history intermixed.
634 For example, in a commit history like this:
636 ---1----2----4----7
638 \ \
639 3----5----6----8---
640 where the numbers denote the order of commit timestamps, git
642 rev-list and friends with --date-order show the commits in the
643 timestamp order: 8 7 6 5 4 3 2 1.
644 With --topo-order, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5
646 3 1); some older commits are shown before newer ones in order to
647 avoid showing the commits from two parallel development track mixed
648 together.
649 --reverse
651 Output the commits chosen to be shown (see Commit Limiting section
652 above) in reverse order. Cannot be combined with --walk-reflogs.
653 Object Traversal
655 These options are mostly targeted for packing of Git repositories.
656 --objects
658 Print the object IDs of any object referenced by the listed
659 commits. --objects foo ^bar thus means “send me all object IDs
660 which I need to download if I have the commit object bar but not
661 foo”.
662 --in-commit-order
664 Print tree and blob ids in order of the commits. The tree and blob
665 ids are printed after they are first referenced by a commit.
666 --objects-edge
668 Similar to --objects, but also print the IDs of excluded commits
669 prefixed with a “-” character. This is used by git-pack-objects(1)
670 to build a “thin” pack, which records objects in deltified form
671 based on objects contained in these excluded commits to reduce
672 network traffic.
673 --objects-edge-aggressive
675 Similar to --objects-edge, but it tries harder to find excluded
676 commits at the cost of increased time. This is used instead of
677 --objects-edge to build “thin” packs for shallow repositories.
678 --indexed-objects
680 Pretend as if all trees and blobs used by the index are listed on
681 the command line. Note that you probably want to use --objects,
682 too.
683 --unpacked
685 Only useful with --objects; print the object IDs that are not in
686 packs.
687 --object-names
689 Only useful with --objects; print the names of the object IDs that
690 are found. This is the default behavior.
691 --no-object-names
693 Only useful with --objects; does not print the names of the object
694 IDs that are found. This inverts --object-names. This flag allows
695 the output to be more easily parsed by commands such as git-cat-
696 file(1).
697 --filter=<filter-spec>
699 Only useful with one of the --objects*; omits objects (usually
700 blobs) from the list of printed objects. The <filter-spec> may be
701 one of the following:
702 The form --filter=blob:none omits all blobs.
704 The form --filter=blob:limit=<n>[kmg] omits blobs larger than n
706 bytes or units. n may be zero. The suffixes k, m, and g can be used
707 to name units in KiB, MiB, or GiB. For example, blob:limit=1k is
708 the same as blob:limit=1024.
709 The form --filter=sparse:oid=<blob-ish> uses a sparse-checkout
711 specification contained in the blob (or blob-expression) <blob-ish>
712 to omit blobs that would not be not required for a sparse checkout
713 on the requested refs.
714 The form --filter=tree:<depth> omits all blobs and trees whose
716 depth from the root tree is >= <depth> (minimum depth if an object
717 is located at multiple depths in the commits traversed). <depth>=0
718 will not include any trees or blobs unless included explicitly in
719 the command-line (or standard input when --stdin is used).
720 <depth>=1 will include only the tree and blobs which are referenced
721 directly by a commit reachable from <commit> or an explicitly-given
722 object. <depth>=2 is like <depth>=1 while also including trees and
723 blobs one more level removed from an explicitly-given commit or
724 tree.
725 Note that the form --filter=sparse:path=<path> that wants to read
727 from an arbitrary path on the filesystem has been dropped for
728 security reasons.
729 Multiple --filter= flags can be specified to combine filters. Only
731 objects which are accepted by every filter are included.
732 The form --filter=combine:<filter1>+<filter2>+...<filterN> can also
734 be used to combined several filters, but this is harder than just
735 repeating the --filter flag and is usually not necessary. Filters
736 are joined by + and individual filters are %-encoded (i.e.
737 URL-encoded). Besides the + and % characters, the following
738 characters are reserved and also must be encoded:
739 ~!@#$^&*()[]{}\;",<>?'` as well as all characters with ASCII code
740 <= 0x20, which includes space and newline.
741 Other arbitrary characters can also be encoded. For instance,
743 combine:tree:3+blob:none and combine:tree%3A3+blob%3Anone are
744 equivalent.
745 --no-filter
747 Turn off any previous --filter= argument.
748 --filter-print-omitted
750 Only useful with --filter=; prints a list of the objects omitted by
751 the filter. Object IDs are prefixed with a “~” character.
752 --missing=<missing-action>
754 A debug option to help with future "partial clone" development.
755 This option specifies how missing objects are handled.
756 The form --missing=error requests that rev-list stop with an error
758 if a missing object is encountered. This is the default action.
759 The form --missing=allow-any will allow object traversal to
761 continue if a missing object is encountered. Missing objects will
762 silently be omitted from the results.
763 The form --missing=allow-promisor is like allow-any, but will only
765 allow object traversal to continue for EXPECTED promisor missing
766 objects. Unexpected missing objects will raise an error.
767 The form --missing=print is like allow-any, but will also print a
769 list of the missing objects. Object IDs are prefixed with a “?”
770 character.
771 --exclude-promisor-objects
773 (For internal use only.) Prefilter object traversal at promisor
774 boundary. This is used with partial clone. This is stronger than
775 --missing=allow-promisor because it limits the traversal, rather
776 than just silencing errors about missing objects.
777 --no-walk[=(sorted|unsorted)]
779 Only show the given commits, but do not traverse their ancestors.
780 This has no effect if a range is specified. If the argument
781 unsorted is given, the commits are shown in the order they were
782 given on the command line. Otherwise (if sorted or no argument was
783 given), the commits are shown in reverse chronological order by
784 commit time. Cannot be combined with --graph.
785 --do-walk
787 Overrides a previous --no-walk.
788 Commit Formatting
790 Using these options, git-rev-list(1) will act similar to the more
791 specialized family of commit log tools: git-log(1), git-show(1), and
792 git-whatchanged(1)
793 --pretty[=<format>], --format=<format>
795 Pretty-print the contents of the commit logs in a given format,
796 where <format> can be one of oneline, short, medium, full, fuller,
797 email, raw, format:<string> and tformat:<string>. When <format> is
798 none of the above, and has %placeholder in it, it acts as if
799 --pretty=tformat:<format> were given.
800 See the "PRETTY FORMATS" section for some additional details for
802 each format. When =<format> part is omitted, it defaults to medium.
803 Note: you can specify the default pretty format in the repository
805 configuration (see git-config(1)).
806 --abbrev-commit
808 Instead of showing the full 40-byte hexadecimal commit object name,
809 show only a partial prefix. Non default number of digits can be
810 specified with "--abbrev=<n>" (which also modifies diff output, if
811 it is displayed).
812 This should make "--pretty=oneline" a whole lot more readable for
814 people using 80-column terminals.
815 --no-abbrev-commit
817 Show the full 40-byte hexadecimal commit object name. This negates
818 --abbrev-commit and those options which imply it such as
819 "--oneline". It also overrides the log.abbrevCommit variable.
820 --oneline
822 This is a shorthand for "--pretty=oneline --abbrev-commit" used
823 together.
824 --encoding=<encoding>
826 The commit objects record the encoding used for the log message in
827 their encoding header; this option can be used to tell the command
828 to re-code the commit log message in the encoding preferred by the
829 user. For non plumbing commands this defaults to UTF-8. Note that
830 if an object claims to be encoded in X and we are outputting in X,
831 we will output the object verbatim; this means that invalid
832 sequences in the original commit may be copied to the output.
833 --expand-tabs=<n>, --expand-tabs, --no-expand-tabs
835 Perform a tab expansion (replace each tab with enough spaces to
836 fill to the next display column that is multiple of <n>) in the log
837 message before showing it in the output. --expand-tabs is a
838 short-hand for --expand-tabs=8, and --no-expand-tabs is a
839 short-hand for --expand-tabs=0, which disables tab expansion.
840 By default, tabs are expanded in pretty formats that indent the log
842 message by 4 spaces (i.e. medium, which is the default, full, and
843 fuller).
844 --show-signature
846 Check the validity of a signed commit object by passing the
847 signature to gpg --verify and show the output.
848 --relative-date
850 Synonym for --date=relative.
851 --date=<format>
853 Only takes effect for dates shown in human-readable format, such as
854 when using --pretty. log.date config variable sets a default value
855 for the log command’s --date option. By default, dates are shown in
856 the original time zone (either committer’s or author’s). If -local
857 is appended to the format (e.g., iso-local), the user’s local time
858 zone is used instead.
859 --date=relative shows dates relative to the current time, e.g. “2
861 hours ago”. The -local option has no effect for --date=relative.
862 --date=local is an alias for --date=default-local.
864 --date=iso (or --date=iso8601) shows timestamps in a ISO 8601-like
866 format. The differences to the strict ISO 8601 format are:
867 · a space instead of the T date/time delimiter
869 · a space between time and time zone
871 · no colon between hours and minutes of the time zone
873 --date=iso-strict (or --date=iso8601-strict) shows timestamps in
875 strict ISO 8601 format.
876 --date=rfc (or --date=rfc2822) shows timestamps in RFC 2822 format,
878 often found in email messages.
879 --date=short shows only the date, but not the time, in YYYY-MM-DD
881 format.
882 --date=raw shows the date as seconds since the epoch (1970-01-01
884 00:00:00 UTC), followed by a space, and then the timezone as an
885 offset from UTC (a + or - with four digits; the first two are
886 hours, and the second two are minutes). I.e., as if the timestamp
887 were formatted with strftime("%s %z")). Note that the -local option
888 does not affect the seconds-since-epoch value (which is always
889 measured in UTC), but does switch the accompanying timezone value.
890 --date=human shows the timezone if the timezone does not match the
892 current time-zone, and doesn’t print the whole date if that matches
893 (ie skip printing year for dates that are "this year", but also
894 skip the whole date itself if it’s in the last few days and we can
895 just say what weekday it was). For older dates the hour and minute
896 is also omitted.
897 --date=unix shows the date as a Unix epoch timestamp (seconds since
899 1970). As with --raw, this is always in UTC and therefore -local
900 has no effect.
901 --date=format:... feeds the format ... to your system strftime,
903 except for %z and %Z, which are handled internally. Use
904 --date=format:%c to show the date in your system locale’s preferred
905 format. See the strftime manual for a complete list of format
906 placeholders. When using -local, the correct syntax is
907 --date=format-local:....
908 --date=default is the default format, and is similar to
910 --date=rfc2822, with a few exceptions:
911 · there is no comma after the day-of-week
913 · the time zone is omitted when the local time zone is used
915 --header
917 Print the contents of the commit in raw-format; each record is
918 separated with a NUL character.
919 --parents
921 Print also the parents of the commit (in the form "commit
922 parent..."). Also enables parent rewriting, see History
923 Simplification above.
924 --children
926 Print also the children of the commit (in the form "commit
927 child..."). Also enables parent rewriting, see History
928 Simplification above.
929 --timestamp
931 Print the raw commit timestamp.
932 --left-right
934 Mark which side of a symmetric difference a commit is reachable
935 from. Commits from the left side are prefixed with < and those from
936 the right with >. If combined with --boundary, those commits are
937 prefixed with -.
938 For example, if you have this topology:
940 y---b---b branch B
942 / \ /
943 / .
944 / / \
945 o---x---a---a branch A
946 you would get an output like this:
948 $ git rev-list --left-right --boundary --pretty=oneline A...B
950 >bbbbbbb... 3rd on b
952 >bbbbbbb... 2nd on b
953 <aaaaaaa... 3rd on a
954 <aaaaaaa... 2nd on a
955 -yyyyyyy... 1st on b
956 -xxxxxxx... 1st on a
957 --graph
960 Draw a text-based graphical representation of the commit history on
961 the left hand side of the output. This may cause extra lines to be
962 printed in between commits, in order for the graph history to be
963 drawn properly. Cannot be combined with --no-walk.
964 This enables parent rewriting, see History Simplification above.
966 This implies the --topo-order option by default, but the
968 --date-order option may also be specified.
969 --show-linear-break[=<barrier>]
971 When --graph is not used, all history branches are flattened which
972 can make it hard to see that the two consecutive commits do not
973 belong to a linear branch. This option puts a barrier in between
974 them in that case. If <barrier> is specified, it is the string that
975 will be shown instead of the default one.
976 --count
978 Print a number stating how many commits would have been listed, and
979 suppress all other output. When used together with --left-right,
980 instead print the counts for left and right commits, separated by a
981 tab. When used together with --cherry-mark, omit patch equivalent
982 commits from these counts and print the count for equivalent
983 commits separated by a tab.
984
986 If the commit is a merge, and if the pretty-format is not oneline,
987 email or raw, an additional line is inserted before the Author: line.
988 This line begins with "Merge: " and the sha1s of ancestral commits are
989 printed, separated by spaces. Note that the listed commits may not
990 necessarily be the list of the direct parent commits if you have
991 limited your view of history: for example, if you are only interested
992 in changes related to a certain directory or file.
993 There are several built-in formats, and you can define additional
995 formats by setting a pretty.<name> config option to either another
996 format name, or a format: string, as described below (see git-
997 config(1)). Here are the details of the built-in formats:
998 · oneline
1000 <sha1> <title line>
1002 This is designed to be as compact as possible.
1004 · short
1006 commit <sha1>
1008 Author: <author>
1009 <title line>
1011 · medium
1013 commit <sha1>
1015 Author: <author>
1016 Date: <author date>
1017 <title line>
1019 <full commit message>
1021 · full
1023 commit <sha1>
1025 Author: <author>
1026 Commit: <committer>
1027 <title line>
1029 <full commit message>
1031 · fuller
1033 commit <sha1>
1035 Author: <author>
1036 AuthorDate: <author date>
1037 Commit: <committer>
1038 CommitDate: <committer date>
1039 <title line>
1041 <full commit message>
1043 · email
1045 From <sha1> <date>
1047 From: <author>
1048 Date: <author date>
1049 Subject: [PATCH] <title line>
1050 <full commit message>
1052 · raw
1054 The raw format shows the entire commit exactly as stored in the
1056 commit object. Notably, the SHA-1s are displayed in full,
1057 regardless of whether --abbrev or --no-abbrev are used, and parents
1058 information show the true parent commits, without taking grafts or
1059 history simplification into account. Note that this format affects
1060 the way commits are displayed, but not the way the diff is shown
1061 e.g. with git log --raw. To get full object names in a raw diff
1062 format, use --no-abbrev.
1063 · format:<string>
1065 The format:<string> format allows you to specify which information
1067 you want to show. It works a little bit like printf format, with
1068 the notable exception that you get a newline with %n instead of \n.
1069 E.g, format:"The author of %h was %an, %ar%nThe title was >>%s<<%n"
1071 would show something like this:
1072 The author of fe6e0ee was Junio C Hamano, 23 hours ago
1074 The title was >>t4119: test autocomputing -p<n> for traditional diff input.<<
1075 The placeholders are:
1077 · Placeholders that expand to a single literal character:
1079 %n
1081 newline
1082 %%
1084 a raw %
1085 %x00
1087 print a byte from a hex code
1088 · Placeholders that affect formatting of later placeholders:
1090 %Cred
1092 switch color to red
1093 %Cgreen
1095 switch color to green
1096 %Cblue
1098 switch color to blue
1099 %Creset
1101 reset color
1102 %C(...)
1104 color specification, as described under Values in the
1105 "CONFIGURATION FILE" section of git-config(1). By default,
1106 colors are shown only when enabled for log output (by
1107 color.diff, color.ui, or --color, and respecting the auto
1108 settings of the former if we are going to a terminal).
1109 %C(auto,...) is accepted as a historical synonym for the
1110 default (e.g., %C(auto,red)). Specifying %C(always,...)
1111 will show the colors even when color is not otherwise
1112 enabled (though consider just using --color=always to
1113 enable color for the whole output, including this format
1114 and anything else git might color). auto alone (i.e.
1115 %C(auto)) will turn on auto coloring on the next
1116 placeholders until the color is switched again.
1117 %m
1119 left (<), right (>) or boundary (-) mark
1120 %w([<w>[,<i1>[,<i2>]]])
1122 switch line wrapping, like the -w option of git-
1123 shortlog(1).
1124 %<(<N>[,trunc|ltrunc|mtrunc])
1126 make the next placeholder take at least N columns, padding
1127 spaces on the right if necessary. Optionally truncate at
1128 the beginning (ltrunc), the middle (mtrunc) or the end
1129 (trunc) if the output is longer than N columns. Note that
1130 truncating only works correctly with N >= 2.
1131 %<|(<N>)
1133 make the next placeholder take at least until Nth columns,
1134 padding spaces on the right if necessary
1135 %>(<N>), %>|(<N>)
1137 similar to %<(<N>), %<|(<N>) respectively, but padding
1138 spaces on the left
1139 %>>(<N>), %>>|(<N>)
1141 similar to %>(<N>), %>|(<N>) respectively, except that if
1142 the next placeholder takes more spaces than given and there
1143 are spaces on its left, use those spaces
1144 %><(<N>), %><|(<N>)
1146 similar to %<(<N>), %<|(<N>) respectively, but padding both
1147 sides (i.e. the text is centered)
1148 · Placeholders that expand to information extracted from the
1150 commit:
1151 %H
1153 commit hash
1154 %h
1156 abbreviated commit hash
1157 %T
1159 tree hash
1160 %t
1162 abbreviated tree hash
1163 %P
1165 parent hashes
1166 %p
1168 abbreviated parent hashes
1169 %an
1171 author name
1172 %aN
1174 author name (respecting .mailmap, see git-shortlog(1) or
1175 git-blame(1))
1176 %ae
1178 author email
1179 %aE
1181 author email (respecting .mailmap, see git-shortlog(1) or
1182 git-blame(1))
1183 %ad
1185 author date (format respects --date= option)
1186 %aD
1188 author date, RFC2822 style
1189 %ar
1191 author date, relative
1192 %at
1194 author date, UNIX timestamp
1195 %ai
1197 author date, ISO 8601-like format
1198 %aI
1200 author date, strict ISO 8601 format
1201 %cn
1203 committer name
1204 %cN
1206 committer name (respecting .mailmap, see git-shortlog(1) or
1207 git-blame(1))
1208 %ce
1210 committer email
1211 %cE
1213 committer email (respecting .mailmap, see git-shortlog(1)
1214 or git-blame(1))
1215 %cd
1217 committer date (format respects --date= option)
1218 %cD
1220 committer date, RFC2822 style
1221 %cr
1223 committer date, relative
1224 %ct
1226 committer date, UNIX timestamp
1227 %ci
1229 committer date, ISO 8601-like format
1230 %cI
1232 committer date, strict ISO 8601 format
1233 %d
1235 ref names, like the --decorate option of git-log(1)
1236 %D
1238 ref names without the " (", ")" wrapping.
1239 %S
1241 ref name given on the command line by which the commit was
1242 reached (like git log --source), only works with git log
1243 %e
1245 encoding
1246 %s
1248 subject
1249 %f
1251 sanitized subject line, suitable for a filename
1252 %b
1254 body
1255 %B
1257 raw body (unwrapped subject and body)
1258 %GG
1260 raw verification message from GPG for a signed commit
1261 %G?
1263 show "G" for a good (valid) signature, "B" for a bad
1264 signature, "U" for a good signature with unknown validity,
1265 "X" for a good signature that has expired, "Y" for a good
1266 signature made by an expired key, "R" for a good signature
1267 made by a revoked key, "E" if the signature cannot be
1268 checked (e.g. missing key) and "N" for no signature
1269 %GS
1271 show the name of the signer for a signed commit
1272 %GK
1274 show the key used to sign a signed commit
1275 %GF
1277 show the fingerprint of the key used to sign a signed
1278 commit
1279 %GP
1281 show the fingerprint of the primary key whose subkey was
1282 used to sign a signed commit
1283 %gD
1285 reflog selector, e.g., refs/stash@{1} or refs/stash@{2
1286 minutes ago}; the format follows the rules described for
1287 the -g option. The portion before the @ is the refname as
1288 given on the command line (so git log -g refs/heads/master
1289 would yield refs/heads/master@{0}).
1290 %gd
1292 shortened reflog selector; same as %gD, but the refname
1293 portion is shortened for human readability (so
1294 refs/heads/master becomes just master).
1295 %gn
1297 reflog identity name
1298 %gN
1300 reflog identity name (respecting .mailmap, see git-
1301 shortlog(1) or git-blame(1))
1302 %ge
1304 reflog identity email
1305 %gE
1307 reflog identity email (respecting .mailmap, see git-
1308 shortlog(1) or git-blame(1))
1309 %gs
1311 reflog subject
1312 %(trailers[:options])
1314 display the trailers of the body as interpreted by git-
1315 interpret-trailers(1). The trailers string may be followed
1316 by a colon and zero or more comma-separated options:
1317 · key=<K>: only show trailers with specified key.
1319 Matching is done case-insensitively and trailing colon
1320 is optional. If option is given multiple times trailer
1321 lines matching any of the keys are shown. This option
1322 automatically enables the only option so that
1323 non-trailer lines in the trailer block are hidden. If
1324 that is not desired it can be disabled with only=false.
1325 E.g., %(trailers:key=Reviewed-by) shows trailer lines
1326 with key Reviewed-by.
1327 · only[=val]: select whether non-trailer lines from the
1329 trailer block should be included. The only keyword may
1330 optionally be followed by an equal sign and one of
1331 true, on, yes to omit or false, off, no to show the
1332 non-trailer lines. If option is given without value it
1333 is enabled. If given multiple times the last value is
1334 used.
1335 · separator=<SEP>: specify a separator inserted between
1337 trailer lines. When this option is not given each
1338 trailer line is terminated with a line feed character.
1339 The string SEP may contain the literal formatting codes
1340 described above. To use comma as separator one must use
1341 %x2C as it would otherwise be parsed as next option. If
1342 separator option is given multiple times only the last
1343 one is used. E.g., %(trailers:key=Ticket,separator=%x2C
1344 ) shows all trailer lines whose key is "Ticket"
1345 separated by a comma and a space.
1346 · unfold[=val]: make it behave as if interpret-trailer’s
1348 --unfold option was given. In same way as to for only
1349 it can be followed by an equal sign and explicit value.
1350 E.g., %(trailers:only,unfold=true) unfolds and shows
1351 all trailer lines.
1352 · valueonly[=val]: skip over the key part of the trailer
1354 line and only show the value part. Also this optionally
1355 allows explicit value.
1356 Note
1358 Some placeholders may depend on other options given to the revision
1359 traversal engine. For example, the %g* reflog options will insert
1360 an empty string unless we are traversing reflog entries (e.g., by
1361 git log -g). The %d and %D placeholders will use the "short"
1362 decoration format if --decorate was not already provided on the
1363 command line.
1364 If you add a + (plus sign) after % of a placeholder, a line-feed is
1366 inserted immediately before the expansion if and only if the
1367 placeholder expands to a non-empty string.
1368 If you add a - (minus sign) after % of a placeholder, all consecutive
1370 line-feeds immediately preceding the expansion are deleted if and only
1371 if the placeholder expands to an empty string.
1372 If you add a ` ` (space) after % of a placeholder, a space is inserted
1374 immediately before the expansion if and only if the placeholder expands
1375 to a non-empty string.
1376 · tformat:
1378 The tformat: format works exactly like format:, except that it
1380 provides "terminator" semantics instead of "separator" semantics.
1381 In other words, each commit has the message terminator character
1382 (usually a newline) appended, rather than a separator placed
1383 between entries. This means that the final entry of a single-line
1384 format will be properly terminated with a new line, just as the
1385 "oneline" format does. For example:
1386 $ git log -2 --pretty=format:%h 4da45bef \
1388 | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
1389 4da45be
1390 7134973 -- NO NEWLINE
1391 $ git log -2 --pretty=tformat:%h 4da45bef \
1393 | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
1394 4da45be
1395 7134973
1396 In addition, any unrecognized string that has a % in it is
1398 interpreted as if it has tformat: in front of it. For example,
1399 these two are equivalent:
1400 $ git log -2 --pretty=tformat:%h 4da45bef
1402 $ git log -2 --pretty=%h 4da45bef
1403
1406 Part of the git(1) suite
1407Git 2.24.1 12/10/2019 GIT-REV-LIST(1)