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