Merge branch 'jc/show-merge'
[git/git.git] / Documentation / git-rev-list.txt
CommitLineData
2cf565c5
DG
1git-rev-list(1)
2===============
2cf565c5
DG
3
4NAME
5----
6git-rev-list - Lists commit objects in reverse chronological order
7
8
9SYNOPSIS
10--------
353ce815 11[verse]
69e0c256 12'git-rev-list' [ \--max-count=number ]
353ce815
JF
13 [ \--max-age=timestamp ]
14 [ \--min-age=timestamp ]
15 [ \--sparse ]
16 [ \--no-merges ]
93b74bca 17 [ \--remove-empty ]
0d2c9d67 18 [ \--not ]
353ce815 19 [ \--all ]
765ac8ec 20 [ \--topo-order ]
353ce815 21 [ \--parents ]
ec579767 22 [ [\--objects | \--objects-edge] [ \--unpacked ] ]
353ce815
JF
23 [ \--pretty | \--header ]
24 [ \--bisect ]
25 <commit>... [ \-- <paths>... ]
2cf565c5
DG
26
27DESCRIPTION
28-----------
29Lists commit objects in reverse chronological order starting at the
adcd3512 30given commit(s), taking ancestry relationship into account. This is
2cf565c5
DG
31useful to produce human-readable log output.
32
69e0c256
JH
33Commits which are stated with a preceding '{caret}' cause listing to stop at
34that point. Their parents are implied. "git-rev-list foo bar {caret}baz" thus
adcd3512
MU
35means "list all the commits which are included in 'foo' and 'bar', but
36not in 'baz'".
37
69e0c256
JH
38A special notation <commit1>..<commit2> can be used as a
39short-hand for {caret}<commit1> <commit2>.
40
0d2c9d67
RS
41Another special notation is <commit1>...<commit2> which is useful for
42merges. The resulting set of commits is the symmetric difference
43between the two operands. The following two commands are equivalent:
44
45------------
46$ git-rev-list A B --not $(git-merge-base --all A B)
47$ git-rev-list A...B
48------------
69e0c256 49
df8baa42
JF
50OPTIONS
51-------
52--pretty::
53 Print the contents of the commit changesets in human-readable form.
54
69e0c256
JH
55--header::
56 Print the contents of the commit in raw-format; each
57 record is separated with a NUL character.
58
df8baa42
JF
59--objects::
60 Print the object IDs of any object referenced by the listed commits.
61 'git-rev-list --objects foo ^bar' thus means "send me all object IDs
62 which I need to download if I have the commit object 'bar', but
63 not 'foo'".
64
ec579767
JH
65--objects-edge::
66 Similar to `--objects`, but also print the IDs of
addf88e4 67 excluded commits prefixed with a `-` character. This is
ec579767
JH
68 used by `git-pack-objects` to build 'thin' pack, which
69 records objects in deltified form based on objects
70 contained in these excluded commits to reduce network
71 traffic.
72
69e0c256
JH
73--unpacked::
74 Only useful with `--objects`; print the object IDs that
75 are not in packs.
76
df8baa42
JF
77--bisect::
78 Limit output to the one commit object which is roughly halfway
79 between the included and excluded commits. Thus, if 'git-rev-list
afb4ff20
JH
80 --bisect foo {caret}bar {caret}baz' outputs 'midpoint', the output
81 of 'git-rev-list foo {caret}midpoint' and 'git-rev-list midpoint
82 {caret}bar {caret}baz' would be of roughly the same length.
83 Finding the change
df8baa42
JF
84 which introduces a regression is thus reduced to a binary search:
85 repeatedly generate and test new 'midpoint's until the commit chain
86 is of length one.
87
69e0c256
JH
88--max-count::
89 Limit the number of commits output.
90
91--max-age=timestamp, --min-age=timestamp::
92 Limit the commits output to specified time range.
93
94--sparse::
95 When optional paths are given, the command outputs only
64b1f6e6
JH
96 the commits that changes at least one of them, and also
97 ignores merges that do not touch the given paths. This
98 flag makes the command output all eligible commits
99 (still subject to count and age limitation), but apply
100 merge simplification nevertheless.
69e0c256 101
93b74bca
JH
102--remove-empty::
103 Stop when a given path disappears from the tree.
104
0d2c9d67
RS
105--not::
106 Reverses the meaning of the '{caret}' prefix (or lack
107 thereof) for all following revision specifiers, up to
108 the next `--not`.
109
69e0c256
JH
110--all::
111 Pretend as if all the refs in `$GIT_DIR/refs/` are
112 listed on the command line as <commit>.
113
114--topo-order::
115 By default, the commits are shown in reverse
116 chronological order. This option makes them appear in
117 topological order (i.e. descendant commits are shown
118 before their parents).
119
2cf565c5
DG
120Author
121------
122Written by Linus Torvalds <torvalds@osdl.org>
123
124Documentation
125--------------
126Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
127
128GIT
129---
a7154e91 130Part of the gitlink:git[7] suite
2cf565c5 131