1GIT-REV-LIST(1)                   Git Manual                   GIT-REV-LIST(1)
2
3
4

NAME

6       git-rev-list - Lists commit objects in reverse chronological order
7

SYNOPSIS

9       git rev-list [<options>] <commit>... [[--] <path>...]
10

DESCRIPTION

12       List commits that are reachable by following the parent links from the
13       given commit(s), but exclude commits that are reachable from the one(s)
14       given with a ^ in front of them. The output is given in reverse
15       chronological order by default.
16
17       You can think of this as a set operation. Commits reachable from any of
18       the commits given on the command line form a set, and then commits
19       reachable from any of the ones given with ^ in front are subtracted
20       from that set. The remaining commits are what comes out in the
21       command’s output. Various other options and paths parameters can be
22       used to further limit the result.
23
24       Thus, the following command:
25
26           $ git rev-list foo bar ^baz
27
28       means "list all the commits which are reachable from foo or bar, but
29       not from baz".
30
31       A special notation "<commit1>..<commit2>" can be used as a short-hand
32       for "^<commit1> <commit2>". For example, either of the following may be
33       used interchangeably:
34
35           $ git rev-list origin..HEAD
36           $ git rev-list HEAD ^origin
37
38       Another special notation is "<commit1>...<commit2>" which is useful for
39       merges. The resulting set of commits is the symmetric difference
40       between the two operands. The following two commands are equivalent:
41
42           $ git rev-list A B --not $(git merge-base --all A B)
43           $ git rev-list A...B
44
45       rev-list is a very essential Git command, since it provides the ability
46       to build and traverse commit ancestry graphs. For this reason, it has a
47       lot of different options that enables it to be used by commands as
48       different as git bisect and git repack.
49

OPTIONS

