Documentation: describe shallow repository
[git] / Documentation / git-rev-list.txt
1 git-rev-list(1)
2 ===============
3
4 NAME
5 ----
6 git-rev-list - Lists commit objects in reverse chronological order
7
8
9 SYNOPSIS
10 --------
11 [verse]
12 'git-rev-list' [ \--max-count=number ]
13              [ \--skip=number ]
14              [ \--max-age=timestamp ]
15              [ \--min-age=timestamp ]
16              [ \--sparse ]
17              [ \--no-merges ]
18              [ \--remove-empty ]
19              [ \--not ]
20              [ \--all ]
21              [ \--stdin ]
22              [ \--topo-order ]
23              [ \--parents ]
24              [ \--encoding[=<encoding>] ]
25              [ \--(author|committer|grep)=<pattern> ]
26              [ [\--objects | \--objects-edge] [ \--unpacked ] ]
27              [ \--pretty | \--header ]
28              [ \--bisect ]
29              [ \--merge ]
30              <commit>... [ \-- <paths>... ]
31
32 DESCRIPTION
33 -----------
34
35 Lists commit objects in reverse chronological order starting at the
36 given commit(s), taking ancestry relationship into account.  This is
37 useful to produce human-readable log output.
38
39 Commits which are stated with a preceding '{caret}' cause listing to
40 stop at that point. Their parents are implied. Thus the following
41 command:
42
43 -----------------------------------------------------------------------
44         $ git-rev-list foo bar ^baz
45 -----------------------------------------------------------------------
46
47 means "list all the commits which are included in 'foo' and 'bar', but
48 not in 'baz'".
49
50 A special notation "'<commit1>'..'<commit2>'" can be used as a
51 short-hand for "{caret}'<commit1>' '<commit2>'". For example, either of
52 the following may be used interchangeably:
53
54 -----------------------------------------------------------------------
55         $ git-rev-list origin..HEAD
56         $ git-rev-list HEAD ^origin
57 -----------------------------------------------------------------------
58
59 Another special notation is "'<commit1>'...'<commit2>'" which is useful
60 for merges.  The resulting set of commits is the symmetric difference
61 between the two operands.  The following two commands are equivalent:
62
63 -----------------------------------------------------------------------
64         $ git-rev-list A B --not $(git-merge-base --all A B)
65         $ git-rev-list A...B
66 -----------------------------------------------------------------------
67
68 gitlink:git-rev-list[1] is a very essential git program, since it
69 provides the ability to build and traverse commit ancestry graphs. For
70 this reason, it has a lot of different options that enables it to be
71 used by commands as different as gitlink:git-bisect[1] and
72 gitlink:git-repack[1].
73
74 OPTIONS
75 -------
76
77 Commit Formatting
78 ~~~~~~~~~~~~~~~~~
79
80 Using these options, gitlink:git-rev-list[1] will act similar to the
81 more specialized family of commit log tools: gitlink:git-log[1],
82 gitlink:git-show[1], and gitlink:git-whatchanged[1]
83
84 include::pretty-formats.txt[]
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".
91
92 --header::
93
94         Print the contents of the commit in raw-format; each record is
95         separated with a NUL character.
96
97 --parents::
98
99         Print the parents of the commit.
100
101 Diff Formatting
102 ~~~~~~~~~~~~~~~
103
104 Below are listed options that control the formatting of diff output.
105 Some of them are specific to gitlink:git-rev-list[1], however other diff
106 options may be given. See gitlink:git-diff-files[1] for more options.
107
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
131 Commit Limiting
132 ~~~~~~~~~~~~~~~
133
134 Besides specifying a range of commits that should be listed using the
135 special notations explained in the description, additional commit
136 limiting may be applied.
137
138 --
139
140 -n 'number', --max-count='number'::
141
142         Limit the number of commits output.
143
144 --skip='number'::
145
146         Skip 'number' commits before starting to show the commit output.
147
148 --since='date', --after='date'::
149
150         Show commits more recent than a specific date.
151
152 --until='date', --before='date'::
153
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.
159
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
170 --remove-empty::
171
172         Stop when a given path disappears from the tree.
173
174 --no-merges::
175
176         Do not print commits with more than one parent.
177
178 --not::
179
180         Reverses the meaning of the '{caret}' prefix (or lack thereof)
181         for all following revision specifiers, up to the next '--not'.
182
183 --all::
184
185         Pretend as if all the refs in `$GIT_DIR/refs/` are listed on the
186         command line as '<commit>'.
187
188 --stdin::
189
190         In addition to the '<commit>' listed on the command
191         line, read them from the standard input.
192
193 --merge::
194
195         After a failed merge, show refs that touch files having a
196         conflict and don't exist on all heads to merge.
197
198 --boundary::
199
200         Output uninteresting commits at the boundary, which are usually
201         not shown.
202
203 --dense, --sparse::
204
205 When optional paths are given, the default behaviour ('--dense') is to
206 only output commits that changes at least one of them, and also ignore
207 merges that do not touch the given paths.
208
209 Use the '--sparse' flag to makes the command output all eligible commits
210 (still subject to count and age limitation), but apply merge
211 simplification nevertheless.
212
213 --bisect::
214
215 Limit output to the one commit object which is roughly halfway between
216 the included and excluded commits. Thus, if
217
218 -----------------------------------------------------------------------
219         $ git-rev-list --bisect foo ^bar ^baz
220 -----------------------------------------------------------------------
221
222 outputs 'midpoint', the output of the two commands
223
224 -----------------------------------------------------------------------
225         $ git-rev-list foo ^midpoint
226         $ git-rev-list midpoint ^bar ^baz
227 -----------------------------------------------------------------------
228
229 would be of roughly the same length.  Finding the change which
230 introduces a regression is thus reduced to a binary search: repeatedly
231 generate and test new 'midpoint's until the commit chain is of length
232 one.
233
234 --
235
236 Commit Ordering
237 ~~~~~~~~~~~~~~~
238
239 By 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
252 Object Traversal
253 ~~~~~~~~~~~~~~~~
254
255 These 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.
276
277 Author
278 ------
279 Written by Linus Torvalds <torvalds@osdl.org>
280
281 Documentation
282 --------------
283 Documentation by David Greaves, Junio C Hamano, Jonas Fonseca
284 and the git-list <git@vger.kernel.org>.
285
286 GIT
287 ---
288 Part of the gitlink:git[7] suite