--walk-reflogs: disallow uninteresting commits
[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 ]
d5db6c9e 13 [ \--skip=number ]
353ce815
JF
14 [ \--max-age=timestamp ]
15 [ \--min-age=timestamp ]
16 [ \--sparse ]
17 [ \--no-merges ]
93b74bca 18 [ \--remove-empty ]
0d2c9d67 19 [ \--not ]
353ce815 20 [ \--all ]
42cabc34 21 [ \--stdin ]
765ac8ec 22 [ \--topo-order ]
353ce815 23 [ \--parents ]
7cbcf4d5 24 [ \--encoding[=<encoding>] ]
bd95fcd3 25 [ \--(author|committer|grep)=<pattern> ]
ec579767 26 [ [\--objects | \--objects-edge] [ \--unpacked ] ]
353ce815
JF
27 [ \--pretty | \--header ]
28 [ \--bisect ]
d249b455 29 [ \--merge ]
353ce815 30 <commit>... [ \-- <paths>... ]
2cf565c5
DG
31
32DESCRIPTION
33-----------
8c02eee2 34
2cf565c5 35Lists commit objects in reverse chronological order starting at the
adcd3512 36given commit(s), taking ancestry relationship into account. This is
2cf565c5
DG
37useful to produce human-readable log output.
38
8c02eee2
JF
39Commits which are stated with a preceding '{caret}' cause listing to
40stop at that point. Their parents are implied. Thus the following
41command:
42
43-----------------------------------------------------------------------
44 $ git-rev-list foo bar ^baz
45-----------------------------------------------------------------------
46
adcd3512
MU
47means "list all the commits which are included in 'foo' and 'bar', but
48not in 'baz'".
49
8c02eee2
JF
50A special notation "'<commit1>'..'<commit2>'" can be used as a
51short-hand for "{caret}'<commit1>' '<commit2>'". For example, either of
52the following may be used interchangeably:
69e0c256 53
8c02eee2
JF
54-----------------------------------------------------------------------
55 $ git-rev-list origin..HEAD
56 $ git-rev-list HEAD ^origin
57-----------------------------------------------------------------------
58
59Another special notation is "'<commit1>'...'<commit2>'" which is useful
60for merges. The resulting set of commits is the symmetric difference
0d2c9d67
RS
61between the two operands. The following two commands are equivalent:
62
8c02eee2
JF
63-----------------------------------------------------------------------
64 $ git-rev-list A B --not $(git-merge-base --all A B)
65 $ git-rev-list A...B
66-----------------------------------------------------------------------
67
68gitlink:git-rev-list[1] is a very essential git program, since it
69provides the ability to build and traverse commit ancestry graphs. For
70this reason, it has a lot of different options that enables it to be
71used by commands as different as gitlink:git-bisect[1] and
72gitlink:git-repack[1].
69e0c256 73
df8baa42
JF
74OPTIONS
75-------
8c02eee2
JF
76
77Commit Formatting
78~~~~~~~~~~~~~~~~~
79
80Using these options, gitlink:git-rev-list[1] will act similar to the
81more specialized family of commit log tools: gitlink:git-log[1],
82gitlink:git-show[1], and gitlink:git-whatchanged[1]
83
5d1faf87 84include::pretty-formats.txt[]
8c02eee2
JF
85
86--relative-date::
87
88 Show dates relative to the current time, e.g. "2 hours ago".
89 Only takes effect for dates shown in human-readable format, such
90 as when using "--pretty".
df8baa42 91
69e0c256 92--header::
8c02eee2
JF
93
94 Print the contents of the commit in raw-format; each record is
95 separated with a NUL character.
69e0c256 96
f443455a 97--parents::
8c02eee2 98
f443455a
ML
99 Print the parents of the commit.
100
8c02eee2
JF
101Diff Formatting
102~~~~~~~~~~~~~~~
df8baa42 103
8c02eee2
JF
104Below are listed options that control the formatting of diff output.
105Some of them are specific to gitlink:git-rev-list[1], however other diff
106options may be given. See gitlink:git-diff-files[1] for more options.
ec579767 107
8c02eee2
JF
108-c::
109
110 This flag changes the way a merge commit is displayed. It shows
111 the differences from each of the parents to the merge result
112 simultaneously instead of showing pairwise diff between a parent
113 and the result one at a time. Furthermore, it lists only files
114 which were modified from all parents.
115
116--cc::
117
118 This flag implies the '-c' options and further compresses the
119 patch output by omitting hunks that show differences from only
120 one parent, or show the same change from all but one parent for
121 an Octopus merge.
122
123-r::
124
125 Show recursive diffs.
126
127-t::
128
129 Show the tree objects in the diff output. This implies '-r'.
130
131Commit Limiting
132~~~~~~~~~~~~~~~
133
134Besides specifying a range of commits that should be listed using the
135special notations explained in the description, additional commit
136limiting may be applied.
137
138--
139
140-n 'number', --max-count='number'::
69e0c256 141
69e0c256
JH
142 Limit the number of commits output.
143
d5db6c9e
JH
144--skip='number'::
145
146 Skip 'number' commits before starting to show the commit output.
147
8c02eee2
JF
148--since='date', --after='date'::
149
150 Show commits more recent than a specific date.
151
152--until='date', --before='date'::
69e0c256 153
8c02eee2
JF
154 Show commits older than a specific date.
155
156--max-age='timestamp', --min-age='timestamp'::
157
158 Limit the commits output to specified time range.
69e0c256 159
bd95fcd3
JH
160--author='pattern', --committer='pattern'::
161
162 Limit the commits output to ones with author/committer
163 header lines that match the specified pattern.
164
165--grep='pattern'::
166
167 Limit the commits output to ones with log message that
168 matches the specified pattern.
169
93b74bca 170--remove-empty::
8c02eee2 171
93b74bca
JH
172 Stop when a given path disappears from the tree.
173
f443455a 174--no-merges::
8c02eee2 175
f443455a
ML
176 Do not print commits with more than one parent.
177
0d2c9d67 178--not::
8c02eee2
JF
179
180 Reverses the meaning of the '{caret}' prefix (or lack thereof)
181 for all following revision specifiers, up to the next '--not'.
0d2c9d67 182
69e0c256 183--all::
69e0c256 184
8c02eee2
JF
185 Pretend as if all the refs in `$GIT_DIR/refs/` are listed on the
186 command line as '<commit>'.
69e0c256 187
42cabc34
JH
188--stdin::
189
190 In addition to the '<commit>' listed on the command
191 line, read them from the standard input.
192
d249b455 193--merge::
8c02eee2 194
d249b455
UZ
195 After a failed merge, show refs that touch files having a
196 conflict and don't exist on all heads to merge.
197
8c02eee2
JF
198--boundary::
199
200 Output uninteresting commits at the boundary, which are usually
201 not shown.
202
203--dense, --sparse::
204
205When optional paths are given, the default behaviour ('--dense') is to
206only output commits that changes at least one of them, and also ignore
207merges that do not touch the given paths.
208
209Use the '--sparse' flag to makes the command output all eligible commits
210(still subject to count and age limitation), but apply merge
211simplification nevertheless.
212
213--bisect::
214
215Limit output to the one commit object which is roughly halfway between
216the included and excluded commits. Thus, if
217
218-----------------------------------------------------------------------
219 $ git-rev-list --bisect foo ^bar ^baz
220-----------------------------------------------------------------------
221
222outputs 'midpoint', the output of the two commands
223
224-----------------------------------------------------------------------
225 $ git-rev-list foo ^midpoint
226 $ git-rev-list midpoint ^bar ^baz
227-----------------------------------------------------------------------
228
229would be of roughly the same length. Finding the change which
230introduces a regression is thus reduced to a binary search: repeatedly
231generate and test new 'midpoint's until the commit chain is of length
232one.
233
234--
235
236Commit Ordering
237~~~~~~~~~~~~~~~
238
239By default, the commits are shown in reverse chronological order.
240
241--topo-order::
242
243 This option makes them appear in topological order (i.e.
244 descendant commits are shown before their parents).
245
246--date-order::
247
248 This option is similar to '--topo-order' in the sense that no
249 parent comes before all of its children, but otherwise things
250 are still ordered in the commit timestamp order.
251
252Object Traversal
253~~~~~~~~~~~~~~~~
254
255These options are mostly targeted for packing of git repositories.
256
257--objects::
258
259 Print the object IDs of any object referenced by the listed
260 commits. 'git-rev-list --objects foo ^bar' thus means "send me
261 all object IDs which I need to download if I have the commit
262 object 'bar', but not 'foo'".
263
264--objects-edge::
265
266 Similar to '--objects', but also print the IDs of excluded
267 commits prefixed with a "-" character. This is used by
268 gitlink:git-pack-objects[1] to build "thin" pack, which records
269 objects in deltified form based on objects contained in these
270 excluded commits to reduce network traffic.
271
272--unpacked::
273
274 Only useful with '--objects'; print the object IDs that are not
275 in packs.
3dfb9278 276
2cf565c5
DG
277Author
278------
279Written by Linus Torvalds <torvalds@osdl.org>
280
281Documentation
282--------------
8c02eee2
JF
283Documentation by David Greaves, Junio C Hamano, Jonas Fonseca
284and the git-list <git@vger.kernel.org>.
2cf565c5
DG
285
286GIT
287---
a7154e91 288Part of the gitlink:git[7] suite