51   Commit Limiting
52       Besides specifying a range of commits that should be listed using the
53       special notations explained in the description, additional commit
54       limiting may be applied.
55
56       Using more options generally further limits the output (e.g.
57       --since=<date1> limits to commits newer than <date1>, and using it with
58       --grep=<pattern> further limits to commits whose log message has a line
59       that matches <pattern>), unless otherwise noted.
60
61       Note that these are applied before commit ordering and formatting
62       options, such as --reverse.
63
64       -<number>, -n <number>, --max-count=<number>
65           Limit the number of commits to output.
66
67       --skip=<number>
68           Skip number commits before starting to show the commit output.
69
70       --since=<date>, --after=<date>
71           Show commits more recent than a specific date.
72
73       --until=<date>, --before=<date>
74           Show commits older than a specific date.
75
76       --max-age=<timestamp>, --min-age=<timestamp>
77           Limit the commits output to specified time range.
78
79       --author=<pattern>, --committer=<pattern>
80           Limit the commits output to ones with author/committer header lines
81           that match the specified pattern (regular expression). With more
82           than one --author=<pattern>, commits whose author matches any of
83           the given patterns are chosen (similarly for multiple
84           --committer=<pattern>).
85
86       --grep-reflog=<pattern>
87           Limit the commits output to ones with reflog entries that match the
88           specified pattern (regular expression). With more than one
89           --grep-reflog, commits whose reflog message matches any of the
90           given patterns are chosen. It is an error to use this option unless
91           --walk-reflogs is in use.
92
93       --grep=<pattern>
94           Limit the commits output to ones with log message that matches the
95           specified pattern (regular expression). With more than one
96           --grep=<pattern>, commits whose message matches any of the given
97           patterns are chosen (but see --all-match).
98
99       --all-match
100           Limit the commits output to ones that match all given --grep,
101           instead of ones that match at least one.
102
103       --invert-grep
104           Limit the commits output to ones with log message that do not match
105           the pattern specified with --grep=<pattern>.
106
107       -i, --regexp-ignore-case
108           Match the regular expression limiting patterns without regard to
109           letter case.
110
111       --basic-regexp
112           Consider the limiting patterns to be basic regular expressions;
113           this is the default.
114
115       -E, --extended-regexp
116           Consider the limiting patterns to be extended regular expressions
117           instead of the default basic regular expressions.
118
119       -F, --fixed-strings
120           Consider the limiting patterns to be fixed strings (don’t interpret
121           pattern as a regular expression).
122
123       -P, --perl-regexp
124           Consider the limiting patterns to be Perl-compatible regular
125           expressions.
126
127           Support for these types of regular expressions is an optional
128           compile-time dependency. If Git wasn’t compiled with support for
129           them providing this option will cause it to die.
130
131       --remove-empty
132           Stop when a given path disappears from the tree.
133
134       --merges
135           Print only merge commits. This is exactly the same as
136           --min-parents=2.
137
138       --no-merges
139           Do not print commits with more than one parent. This is exactly the
140           same as --max-parents=1.
141
142       --min-parents=<number>, --max-parents=<number>, --no-min-parents,
143       --no-max-parents
144           Show only commits which have at least (or at most) that many parent
145           commits. In particular, --max-parents=1 is the same as --no-merges,
146           --min-parents=2 is the same as --merges.  --max-parents=0 gives all
147           root commits and --min-parents=3 all octopus merges.
148
149           --no-min-parents and --no-max-parents reset these limits (to no
150           limit) again. Equivalent forms are --min-parents=0 (any commit has
151           0 or more parents) and --max-parents=-1 (negative numbers denote no
152           upper limit).
153
154       --first-parent
155           When finding commits to include, follow only the first parent
156           commit upon seeing a merge commit. This option can give a better
157           overview when viewing the evolution of a particular topic branch,
158           because merges into a topic branch tend to be only about adjusting
159           to updated upstream from time to time, and this option allows you
160           to ignore the individual commits brought in to your history by such
161           a merge.
162
163       --exclude-first-parent-only
164           When finding commits to exclude (with a ^), follow only the first
165           parent commit upon seeing a merge commit. This can be used to find
166           the set of changes in a topic branch from the point where it
167           diverged from the remote branch, given that arbitrary merges can be
168           valid topic branch changes.
169
170       --not
171           Reverses the meaning of the ^ prefix (or lack thereof) for all
172           following revision specifiers, up to the next --not.
173
174       --all
175           Pretend as if all the refs in refs/, along with HEAD, are listed on
176           the command line as <commit>.
177
178       --branches[=<pattern>]
179           Pretend as if all the refs in refs/heads are listed on the command
180           line as <commit>. If <pattern> is given, limit branches to ones
181           matching given shell glob. If pattern lacks ?, *, or [, /* at the
182           end is implied.
183
184       --tags[=<pattern>]
185           Pretend as if all the refs in refs/tags are listed on the command
186           line as <commit>. If <pattern> is given, limit tags to ones
187           matching given shell glob. If pattern lacks ?, *, or [, /* at the
188           end is implied.
189
190       --remotes[=<pattern>]
191           Pretend as if all the refs in refs/remotes are listed on the
192           command line as <commit>. If <pattern> is given, limit
193           remote-tracking branches to ones matching given shell glob. If
194           pattern lacks ?, *, or [, /* at the end is implied.
195
196       --glob=<glob-pattern>
197           Pretend as if all the refs matching shell glob <glob-pattern> are
198           listed on the command line as <commit>. Leading refs/, is
199           automatically prepended if missing. If pattern lacks ?, *, or [, /*
200           at the end is implied.
201
202       --exclude=<glob-pattern>
203           Do not include refs matching <glob-pattern> that the next --all,
204           --branches, --tags, --remotes, or --glob would otherwise consider.
205           Repetitions of this option accumulate exclusion patterns up to the
206           next --all, --branches, --tags, --remotes, or --glob option (other
207           options or arguments do not clear accumulated patterns).
208
209           The patterns given should not begin with refs/heads, refs/tags, or
210           refs/remotes when applied to --branches, --tags, or --remotes,
211           respectively, and they must begin with refs/ when applied to --glob
212           or --all. If a trailing /* is intended, it must be given
213           explicitly.
214
215       --reflog
216           Pretend as if all objects mentioned by reflogs are listed on the
217           command line as <commit>.
218
219       --alternate-refs
220           Pretend as if all objects mentioned as ref tips of alternate
221           repositories were listed on the command line. An alternate
222           repository is any repository whose object directory is specified in
223           objects/info/alternates. The set of included objects may be
224           modified by core.alternateRefsCommand, etc. See git-config(1).
225
226       --single-worktree
227           By default, all working trees will be examined by the following
228           options when there are more than one (see git-worktree(1)): --all,
229           --reflog and --indexed-objects. This option forces them to examine
230           the current working tree only.
231
232       --ignore-missing
233           Upon seeing an invalid object name in the input, pretend as if the
234           bad input was not given.
235
236       --stdin
237           In addition to the <commit> listed on the command line, read them
238           from the standard input. If a -- separator is seen, stop reading
239           commits and start reading paths to limit the result.
240
241       --quiet
242           Don’t print anything to standard output. This form is primarily
243           meant to allow the caller to test the exit status to see if a range
244           of objects is fully connected (or not). It is faster than
245           redirecting stdout to /dev/null as the output does not have to be
246           formatted.
247
248       --disk-usage
249           Suppress normal output; instead, print the sum of the bytes used
250           for on-disk storage by the selected commits or objects. This is
251           equivalent to piping the output into git cat-file
252           --batch-check='%(objectsize:disk)', except that it runs much faster
253           (especially with --use-bitmap-index). See the CAVEATS section in
254           git-cat-file(1) for the limitations of what "on-disk storage"
255           means.
256
257       --cherry-mark
258           Like --cherry-pick (see below) but mark equivalent commits with =
259           rather than omitting them, and inequivalent ones with +.
260
261       --cherry-pick
262           Omit any commit that introduces the same change as another commit
263           on the “other side” when the set of commits are limited with
264           symmetric difference.
265
266           For example, if you have two branches, A and B, a usual way to list
267           all commits on only one side of them is with --left-right (see the
268           example below in the description of the --left-right option).
269           However, it shows the commits that were cherry-picked from the
270           other branch (for example, “3rd on b” may be cherry-picked from
271           branch A). With this option, such pairs of commits are excluded
272           from the output.
273
274       --left-only, --right-only
275           List only commits on the respective side of a symmetric difference,
276           i.e. only those which would be marked < resp.  > by --left-right.
277
278           For example, --cherry-pick --right-only A...B omits those commits
279           from B which are in A or are patch-equivalent to a commit in A. In
280           other words, this lists the + commits from git cherry A B. More
281           precisely, --cherry-pick --right-only --no-merges gives the exact
282           list.
283
284       --cherry
285           A synonym for --right-only --cherry-mark --no-merges; useful to
286           limit the output to the commits on our side and mark those that
287           have been applied to the other side of a forked history with git
288           log --cherry upstream...mybranch, similar to git cherry upstream
289           mybranch.
290
291       -g, --walk-reflogs
292           Instead of walking the commit ancestry chain, walk reflog entries
293           from the most recent one to older ones. When this option is used
294           you cannot specify commits to exclude (that is, ^commit,
295           commit1..commit2, and commit1...commit2 notations cannot be used).
296
297           With --pretty format other than oneline and reference (for obvious
298           reasons), this causes the output to have two extra lines of
299           information taken from the reflog. The reflog designator in the
300           output may be shown as ref@{Nth} (where Nth is the
301           reverse-chronological index in the reflog) or as ref@{timestamp}
302           (with the timestamp for that entry), depending on a few rules:
303
304            1. If the starting point is specified as ref@{Nth}, show the index
305               format.
306
307            2. If the starting point was specified as ref@{now}, show the
308               timestamp format.
309
310            3. If neither was used, but --date was given on the command line,
311               show the timestamp in the format requested by --date.
312
313            4. Otherwise, show the index format.
314
315           Under --pretty=oneline, the commit message is prefixed with this
316           information on the same line. This option cannot be combined with
317           --reverse. See also git-reflog(1).
318
319           Under --pretty=reference, this information will not be shown at
320           all.
321
322       --merge
323           After a failed merge, show refs that touch files having a conflict
324           and don’t exist on all heads to merge.
325
326       --boundary
327           Output excluded boundary commits. Boundary commits are prefixed
328           with -.
329
330       --use-bitmap-index
331           Try to speed up the traversal using the pack bitmap index (if one
332           is available). Note that when traversing with --objects, trees and
333           blobs will not have their associated path printed.
334
335       --progress=<header>
336           Show progress reports on stderr as objects are considered. The
337           <header> text will be printed with each progress update.
338
339   History Simplification
340       Sometimes you are only interested in parts of the history, for example
341       the commits modifying a particular <path>. But there are two parts of
342       History Simplification, one part is selecting the commits and the other
343       is how to do it, as there are various strategies to simplify the
344       history.
345
346       The following options select the commits to be shown:
347
348       <paths>
349           Commits modifying the given <paths> are selected.
350
351       --simplify-by-decoration
352           Commits that are referred by some branch or tag are selected.
353
354       Note that extra commits can be shown to give a meaningful history.
355
356       The following options affect the way the simplification is performed:
357
358       Default mode
359           Simplifies the history to the simplest history explaining the final
360           state of the tree. Simplest because it prunes some side branches if
361           the end result is the same (i.e. merging branches with the same
362           content)
363
364       --show-pulls
365           Include all commits from the default mode, but also any merge
366           commits that are not TREESAME to the first parent but are TREESAME
367           to a later parent. This mode is helpful for showing the merge
368           commits that "first introduced" a change to a branch.
369
370       --full-history
371           Same as the default mode, but does not prune some history.
372
373       --dense
374           Only the selected commits are shown, plus some to have a meaningful
375           history.
376
377       --sparse
378           All commits in the simplified history are shown.
379
380       --simplify-merges
381           Additional option to --full-history to remove some needless merges
382           from the resulting history, as there are no selected commits
383           contributing to this merge.
384
385       --ancestry-path
386           When given a range of commits to display (e.g.  commit1..commit2 or
387           commit2 ^commit1), only display commits that exist directly on the
388           ancestry chain between the commit1 and commit2, i.e. commits that
389           are both descendants of commit1, and ancestors of commit2.
390
391       A more detailed explanation follows.
392
393       Suppose you specified foo as the <paths>. We shall call commits that
394       modify foo !TREESAME, and the rest TREESAME. (In a diff filtered for
395       foo, they look different and equal, respectively.)
396
397       In the following, we will always refer to the same example history to
398       illustrate the differences between simplification settings. We assume
399       that you are filtering for a file foo in this commit graph:
400
401                     .-A---M---N---O---P---Q
402                    /     /   /   /   /   /
403                   I     B   C   D   E   Y
404                    \   /   /   /   /   /
405                     `-------------'   X
406
407       The horizontal line of history A---Q is taken to be the first parent of
408       each merge. The commits are:
409
410I is the initial commit, in which foo exists with contents “asdf”,
411           and a file quux exists with contents “quux”. Initial commits are
412           compared to an empty tree, so I is !TREESAME.
413
414       •   In A, foo contains just “foo”.
415
416B contains the same change as A. Its merge M is trivial and hence
417           TREESAME to all parents.
418
419C does not change foo, but its merge N changes it to “foobar”, so
420           it is not TREESAME to any parent.
421
422D sets foo to “baz”. Its merge O combines the strings from N and D
423           to “foobarbaz”; i.e., it is not TREESAME to any parent.
424
425E changes quux to “xyzzy”, and its merge P combines the strings to
426           “quux xyzzy”.  P is TREESAME to O, but not to E.
427
428X is an independent root commit that added a new file side, and Y
429           modified it.  Y is TREESAME to X. Its merge Q added side to P, and
430           Q is TREESAME to P, but not to Y.
431
432       rev-list walks backwards through history, including or excluding
433       commits based on whether --full-history and/or parent rewriting (via
434       --parents or --children) are used. The following settings are
435       available.
436
437       Default mode
438           Commits are included if they are not TREESAME to any parent (though
439           this can be changed, see --sparse below). If the commit was a
440           merge, and it was TREESAME to one parent, follow only that parent.
441           (Even if there are several TREESAME parents, follow only one of
442           them.) Otherwise, follow all parents.
443
444           This results in:
445
446                         .-A---N---O
447                        /     /   /
448                       I---------D
449
450           Note how the rule to only follow the TREESAME parent, if one is
451           available, removed B from consideration entirely.  C was considered
452           via N, but is TREESAME. Root commits are compared to an empty tree,
453           so I is !TREESAME.
454
455           Parent/child relations are only visible with --parents, but that
456           does not affect the commits selected in default mode, so we have
457           shown the parent lines.
458
459       --full-history without parent rewriting
460           This mode differs from the default in one point: always follow all
461           parents of a merge, even if it is TREESAME to one of them. Even if
462           more than one side of the merge has commits that are included, this
463           does not imply that the merge itself is! In the example, we get
464
465                       I  A  B  N  D  O  P  Q
466
467           M was excluded because it is TREESAME to both parents.  E, C and B
468           were all walked, but only B was !TREESAME, so the others do not
469           appear.
470
471           Note that without parent rewriting, it is not really possible to
472           talk about the parent/child relationships between the commits, so
473           we show them disconnected.
474
475       --full-history with parent rewriting
476           Ordinary commits are only included if they are !TREESAME (though
477           this can be changed, see --sparse below).
478
479           Merges are always included. However, their parent list is
480           rewritten: Along each parent, prune away commits that are not
481           included themselves. This results in
482
483                         .-A---M---N---O---P---Q
484                        /     /   /   /   /
485                       I     B   /   D   /
486                        \   /   /   /   /
487                         `-------------'
488
489           Compare to --full-history without rewriting above. Note that E was
490           pruned away because it is TREESAME, but the parent list of P was
491           rewritten to contain E's parent I. The same happened for C and N,
492           and X, Y and Q.
493
494       In addition to the above settings, you can change whether TREESAME
495       affects inclusion:
496
497       --dense
498           Commits that are walked are included if they are not TREESAME to
499           any parent.
500
501       --sparse
502           All commits that are walked are included.
503
504           Note that without --full-history, this still simplifies merges: if
505           one of the parents is TREESAME, we follow only that one, so the
506           other sides of the merge are never walked.
507
508       --simplify-merges
509           First, build a history graph in the same way that --full-history
510           with parent rewriting does (see above).
511
512           Then simplify each commit C to its replacement C' in the final
513           history according to the following rules:
514
515           •   Set C' to C.
516
517           •   Replace each parent P of C' with its simplification P'. In the
518               process, drop parents that are ancestors of other parents or
519               that are root commits TREESAME to an empty tree, and remove
520               duplicates, but take care to never drop all parents that we are
521               TREESAME to.
522
523           •   If after this parent rewriting, C' is a root or merge commit
524               (has zero or >1 parents), a boundary commit, or !TREESAME, it
525               remains. Otherwise, it is replaced with its only parent.
526
527           The effect of this is best shown by way of comparing to
528           --full-history with parent rewriting. The example turns into:
529
530                         .-A---M---N---O
531                        /     /       /
532                       I     B       D
533                        \   /       /
534                         `---------'
535
536           Note the major differences in N, P, and Q over --full-history:
537
538N's parent list had I removed, because it is an ancestor of the
539               other parent M. Still, N remained because it is !TREESAME.
540
541P's parent list similarly had I removed.  P was then removed
542               completely, because it had one parent and is TREESAME.
543
544Q's parent list had Y simplified to X.  X was then removed,
545               because it was a TREESAME root.  Q was then removed completely,
546               because it had one parent and is TREESAME.
547
548       There is another simplification mode available:
549
550       --ancestry-path
551           Limit the displayed commits to those directly on the ancestry chain
552           between the “from” and “to” commits in the given commit range. I.e.
553           only display commits that are ancestor of the “to” commit and
554           descendants of the “from” commit.
555
556           As an example use case, consider the following commit history:
557
558                           D---E-------F
559                          /     \       \
560                         B---C---G---H---I---J
561                        /                     \
562                       A-------K---------------L--M
563
564           A regular D..M computes the set of commits that are ancestors of M,
565           but excludes the ones that are ancestors of D. This is useful to
566           see what happened to the history leading to M since D, in the sense
567           that “what does M have that did not exist in D”. The result in this
568           example would be all the commits, except A and B (and D itself, of
569           course).
570
571           When we want to find out what commits in M are contaminated with
572           the bug introduced by D and need fixing, however, we might want to
573           view only the subset of D..M that are actually descendants of D,
574           i.e. excluding C and K. This is exactly what the --ancestry-path
575           option does. Applied to the D..M range, it results in:
576
577                               E-------F
578                                \       \
579                                 G---H---I---J
580                                              \
581                                               L--M
582
583       Before discussing another option, --show-pulls, we need to create a new
584       example history.
585
586       A common problem users face when looking at simplified history is that
587       a commit they know changed a file somehow does not appear in the file’s
588       simplified history. Let’s demonstrate a new example and show how
589       options such as --full-history and --simplify-merges works in that
590       case:
591
592                     .-A---M-----C--N---O---P
593                    /     / \  \  \/   /   /
594                   I     B   \  R-'`-Z'   /
595                    \   /     \/         /
596                     \ /      /\        /
597                      `---X--'  `---Y--'
598
599       For this example, suppose I created file.txt which was modified by A,
600       B, and X in different ways. The single-parent commits C, Z, and Y do
601       not change file.txt. The merge commit M was created by resolving the
602       merge conflict to include both changes from A and B and hence is not
603       TREESAME to either. The merge commit R, however, was created by
604       ignoring the contents of file.txt at M and taking only the contents of
605       file.txt at X. Hence, R is TREESAME to X but not M. Finally, the
606       natural merge resolution to create N is to take the contents of
607       file.txt at R, so N is TREESAME to R but not C. The merge commits O and
608       P are TREESAME to their first parents, but not to their second parents,
609       Z and Y respectively.
610
611       When using the default mode, N and R both have a TREESAME parent, so
612       those edges are walked and the others are ignored. The resulting
613       history graph is:
614
615                   I---X
616
617       When using --full-history, Git walks every edge. This will discover the
618       commits A and B and the merge M, but also will reveal the merge commits
619       O and P. With parent rewriting, the resulting graph is:
620
621                     .-A---M--------N---O---P
622                    /     / \  \  \/   /   /
623                   I     B   \  R-'`--'   /
624                    \   /     \/         /
625                     \ /      /\        /
626                      `---X--'  `------'
627
628       Here, the merge commits O and P contribute extra noise, as they did not
629       actually contribute a change to file.txt. They only merged a topic that
630       was based on an older version of file.txt. This is a common issue in
631       repositories using a workflow where many contributors work in parallel
632       and merge their topic branches along a single trunk: manu unrelated
633       merges appear in the --full-history results.
634
635       When using the --simplify-merges option, the commits O and P disappear
636       from the results. This is because the rewritten second parents of O and
637       P are reachable from their first parents. Those edges are removed and
638       then the commits look like single-parent commits that are TREESAME to
639       their parent. This also happens to the commit N, resulting in a history
640       view as follows:
641
642                     .-A---M--.
643                    /     /    \
644                   I     B      R
645                    \   /      /
646                     \ /      /
647                      `---X--'
648
649       In this view, we see all of the important single-parent changes from A,
650       B, and X. We also see the carefully-resolved merge M and the
651       not-so-carefully-resolved merge R. This is usually enough information
652       to determine why the commits A and B "disappeared" from history in the
653       default view. However, there are a few issues with this approach.
654
655       The first issue is performance. Unlike any previous option, the
656       --simplify-merges option requires walking the entire commit history
657       before returning a single result. This can make the option difficult to
658       use for very large repositories.
659
660       The second issue is one of auditing. When many contributors are working
661       on the same repository, it is important which merge commits introduced
662       a change into an important branch. The problematic merge R above is not
663       likely to be the merge commit that was used to merge into an important
664       branch. Instead, the merge N was used to merge R and X into the
665       important branch. This commit may have information about why the change
666       X came to override the changes from A and B in its commit message.
667
668       --show-pulls
669           In addition to the commits shown in the default history, show each
670           merge commit that is not TREESAME to its first parent but is
671           TREESAME to a later parent.
672
673           When a merge commit is included by --show-pulls, the merge is
674           treated as if it "pulled" the change from another branch. When
675           using --show-pulls on this example (and no other options) the
676           resulting graph is:
677
678                       I---X---R---N
679
680           Here, the merge commits R and N are included because they pulled
681           the commits X and R into the base branch, respectively. These
682           merges are the reason the commits A and B do not appear in the
683           default history.
684
685           When --show-pulls is paired with --simplify-merges, the graph
686           includes all of the necessary information:
687
688                         .-A---M--.   N
689                        /     /    \ /
690                       I     B      R
691                        \   /      /
692                         \ /      /
693                          `---X--'
694
695           Notice that since M is reachable from R, the edge from N to M was
696           simplified away. However, N still appears in the history as an
697           important commit because it "pulled" the change R into the main
698           branch.
699
700       The --simplify-by-decoration option allows you to view only the big
701       picture of the topology of the history, by omitting commits that are
702       not referenced by tags. Commits are marked as !TREESAME (in other
703       words, kept after history simplification rules described above) if (1)
704       they are referenced by tags, or (2) they change the contents of the
705       paths given on the command line. All other commits are marked as
706       TREESAME (subject to be simplified away).
707
708   Bisection Helpers
709       --bisect
710           Limit output to the one commit object which is roughly halfway
711           between included and excluded commits. Note that the bad bisection
712           ref refs/bisect/bad is added to the included commits (if it exists)
713           and the good bisection refs refs/bisect/good-* are added to the
714           excluded commits (if they exist). Thus, supposing there are no refs
715           in refs/bisect/, if
716
717                       $ git rev-list --bisect foo ^bar ^baz
718
719           outputs midpoint, the output of the two commands
720
721                       $ git rev-list foo ^midpoint
722                       $ git rev-list midpoint ^bar ^baz
723
724           would be of roughly the same length. Finding the change which
725           introduces a regression is thus reduced to a binary search:
726           repeatedly generate and test new 'midpoint’s until the commit chain
727           is of length one.
728
729       --bisect-vars
730           This calculates the same as --bisect, except that refs in
731           refs/bisect/ are not used, and except that this outputs text ready
732           to be eval’ed by the shell. These lines will assign the name of the
733           midpoint revision to the variable bisect_rev, and the expected
734           number of commits to be tested after bisect_rev is tested to
735           bisect_nr, the expected number of commits to be tested if
736           bisect_rev turns out to be good to bisect_good, the expected number
737           of commits to be tested if bisect_rev turns out to be bad to
738           bisect_bad, and the number of commits we are bisecting right now to
739           bisect_all.
740
741       --bisect-all
742           This outputs all the commit objects between the included and
743           excluded commits, ordered by their distance to the included and
744           excluded commits. Refs in refs/bisect/ are not used. The farthest
745           from them is displayed first. (This is the only one displayed by
746           --bisect.)
747
748           This is useful because it makes it easy to choose a good commit to
749           test when you want to avoid to test some of them for some reason
750           (they may not compile for example).
751
752           This option can be used along with --bisect-vars, in this case,
753           after all the sorted commit objects, there will be the same text as
754           if --bisect-vars had been used alone.
755
756   Commit Ordering
757       By default, the commits are shown in reverse chronological order.
758
759       --date-order
760           Show no parents before all of its children are shown, but otherwise
761           show commits in the commit timestamp order.
762
763       --author-date-order
764           Show no parents before all of its children are shown, but otherwise
765           show commits in the author timestamp order.
766
767       --topo-order
768           Show no parents before all of its children are shown, and avoid
769           showing commits on multiple lines of history intermixed.
770
771           For example, in a commit history like this:
772
773                   ---1----2----4----7
774                       \              \
775                        3----5----6----8---
776
777           where the numbers denote the order of commit timestamps, git
778           rev-list and friends with --date-order show the commits in the
779           timestamp order: 8 7 6 5 4 3 2 1.
780
781           With --topo-order, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5
782           3 1); some older commits are shown before newer ones in order to
783           avoid showing the commits from two parallel development track mixed
784           together.
785
786       --reverse
787           Output the commits chosen to be shown (see Commit Limiting section
788           above) in reverse order. Cannot be combined with --walk-reflogs.
789
790   Object Traversal
791       These options are mostly targeted for packing of Git repositories.
792
793       --objects
794           Print the object IDs of any object referenced by the listed
795           commits.  --objects foo ^bar thus means “send me all object IDs
796           which I need to download if I have the commit object bar but not
797           foo”.
798
799       --in-commit-order
800           Print tree and blob ids in order of the commits. The tree and blob
801           ids are printed after they are first referenced by a commit.
802
803       --objects-edge
804           Similar to --objects, but also print the IDs of excluded commits
805           prefixed with a “-” character. This is used by git-pack-objects(1)
806           to build a “thin” pack, which records objects in deltified form
807           based on objects contained in these excluded commits to reduce
808           network traffic.
809
810       --objects-edge-aggressive
811           Similar to --objects-edge, but it tries harder to find excluded
812           commits at the cost of increased time. This is used instead of
813           --objects-edge to build “thin” packs for shallow repositories.
814
815       --indexed-objects
816           Pretend as if all trees and blobs used by the index are listed on
817           the command line. Note that you probably want to use --objects,
818           too.
819
820       --unpacked
821           Only useful with --objects; print the object IDs that are not in
822           packs.
823
824       --object-names
825           Only useful with --objects; print the names of the object IDs that
826           are found. This is the default behavior.
827
828       --no-object-names
829           Only useful with --objects; does not print the names of the object
830           IDs that are found. This inverts --object-names. This flag allows
831           the output to be more easily parsed by commands such as git-cat-
832           file(1).
833
834       --filter=<filter-spec>
835           Only useful with one of the --objects*; omits objects (usually
836           blobs) from the list of printed objects. The <filter-spec> may be
837           one of the following:
838
839           The form --filter=blob:none omits all blobs.
840
841           The form --filter=blob:limit=<n>[kmg] omits blobs larger than n
842           bytes or units. n may be zero. The suffixes k, m, and g can be used
843           to name units in KiB, MiB, or GiB. For example, blob:limit=1k is
844           the same as blob:limit=1024.
845
846           The form --filter=object:type=(tag|commit|tree|blob) omits all
847           objects which are not of the requested type.
848
849           The form --filter=sparse:oid=<blob-ish> uses a sparse-checkout
850           specification contained in the blob (or blob-expression) <blob-ish>
851           to omit blobs that would not be required for a sparse checkout on
852           the requested refs.
853
854           The form --filter=tree:<depth> omits all blobs and trees whose
855           depth from the root tree is >= <depth> (minimum depth if an object
856           is located at multiple depths in the commits traversed). <depth>=0
857           will not include any trees or blobs unless included explicitly in
858           the command-line (or standard input when --stdin is used).
859           <depth>=1 will include only the tree and blobs which are referenced
860           directly by a commit reachable from <commit> or an explicitly-given
861           object. <depth>=2 is like <depth>=1 while also including trees and
862           blobs one more level removed from an explicitly-given commit or
863           tree.
864
865           Note that the form --filter=sparse:path=<path> that wants to read
866           from an arbitrary path on the filesystem has been dropped for
867           security reasons.
868
869           Multiple --filter= flags can be specified to combine filters. Only
870           objects which are accepted by every filter are included.
871
872           The form --filter=combine:<filter1>+<filter2>+...<filterN> can also
873           be used to combined several filters, but this is harder than just
874           repeating the --filter flag and is usually not necessary. Filters
875           are joined by + and individual filters are %-encoded (i.e.
876           URL-encoded). Besides the + and % characters, the following
877           characters are reserved and also must be encoded:
878           ~!@#$^&*()[]{}\;",<>?'` as well as all characters with ASCII code
879           <= 0x20, which includes space and newline.
880
881           Other arbitrary characters can also be encoded. For instance,
882           combine:tree:3+blob:none and combine:tree%3A3+blob%3Anone are
883           equivalent.
884
885       --no-filter
886           Turn off any previous --filter= argument.
887
888       --filter-provided-objects
889           Filter the list of explicitly provided objects, which would
890           otherwise always be printed even if they did not match any of the
891           filters. Only useful with --filter=.
892
893       --filter-print-omitted
894           Only useful with --filter=; prints a list of the objects omitted by
895           the filter. Object IDs are prefixed with a “~” character.
896
897       --missing=<missing-action>
898           A debug option to help with future "partial clone" development.
899           This option specifies how missing objects are handled.
900
901           The form --missing=error requests that rev-list stop with an error
902           if a missing object is encountered. This is the default action.
903
904           The form --missing=allow-any will allow object traversal to
905           continue if a missing object is encountered. Missing objects will
906           silently be omitted from the results.
907
908           The form --missing=allow-promisor is like allow-any, but will only
909           allow object traversal to continue for EXPECTED promisor missing
910           objects. Unexpected missing objects will raise an error.
911
912           The form --missing=print is like allow-any, but will also print a
913           list of the missing objects. Object IDs are prefixed with a “?”
914           character.
915
916       --exclude-promisor-objects
917           (For internal use only.) Prefilter object traversal at promisor
918           boundary. This is used with partial clone. This is stronger than
919           --missing=allow-promisor because it limits the traversal, rather
920           than just silencing errors about missing objects.
921
922       --no-walk[=(sorted|unsorted)]
923           Only show the given commits, but do not traverse their ancestors.
924           This has no effect if a range is specified. If the argument
925           unsorted is given, the commits are shown in the order they were
926           given on the command line. Otherwise (if sorted or no argument was
927           given), the commits are shown in reverse chronological order by
928           commit time. Cannot be combined with --graph.
929
930       --do-walk
931           Overrides a previous --no-walk.
932
933   Commit Formatting
934       Using these options, git-rev-list(1) will act similar to the more
935       specialized family of commit log tools: git-log(1), git-show(1), and
936       git-whatchanged(1)
937
938       --pretty[=<format>], --format=<format>
939           Pretty-print the contents of the commit logs in a given format,
940           where <format> can be one of oneline, short, medium, full, fuller,
941           reference, email, raw, format:<string> and tformat:<string>. When
942           <format> is none of the above, and has %placeholder in it, it acts
943           as if --pretty=tformat:<format> were given.
944
945           See the "PRETTY FORMATS" section for some additional details for
946           each format. When =<format> part is omitted, it defaults to medium.
947
948           Note: you can specify the default pretty format in the repository
949           configuration (see git-config(1)).
950
951       --abbrev-commit
952           Instead of showing the full 40-byte hexadecimal commit object name,
953           show a prefix that names the object uniquely. "--abbrev=<n>" (which
954           also modifies diff output, if it is displayed) option can be used
955           to specify the minimum length of the prefix.
956
957           This should make "--pretty=oneline" a whole lot more readable for
958           people using 80-column terminals.
959
960       --no-abbrev-commit
961           Show the full 40-byte hexadecimal commit object name. This negates
962           --abbrev-commit, either explicit or implied by other options such
963           as "--oneline". It also overrides the log.abbrevCommit variable.
964
965       --oneline
966           This is a shorthand for "--pretty=oneline --abbrev-commit" used
967           together.
968
969       --encoding=<encoding>
970           Commit objects record the character encoding used for the log
971           message in their encoding header; this option can be used to tell
972           the command to re-code the commit log message in the encoding
973           preferred by the user. For non plumbing commands this defaults to
974           UTF-8. Note that if an object claims to be encoded in X and we are
975           outputting in X, we will output the object verbatim; this means
976           that invalid sequences in the original commit may be copied to the
977           output. Likewise, if iconv(3) fails to convert the commit, we will
978           quietly output the original object verbatim.
979
980       --expand-tabs=<n>, --expand-tabs, --no-expand-tabs
981           Perform a tab expansion (replace each tab with enough spaces to
982           fill to the next display column that is multiple of <n>) in the log
983           message before showing it in the output.  --expand-tabs is a
984           short-hand for --expand-tabs=8, and --no-expand-tabs is a
985           short-hand for --expand-tabs=0, which disables tab expansion.
986
987           By default, tabs are expanded in pretty formats that indent the log
988           message by 4 spaces (i.e.  medium, which is the default, full, and
989           fuller).
990
991       --show-signature
992           Check the validity of a signed commit object by passing the
993           signature to gpg --verify and show the output.
994
995       --relative-date
996           Synonym for --date=relative.
997
998       --date=<format>
999           Only takes effect for dates shown in human-readable format, such as
1000           when using --pretty.  log.date config variable sets a default value
1001           for the log command’s --date option. By default, dates are shown in
1002           the original time zone (either committer’s or author’s). If -local
1003           is appended to the format (e.g., iso-local), the user’s local time
1004           zone is used instead.
1005
1006           --date=relative shows dates relative to the current time, e.g.  “2
1007           hours ago”. The -local option has no effect for --date=relative.
1008
1009           --date=local is an alias for --date=default-local.
1010
1011           --date=iso (or --date=iso8601) shows timestamps in a ISO 8601-like
1012           format. The differences to the strict ISO 8601 format are:
1013
1014           •   a space instead of the T date/time delimiter
1015
1016           •   a space between time and time zone
1017
1018           •   no colon between hours and minutes of the time zone
1019
1020           --date=iso-strict (or --date=iso8601-strict) shows timestamps in
1021           strict ISO 8601 format.
1022
1023           --date=rfc (or --date=rfc2822) shows timestamps in RFC 2822 format,
1024           often found in email messages.
1025
1026           --date=short shows only the date, but not the time, in YYYY-MM-DD
1027           format.
1028
1029           --date=raw shows the date as seconds since the epoch (1970-01-01
1030           00:00:00 UTC), followed by a space, and then the timezone as an
1031           offset from UTC (a + or - with four digits; the first two are
1032           hours, and the second two are minutes). I.e., as if the timestamp
1033           were formatted with strftime("%s %z")). Note that the -local option
1034           does not affect the seconds-since-epoch value (which is always
1035           measured in UTC), but does switch the accompanying timezone value.
1036
1037           --date=human shows the timezone if the timezone does not match the
1038           current time-zone, and doesn’t print the whole date if that matches
1039           (ie skip printing year for dates that are "this year", but also
1040           skip the whole date itself if it’s in the last few days and we can
1041           just say what weekday it was). For older dates the hour and minute
1042           is also omitted.
1043
1044           --date=unix shows the date as a Unix epoch timestamp (seconds since
1045           1970). As with --raw, this is always in UTC and therefore -local
1046           has no effect.
1047
1048           --date=format:...  feeds the format ...  to your system strftime,
1049           except for %s, %z, and %Z, which are handled internally. Use
1050           --date=format:%c to show the date in your system locale’s preferred
1051           format. See the strftime manual for a complete list of format
1052           placeholders. When using -local, the correct syntax is
1053           --date=format-local:....
1054
1055           --date=default is the default format, and is similar to
1056           --date=rfc2822, with a few exceptions:
1057
1058           •   there is no comma after the day-of-week
1059
1060           •   the time zone is omitted when the local time zone is used
1061
1062       --header
1063           Print the contents of the commit in raw-format; each record is
1064           separated with a NUL character.
1065
1066       --no-commit-header
1067           Suppress the header line containing "commit" and the object ID
1068           printed before the specified format. This has no effect on the
1069           built-in formats; only custom formats are affected.
1070
1071       --commit-header
1072           Overrides a previous --no-commit-header.
1073
1074       --parents
1075           Print also the parents of the commit (in the form "commit parent...
1076           "). Also enables parent rewriting, see History Simplification
1077           above.
1078
1079       --children
1080           Print also the children of the commit (in the form "commit child...
1081           "). Also enables parent rewriting, see History Simplification
1082           above.
1083
1084       --timestamp
1085           Print the raw commit timestamp.
1086
1087       --left-right
1088           Mark which side of a symmetric difference a commit is reachable
1089           from. Commits from the left side are prefixed with < and those from
1090           the right with >. If combined with --boundary, those commits are
1091           prefixed with -.
1092
1093           For example, if you have this topology:
1094
1095                            y---b---b  branch B
1096                           / \ /
1097                          /   .
1098                         /   / \
1099                        o---x---a---a  branch A
1100
1101           you would get an output like this:
1102
1103                       $ git rev-list --left-right --boundary --pretty=oneline A...B
1104
1105                       >bbbbbbb... 3rd on b
1106                       >bbbbbbb... 2nd on b
1107                       <aaaaaaa... 3rd on a
1108                       <aaaaaaa... 2nd on a
1109                       -yyyyyyy... 1st on b
1110                       -xxxxxxx... 1st on a
1111
1112       --graph
1113           Draw a text-based graphical representation of the commit history on
1114           the left hand side of the output. This may cause extra lines to be
1115           printed in between commits, in order for the graph history to be
1116           drawn properly. Cannot be combined with --no-walk.
1117
1118           This enables parent rewriting, see History Simplification above.
1119
1120           This implies the --topo-order option by default, but the
1121           --date-order option may also be specified.
1122
1123       --show-linear-break[=<barrier>]
1124           When --graph is not used, all history branches are flattened which
1125           can make it hard to see that the two consecutive commits do not
1126           belong to a linear branch. This option puts a barrier in between
1127           them in that case. If <barrier> is specified, it is the string that
1128           will be shown instead of the default one.
1129
1130       --count
1131           Print a number stating how many commits would have been listed, and
1132           suppress all other output. When used together with --left-right,
1133           instead print the counts for left and right commits, separated by a
1134           tab. When used together with --cherry-mark, omit patch equivalent
1135           commits from these counts and print the count for equivalent
1136           commits separated by a tab.
1137

PRETTY FORMATS

1139       If the commit is a merge, and if the pretty-format is not oneline,
1140       email or raw, an additional line is inserted before the Author: line.
1141       This line begins with "Merge: " and the hashes of ancestral commits are
1142       printed, separated by spaces. Note that the listed commits may not
1143       necessarily be the list of the direct parent commits if you have
1144       limited your view of history: for example, if you are only interested
1145       in changes related to a certain directory or file.
1146
1147       There are several built-in formats, and you can define additional
1148       formats by setting a pretty.<name> config option to either another
1149       format name, or a format: string, as described below (see git-
1150       config(1)). Here are the details of the built-in formats:
1151
1152oneline
1153
1154               <hash> <title-line>
1155
1156           This is designed to be as compact as possible.
1157
1158short
1159
1160               commit <hash>
1161               Author: <author>
1162
1163               <title-line>
1164
1165medium
1166
1167               commit <hash>
1168               Author: <author>
1169               Date:   <author-date>
1170
1171               <title-line>
1172
1173               <full-commit-message>
1174
1175full
1176
1177               commit <hash>
1178               Author: <author>
1179               Commit: <committer>
1180
1181               <title-line>
1182
1183               <full-commit-message>
1184
1185fuller
1186
1187               commit <hash>
1188               Author:     <author>
1189               AuthorDate: <author-date>
1190               Commit:     <committer>
1191               CommitDate: <committer-date>
1192
1193               <title-line>
1194
1195               <full-commit-message>
1196
1197reference
1198
1199               <abbrev-hash> (<title-line>, <short-author-date>)
1200
1201           This format is used to refer to another commit in a commit message
1202           and is the same as --pretty='format:%C(auto)%h (%s, %ad)'. By
1203           default, the date is formatted with --date=short unless another
1204           --date option is explicitly specified. As with any format: with
1205           format placeholders, its output is not affected by other options
1206           like --decorate and --walk-reflogs.
1207
1208email
1209
1210               From <hash> <date>
1211               From: <author>
1212               Date: <author-date>
1213               Subject: [PATCH] <title-line>
1214
1215               <full-commit-message>
1216
1217mboxrd
1218
1219           Like email, but lines in the commit message starting with "From "
1220           (preceded by zero or more ">") are quoted with ">" so they aren’t
1221           confused as starting a new commit.
1222
1223raw
1224
1225           The raw format shows the entire commit exactly as stored in the
1226           commit object. Notably, the hashes are displayed in full,
1227           regardless of whether --abbrev or --no-abbrev are used, and parents
1228           information show the true parent commits, without taking grafts or
1229           history simplification into account. Note that this format affects
1230           the way commits are displayed, but not the way the diff is shown
1231           e.g. with git log --raw. To get full object names in a raw diff
1232           format, use --no-abbrev.
1233
1234format:<format-string>
1235
1236           The format:<format-string> format allows you to specify which
1237           information you want to show. It works a little bit like printf
1238           format, with the notable exception that you get a newline with %n
1239           instead of \n.
1240
1241           E.g, format:"The author of %h was %an, %ar%nThe title was >>%s<<%n"
1242           would show something like this:
1243
1244               The author of fe6e0ee was Junio C Hamano, 23 hours ago
1245               The title was >>t4119: test autocomputing -p<n> for traditional diff input.<<
1246
1247           The placeholders are:
1248
1249           •   Placeholders that expand to a single literal character:
1250
1251               %n
1252                   newline
1253
1254               %%
1255                   a raw %
1256
1257               %x00
1258                   print a byte from a hex code
1259
1260           •   Placeholders that affect formatting of later placeholders:
1261
1262               %Cred
1263                   switch color to red
1264
1265               %Cgreen
1266                   switch color to green
1267
1268               %Cblue
1269                   switch color to blue
1270
1271               %Creset
1272                   reset color
1273
1274               %C(...)
1275                   color specification, as described under Values in the
1276                   "CONFIGURATION FILE" section of git-config(1). By default,
1277                   colors are shown only when enabled for log output (by
1278                   color.diff, color.ui, or --color, and respecting the auto
1279                   settings of the former if we are going to a terminal).
1280                   %C(auto,...)  is accepted as a historical synonym for the
1281                   default (e.g., %C(auto,red)). Specifying %C(always,...)
1282                   will show the colors even when color is not otherwise
1283                   enabled (though consider just using --color=always to
1284                   enable color for the whole output, including this format
1285                   and anything else git might color).  auto alone (i.e.
1286                   %C(auto)) will turn on auto coloring on the next
1287                   placeholders until the color is switched again.
1288
1289               %m
1290                   left (<), right (>) or boundary (-) mark
1291
1292               %w([<w>[,<i1>[,<i2>]]])
1293                   switch line wrapping, like the -w option of git-
1294                   shortlog(1).
1295
1296               %<(<N>[,trunc|ltrunc|mtrunc])
1297                   make the next placeholder take at least N columns, padding
1298                   spaces on the right if necessary. Optionally truncate at
1299                   the beginning (ltrunc), the middle (mtrunc) or the end
1300                   (trunc) if the output is longer than N columns. Note that
1301                   truncating only works correctly with N >= 2.
1302
1303               %<|(<N>)
1304                   make the next placeholder take at least until Nth columns,
1305                   padding spaces on the right if necessary
1306
1307               %>(<N>), %>|(<N>)
1308                   similar to %<(<N>), %<|(<N>) respectively, but padding
1309                   spaces on the left
1310
1311               %>>(<N>), %>>|(<N>)
1312                   similar to %>(<N>), %>|(<N>) respectively, except that if
1313                   the next placeholder takes more spaces than given and there
1314                   are spaces on its left, use those spaces
1315
1316               %><(<N>), %><|(<N>)
1317                   similar to %<(<N>), %<|(<N>) respectively, but padding both
1318                   sides (i.e. the text is centered)
1319
1320           •   Placeholders that expand to information extracted from the
1321               commit:
1322
1323               %H
1324                   commit hash
1325
1326               %h
1327                   abbreviated commit hash
1328
1329               %T
1330                   tree hash
1331
1332               %t
1333                   abbreviated tree hash
1334
1335               %P
1336                   parent hashes
1337
1338               %p
1339                   abbreviated parent hashes
1340
1341               %an
1342                   author name
1343
1344               %aN
1345                   author name (respecting .mailmap, see git-shortlog(1) or
1346                   git-blame(1))
1347
1348               %ae
1349                   author email
1350
1351               %aE
1352                   author email (respecting .mailmap, see git-shortlog(1) or
1353                   git-blame(1))
1354
1355               %al
1356                   author email local-part (the part before the @ sign)
1357
1358               %aL
1359                   author local-part (see %al) respecting .mailmap, see git-
1360                   shortlog(1) or git-blame(1))
1361
1362               %ad
1363                   author date (format respects --date= option)
1364
1365               %aD
1366                   author date, RFC2822 style
1367
1368               %ar
1369                   author date, relative
1370
1371               %at
1372                   author date, UNIX timestamp
1373
1374               %ai
1375                   author date, ISO 8601-like format
1376
1377               %aI
1378                   author date, strict ISO 8601 format
1379
1380               %as
1381                   author date, short format (YYYY-MM-DD)
1382
1383               %ah
1384                   author date, human style (like the --date=human option of
1385                   git-rev-list(1))
1386
1387               %cn
1388                   committer name
1389
1390               %cN
1391                   committer name (respecting .mailmap, see git-shortlog(1) or
1392                   git-blame(1))
1393
1394               %ce
1395                   committer email
1396
1397               %cE
1398                   committer email (respecting .mailmap, see git-shortlog(1)
1399                   or git-blame(1))
1400
1401               %cl
1402                   committer email local-part (the part before the @ sign)
1403
1404               %cL
1405                   committer local-part (see %cl) respecting .mailmap, see
1406                   git-shortlog(1) or git-blame(1))
1407
1408               %cd
1409                   committer date (format respects --date= option)
1410
1411               %cD
1412                   committer date, RFC2822 style
1413
1414               %cr
1415                   committer date, relative
1416
1417               %ct
1418                   committer date, UNIX timestamp
1419
1420               %ci
1421                   committer date, ISO 8601-like format
1422
1423               %cI
1424                   committer date, strict ISO 8601 format
1425
1426               %cs
1427                   committer date, short format (YYYY-MM-DD)
1428
1429               %ch
1430                   committer date, human style (like the --date=human option
1431                   of git-rev-list(1))
1432
1433               %d
1434                   ref names, like the --decorate option of git-log(1)
1435
1436               %D
1437                   ref names without the " (", ")" wrapping.
1438
1439               %(describe[:options])
1440                   human-readable name, like git-describe(1); empty string for
1441                   undescribable commits. The describe string may be followed
1442                   by a colon and zero or more comma-separated options.
1443                   Descriptions can be inconsistent when tags are added or
1444                   removed at the same time.
1445
1446tags[=<bool-value>]: Instead of only considering
1447                       annotated tags, consider lightweight tags as well.
1448
1449abbrev=<number>: Instead of using the default number of
1450                       hexadecimal digits (which will vary according to the
1451                       number of objects in the repository with a default of
1452                       7) of the abbreviated object name, use <number> digits,
1453                       or as many digits as needed to form a unique object
1454                       name.
1455
1456match=<pattern>: Only consider tags matching the given
1457                       glob(7) pattern, excluding the "refs/tags/" prefix.
1458
1459exclude=<pattern>: Do not consider tags matching the
1460                       given glob(7) pattern, excluding the "refs/tags/"
1461                       prefix.
1462
1463               %S
1464                   ref name given on the command line by which the commit was
1465                   reached (like git log --source), only works with git log
1466
1467               %e
1468                   encoding
1469
1470               %s
1471                   subject
1472
1473               %f
1474                   sanitized subject line, suitable for a filename
1475
1476               %b
1477                   body
1478
1479               %B
1480                   raw body (unwrapped subject and body)
1481
1482               %GG
1483                   raw verification message from GPG for a signed commit
1484
1485               %G?
1486                   show "G" for a good (valid) signature, "B" for a bad
1487                   signature, "U" for a good signature with unknown validity,
1488                   "X" for a good signature that has expired, "Y" for a good
1489                   signature made by an expired key, "R" for a good signature
1490                   made by a revoked key, "E" if the signature cannot be
1491                   checked (e.g. missing key) and "N" for no signature
1492
1493               %GS
1494                   show the name of the signer for a signed commit
1495
1496               %GK
1497                   show the key used to sign a signed commit
1498
1499               %GF
1500                   show the fingerprint of the key used to sign a signed
1501                   commit
1502
1503               %GP
1504                   show the fingerprint of the primary key whose subkey was
1505                   used to sign a signed commit
1506
1507               %GT
1508                   show the trust level for the key used to sign a signed
1509                   commit
1510
1511               %gD
1512                   reflog selector, e.g., refs/stash@{1} or refs/stash@{2
1513                   minutes ago}; the format follows the rules described for
1514                   the -g option. The portion before the @ is the refname as
1515                   given on the command line (so git log -g refs/heads/master
1516                   would yield refs/heads/master@{0}).
1517
1518               %gd
1519                   shortened reflog selector; same as %gD, but the refname
1520                   portion is shortened for human readability (so
1521                   refs/heads/master becomes just master).
1522
1523               %gn
1524                   reflog identity name
1525
1526               %gN
1527                   reflog identity name (respecting .mailmap, see git-
1528                   shortlog(1) or git-blame(1))
1529
1530               %ge
1531                   reflog identity email
1532
1533               %gE
1534                   reflog identity email (respecting .mailmap, see git-
1535                   shortlog(1) or git-blame(1))
1536
1537               %gs
1538                   reflog subject
1539
1540               %(trailers[:options])
1541                   display the trailers of the body as interpreted by git-
1542                   interpret-trailers(1). The trailers string may be followed
1543                   by a colon and zero or more comma-separated options. If any
1544                   option is provided multiple times the last occurrence wins.
1545
1546key=<key>: only show trailers with specified <key>.
1547                       Matching is done case-insensitively and trailing colon
1548                       is optional. If option is given multiple times trailer
1549                       lines matching any of the keys are shown. This option
1550                       automatically enables the only option so that
1551                       non-trailer lines in the trailer block are hidden. If
1552                       that is not desired it can be disabled with only=false.
1553                       E.g., %(trailers:key=Reviewed-by) shows trailer lines
1554                       with key Reviewed-by.
1555
1556only[=<bool>]: select whether non-trailer lines from
1557                       the trailer block should be included.
1558
1559separator=<sep>: specify a separator inserted between
1560                       trailer lines. When this option is not given each
1561                       trailer line is terminated with a line feed character.
1562                       The string <sep> may contain the literal formatting
1563                       codes described above. To use comma as separator one
1564                       must use %x2C as it would otherwise be parsed as next
1565                       option. E.g., %(trailers:key=Ticket,separator=%x2C )
1566                       shows all trailer lines whose key is "Ticket" separated
1567                       by a comma and a space.
1568
1569unfold[=<bool>]: make it behave as if
1570                       interpret-trailer’s --unfold option was given. E.g.,
1571                       %(trailers:only,unfold=true) unfolds and shows all
1572                       trailer lines.
1573
1574keyonly[=<bool>]: only show the key part of the
1575                       trailer.
1576
1577valueonly[=<bool>]: only show the value part of the
1578                       trailer.
1579
1580key_value_separator=<sep>: specify a separator inserted
1581                       between trailer lines. When this option is not given
1582                       each trailer key-value pair is separated by ": ".
1583                       Otherwise it shares the same semantics as
1584                       separator=<sep> above.
1585
1586           Note
1587           Some placeholders may depend on other options given to the revision
1588           traversal engine. For example, the %g* reflog options will insert
1589           an empty string unless we are traversing reflog entries (e.g., by
1590           git log -g). The %d and %D placeholders will use the "short"
1591           decoration format if --decorate was not already provided on the
1592           command line.
1593
1594       The boolean options accept an optional value [=<bool-value>]. The
1595       values true, false, on, off etc. are all accepted. See the "boolean"
1596       sub-section in "EXAMPLES" in git-config(1). If a boolean option is
1597       given with no value, it’s enabled.
1598
1599       If you add a + (plus sign) after % of a placeholder, a line-feed is
1600       inserted immediately before the expansion if and only if the
1601       placeholder expands to a non-empty string.
1602
1603       If you add a - (minus sign) after % of a placeholder, all consecutive
1604       line-feeds immediately preceding the expansion are deleted if and only
1605       if the placeholder expands to an empty string.
1606
1607       If you add a ` ` (space) after % of a placeholder, a space is inserted
1608       immediately before the expansion if and only if the placeholder expands
1609       to a non-empty string.
1610
1611tformat:
1612
1613           The tformat: format works exactly like format:, except that it
1614           provides "terminator" semantics instead of "separator" semantics.
1615           In other words, each commit has the message terminator character
1616           (usually a newline) appended, rather than a separator placed
1617           between entries. This means that the final entry of a single-line
1618           format will be properly terminated with a new line, just as the
1619           "oneline" format does. For example:
1620
1621               $ git log -2 --pretty=format:%h 4da45bef \
1622                 | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
1623               4da45be
1624               7134973 -- NO NEWLINE
1625
1626               $ git log -2 --pretty=tformat:%h 4da45bef \
1627                 | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
1628               4da45be
1629               7134973
1630
1631           In addition, any unrecognized string that has a % in it is
1632           interpreted as if it has tformat: in front of it. For example,
1633           these two are equivalent:
1634
1635               $ git log -2 --pretty=tformat:%h 4da45bef
1636               $ git log -2 --pretty=%h 4da45bef
1637

EXAMPLES

1639       •   Print the list of commits reachable from the current branch.
1640
1641               git rev-list HEAD
1642
1643       •   Print the list of commits on this branch, but not present in the
1644           upstream branch.
1645
1646               git rev-list @{upstream}..HEAD
1647
1648       •   Format commits with their author and commit message (see also the
1649           porcelain git-log(1)).
1650
1651               git rev-list --format=medium HEAD
1652
1653       •   Format commits along with their diffs (see also the porcelain git-
1654           log(1), which can do this in a single process).
1655
1656               git rev-list HEAD |
1657               git diff-tree --stdin --format=medium -p
1658
1659       •   Print the list of commits on the current branch that touched any
1660           file in the Documentation directory.
1661
1662               git rev-list HEAD -- Documentation/
1663
1664       •   Print the list of commits authored by you in the past year, on any
1665           branch, tag, or other ref.
1666
1667               git rev-list --author=you@example.com --since=1.year.ago --all
1668
1669       •   Print the list of objects reachable from the current branch (i.e.,
1670           all commits and the blobs and trees they contain).
1671
1672               git rev-list --objects HEAD
1673
1674       •   Compare the disk size of all reachable objects, versus those
1675           reachable from reflogs, versus the total packed size. This can tell
1676           you whether running git repack -ad might reduce the repository size
1677           (by dropping unreachable objects), and whether expiring reflogs
1678           might help.
1679
1680               # reachable objects
1681               git rev-list --disk-usage --objects --all
1682               # plus reflogs
1683               git rev-list --disk-usage --objects --all --reflog
1684               # total disk size used
1685               du -c .git/objects/pack/*.pack .git/objects/??/*
1686               # alternative to du: add up "size" and "size-pack" fields
1687               git count-objects -v
1688
1689       •   Report the disk size of each branch, not including objects used by
1690           the current branch. This can find outliers that are contributing to
1691           a bloated repository size (e.g., because somebody accidentally
1692           committed large build artifacts).
1693
1694               git for-each-ref --format='%(refname)' |
1695               while read branch
1696               do
1697                       size=$(git rev-list --disk-usage --objects HEAD..$branch)
1698                       echo "$size $branch"
1699               done |
1700               sort -n
1701
1702       •   Compare the on-disk size of branches in one group of refs,
1703           excluding another. If you co-mingle objects from multiple remotes
1704           in a single repository, this can show which remotes are
1705           contributing to the repository size (taking the size of origin as a
1706           baseline).
1707
1708               git rev-list --disk-usage --objects --remotes=$suspect --not --remotes=origin
1709

GIT

1711       Part of the git(1) suite
1712
1713
1714
1715Git 2.36.1                        2022-05-05                   GIT-REV-LIST(1)
Impressum