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