]>
Commit | Line | Data |
---|---|---|
2cf565c5 DG |
1 | git-rev-list(1) |
2 | =============== | |
2cf565c5 DG |
3 | |
4 | NAME | |
5 | ---- | |
6 | git-rev-list - Lists commit objects in reverse chronological order | |
7 | ||
8 | ||
9 | SYNOPSIS | |
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 ] |
29a6c3f8 | 19 | [ \--full-history ] |
0d2c9d67 | 20 | [ \--not ] |
353ce815 | 21 | [ \--all ] |
42cabc34 | 22 | [ \--stdin ] |
765ac8ec | 23 | [ \--topo-order ] |
353ce815 | 24 | [ \--parents ] |
e3c1500f | 25 | [ \--timestamp ] |
b24bace5 | 26 | [ \--left-right ] |
55a643ed | 27 | [ \--cherry-pick ] |
7cbcf4d5 | 28 | [ \--encoding[=<encoding>] ] |
bd95fcd3 | 29 | [ \--(author|committer|grep)=<pattern> ] |
e5633cbb JH |
30 | [ \--regexp-ignore-case | \-i ] |
31 | [ \--extended-regexp | \-E ] | |
1701872f | 32 | [ \--date={local|relative|default|iso|rfc|short} ] |
ec579767 | 33 | [ [\--objects | \--objects-edge] [ \--unpacked ] ] |
353ce815 JF |
34 | [ \--pretty | \--header ] |
35 | [ \--bisect ] | |
457f08a0 | 36 | [ \--bisect-vars ] |
3ac9f612 | 37 | [ \--bisect-all ] |
d249b455 | 38 | [ \--merge ] |
9c5e66e9 | 39 | [ \--reverse ] |
4d12a471 | 40 | [ \--walk-reflogs ] |
8e64006e | 41 | [ \--no-walk ] [ \--do-walk ] |
353ce815 | 42 | <commit>... [ \-- <paths>... ] |
2cf565c5 DG |
43 | |
44 | DESCRIPTION | |
45 | ----------- | |
8c02eee2 | 46 | |
2cf565c5 | 47 | Lists commit objects in reverse chronological order starting at the |
adcd3512 | 48 | given commit(s), taking ancestry relationship into account. This is |
2cf565c5 DG |
49 | useful to produce human-readable log output. |
50 | ||
8c02eee2 JF |
51 | Commits which are stated with a preceding '{caret}' cause listing to |
52 | stop at that point. Their parents are implied. Thus the following | |
53 | command: | |
54 | ||
55 | ----------------------------------------------------------------------- | |
56 | $ git-rev-list foo bar ^baz | |
57 | ----------------------------------------------------------------------- | |
58 | ||
adcd3512 MU |
59 | means "list all the commits which are included in 'foo' and 'bar', but |
60 | not in 'baz'". | |
61 | ||
8c02eee2 JF |
62 | A special notation "'<commit1>'..'<commit2>'" can be used as a |
63 | short-hand for "{caret}'<commit1>' '<commit2>'". For example, either of | |
64 | the following may be used interchangeably: | |
69e0c256 | 65 | |
8c02eee2 JF |
66 | ----------------------------------------------------------------------- |
67 | $ git-rev-list origin..HEAD | |
68 | $ git-rev-list HEAD ^origin | |
69 | ----------------------------------------------------------------------- | |
70 | ||
71 | Another special notation is "'<commit1>'...'<commit2>'" which is useful | |
72 | for merges. The resulting set of commits is the symmetric difference | |
0d2c9d67 RS |
73 | between the two operands. The following two commands are equivalent: |
74 | ||
8c02eee2 JF |
75 | ----------------------------------------------------------------------- |
76 | $ git-rev-list A B --not $(git-merge-base --all A B) | |
77 | $ git-rev-list A...B | |
78 | ----------------------------------------------------------------------- | |
79 | ||
80 | gitlink:git-rev-list[1] is a very essential git program, since it | |
81 | provides the ability to build and traverse commit ancestry graphs. For | |
82 | this reason, it has a lot of different options that enables it to be | |
83 | used by commands as different as gitlink:git-bisect[1] and | |
84 | gitlink:git-repack[1]. | |
69e0c256 | 85 | |
df8baa42 JF |
86 | OPTIONS |
87 | ------- | |
8c02eee2 JF |
88 | |
89 | Commit Formatting | |
90 | ~~~~~~~~~~~~~~~~~ | |
91 | ||
92 | Using these options, gitlink:git-rev-list[1] will act similar to the | |
93 | more specialized family of commit log tools: gitlink:git-log[1], | |
94 | gitlink:git-show[1], and gitlink:git-whatchanged[1] | |
95 | ||
331b51d2 | 96 | include::pretty-options.txt[] |
8c02eee2 JF |
97 | |
98 | --relative-date:: | |
99 | ||
a7b02ccf JH |
100 | Synonym for `--date=relative`. |
101 | ||
1701872f | 102 | --date={relative,local,default,iso,rfc}:: |
a7b02ccf | 103 | |
8c02eee2 JF |
104 | Only takes effect for dates shown in human-readable format, such |
105 | as when using "--pretty". | |
a7b02ccf JH |
106 | + |
107 | `--date=relative` shows dates relative to the current time, | |
108 | e.g. "2 hours ago". | |
109 | + | |
110 | `--date=local` shows timestamps in user's local timezone. | |
111 | + | |
1701872f JH |
112 | `--date=iso` (or `--date=iso8601`) shows timestamps in ISO 8601 format. |
113 | + | |
114 | `--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822 | |
115 | format, often found in E-mail messages. | |
116 | + | |
02783075 | 117 | `--date=short` shows only date but not time, in `YYYY-MM-DD` format. |
1701872f | 118 | + |
a7b02ccf JH |
119 | `--date=default` shows timestamps in the original timezone |
120 | (either committer's or author's). | |
df8baa42 | 121 | |
69e0c256 | 122 | --header:: |
8c02eee2 JF |
123 | |
124 | Print the contents of the commit in raw-format; each record is | |
125 | separated with a NUL character. | |
69e0c256 | 126 | |
f443455a | 127 | --parents:: |
8c02eee2 | 128 | |
f443455a ML |
129 | Print the parents of the commit. |
130 | ||
e3c1500f JN |
131 | --timestamp:: |
132 | Print the raw commit timestamp. | |
133 | ||
b24bace5 BG |
134 | --left-right:: |
135 | ||
136 | Mark which side of a symmetric diff a commit is reachable from. | |
137 | Commits from the left side are prefixed with `<` and those from | |
138 | the right with `>`. If combined with `--boundary`, those | |
139 | commits are prefixed with `-`. | |
140 | + | |
141 | For example, if you have this topology: | |
142 | + | |
143 | ----------------------------------------------------------------------- | |
144 | y---b---b branch B | |
145 | / \ / | |
146 | / . | |
147 | / / \ | |
148 | o---x---a---a branch A | |
149 | ----------------------------------------------------------------------- | |
150 | + | |
151 | you would get an output line this: | |
152 | + | |
153 | ----------------------------------------------------------------------- | |
154 | $ git rev-list --left-right --boundary --pretty=oneline A...B | |
155 | ||
156 | >bbbbbbb... 3rd on b | |
157 | >bbbbbbb... 2nd on b | |
158 | <aaaaaaa... 3rd on a | |
159 | <aaaaaaa... 2nd on a | |
160 | -yyyyyyy... 1st on b | |
161 | -xxxxxxx... 1st on a | |
162 | ----------------------------------------------------------------------- | |
163 | ||
8c02eee2 JF |
164 | Diff Formatting |
165 | ~~~~~~~~~~~~~~~ | |
df8baa42 | 166 | |
8c02eee2 JF |
167 | Below are listed options that control the formatting of diff output. |
168 | Some of them are specific to gitlink:git-rev-list[1], however other diff | |
169 | options may be given. See gitlink:git-diff-files[1] for more options. | |
ec579767 | 170 | |
8c02eee2 JF |
171 | -c:: |
172 | ||
173 | This flag changes the way a merge commit is displayed. It shows | |
174 | the differences from each of the parents to the merge result | |
175 | simultaneously instead of showing pairwise diff between a parent | |
176 | and the result one at a time. Furthermore, it lists only files | |
177 | which were modified from all parents. | |
178 | ||
179 | --cc:: | |
180 | ||
181 | This flag implies the '-c' options and further compresses the | |
182 | patch output by omitting hunks that show differences from only | |
183 | one parent, or show the same change from all but one parent for | |
184 | an Octopus merge. | |
185 | ||
186 | -r:: | |
187 | ||
188 | Show recursive diffs. | |
189 | ||
190 | -t:: | |
191 | ||
192 | Show the tree objects in the diff output. This implies '-r'. | |
193 | ||
194 | Commit Limiting | |
195 | ~~~~~~~~~~~~~~~ | |
196 | ||
197 | Besides specifying a range of commits that should be listed using the | |
198 | special notations explained in the description, additional commit | |
199 | limiting may be applied. | |
200 | ||
201 | -- | |
202 | ||
203 | -n 'number', --max-count='number':: | |
69e0c256 | 204 | |
69e0c256 JH |
205 | Limit the number of commits output. |
206 | ||
d5db6c9e JH |
207 | --skip='number':: |
208 | ||
209 | Skip 'number' commits before starting to show the commit output. | |
210 | ||
8c02eee2 JF |
211 | --since='date', --after='date':: |
212 | ||
213 | Show commits more recent than a specific date. | |
214 | ||
215 | --until='date', --before='date':: | |
69e0c256 | 216 | |
8c02eee2 JF |
217 | Show commits older than a specific date. |
218 | ||
219 | --max-age='timestamp', --min-age='timestamp':: | |
220 | ||
221 | Limit the commits output to specified time range. | |
69e0c256 | 222 | |
bd95fcd3 JH |
223 | --author='pattern', --committer='pattern':: |
224 | ||
225 | Limit the commits output to ones with author/committer | |
a5c2d26a | 226 | header lines that match the specified pattern (regular expression). |
bd95fcd3 JH |
227 | |
228 | --grep='pattern':: | |
229 | ||
230 | Limit the commits output to ones with log message that | |
a5c2d26a | 231 | matches the specified pattern (regular expression). |
bd95fcd3 | 232 | |
e5633cbb | 233 | -i, --regexp-ignore-case:: |
93d496a5 PB |
234 | |
235 | Match the regexp limiting patterns without regard to letters case. | |
236 | ||
e5633cbb | 237 | -E, --extended-regexp:: |
93d496a5 PB |
238 | |
239 | Consider the limiting patterns to be extended regular expressions | |
240 | instead of the default basic regular expressions. | |
241 | ||
93b74bca | 242 | --remove-empty:: |
8c02eee2 | 243 | |
93b74bca JH |
244 | Stop when a given path disappears from the tree. |
245 | ||
29a6c3f8 JN |
246 | --full-history:: |
247 | ||
248 | Show also parts of history irrelevant to current state of a given | |
249 | path. This turns off history simplification, which removed merges | |
250 | which didn't change anything at all at some child. It will still actually | |
251 | simplify away merges that didn't change anything at all into either | |
252 | child. | |
253 | ||
f443455a | 254 | --no-merges:: |
8c02eee2 | 255 | |
f443455a ML |
256 | Do not print commits with more than one parent. |
257 | ||
0d2c9d67 | 258 | --not:: |
8c02eee2 JF |
259 | |
260 | Reverses the meaning of the '{caret}' prefix (or lack thereof) | |
261 | for all following revision specifiers, up to the next '--not'. | |
0d2c9d67 | 262 | |
69e0c256 | 263 | --all:: |
69e0c256 | 264 | |
8c02eee2 JF |
265 | Pretend as if all the refs in `$GIT_DIR/refs/` are listed on the |
266 | command line as '<commit>'. | |
69e0c256 | 267 | |
42cabc34 JH |
268 | --stdin:: |
269 | ||
270 | In addition to the '<commit>' listed on the command | |
271 | line, read them from the standard input. | |
55a643ed JH |
272 | |
273 | --cherry-pick:: | |
274 | ||
275 | Omit any commit that introduces the same change as | |
276 | another commit on the "other side" when the set of | |
277 | commits are limited with symmetric difference. | |
278 | + | |
279 | For example, if you have two branches, `A` and `B`, a usual way | |
280 | to list all commits on only one side of them is with | |
281 | `--left-right`, like the example above in the description of | |
282 | that option. It however shows the commits that were cherry-picked | |
283 | from the other branch (for example, "3rd on b" may be cherry-picked | |
284 | from branch A). With this option, such pairs of commits are | |
285 | excluded from the output. | |
42cabc34 | 286 | |
084ae0a7 | 287 | -g, --walk-reflogs:: |
911cedc9 JH |
288 | |
289 | Instead of walking the commit ancestry chain, walk | |
290 | reflog entries from the most recent one to older ones. | |
291 | When this option is used you cannot specify commits to | |
292 | exclude (that is, '{caret}commit', 'commit1..commit2', | |
293 | nor 'commit1...commit2' notations cannot be used). | |
294 | + | |
295 | With '\--pretty' format other than oneline (for obvious reasons), | |
296 | this causes the output to have two extra lines of information | |
967506bb | 297 | taken from the reflog. By default, 'commit@\{Nth}' notation is |
911cedc9 | 298 | used in the output. When the starting commit is specified as |
967506bb | 299 | 'commit@{now}', output also uses 'commit@\{timestamp}' notation |
4d12a471 JH |
300 | instead. Under '\--pretty=oneline', the commit message is |
301 | prefixed with this information on the same line. | |
620e729d QT |
302 | |
303 | Cannot be combined with '\--reverse'. | |
911cedc9 | 304 | |
d249b455 | 305 | --merge:: |
8c02eee2 | 306 | |
d249b455 UZ |
307 | After a failed merge, show refs that touch files having a |
308 | conflict and don't exist on all heads to merge. | |
309 | ||
8c02eee2 JF |
310 | --boundary:: |
311 | ||
312 | Output uninteresting commits at the boundary, which are usually | |
313 | not shown. | |
314 | ||
315 | --dense, --sparse:: | |
316 | ||
317 | When optional paths are given, the default behaviour ('--dense') is to | |
318 | only output commits that changes at least one of them, and also ignore | |
319 | merges that do not touch the given paths. | |
320 | ||
321 | Use the '--sparse' flag to makes the command output all eligible commits | |
322 | (still subject to count and age limitation), but apply merge | |
323 | simplification nevertheless. | |
324 | ||
325 | --bisect:: | |
326 | ||
327 | Limit output to the one commit object which is roughly halfway between | |
328 | the included and excluded commits. Thus, if | |
329 | ||
330 | ----------------------------------------------------------------------- | |
331 | $ git-rev-list --bisect foo ^bar ^baz | |
332 | ----------------------------------------------------------------------- | |
333 | ||
334 | outputs 'midpoint', the output of the two commands | |
335 | ||
336 | ----------------------------------------------------------------------- | |
337 | $ git-rev-list foo ^midpoint | |
338 | $ git-rev-list midpoint ^bar ^baz | |
339 | ----------------------------------------------------------------------- | |
340 | ||
341 | would be of roughly the same length. Finding the change which | |
342 | introduces a regression is thus reduced to a binary search: repeatedly | |
343 | generate and test new 'midpoint's until the commit chain is of length | |
344 | one. | |
345 | ||
457f08a0 JH |
346 | --bisect-vars:: |
347 | ||
348 | This calculates the same as `--bisect`, but outputs text ready | |
349 | to be eval'ed by the shell. These lines will assign the name of | |
350 | the midpoint revision to the variable `bisect_rev`, and the | |
351 | expected number of commits to be tested after `bisect_rev` is | |
352 | tested to `bisect_nr`, the expected number of commits to be | |
353 | tested if `bisect_rev` turns out to be good to `bisect_good`, | |
354 | the expected number of commits to be tested if `bisect_rev` | |
355 | turns out to be bad to `bisect_bad`, and the number of commits | |
356 | we are bisecting right now to `bisect_all`. | |
357 | ||
3ac9f612 CC |
358 | --bisect-all:: |
359 | ||
360 | This outputs all the commit objects between the included and excluded | |
361 | commits, ordered by their distance to the included and excluded | |
362 | commits. The farthest from them is displayed first. (This is the only | |
363 | one displayed by `--bisect`.) | |
364 | ||
365 | This is useful because it makes it easy to choose a good commit to | |
366 | test when you want to avoid to test some of them for some reason (they | |
367 | may not compile for example). | |
368 | ||
369 | This option can be used along with `--bisect-vars`, in this case, | |
370 | after all the sorted commit objects, there will be the same text as if | |
371 | `--bisect-vars` had been used alone. | |
372 | ||
8c02eee2 JF |
373 | -- |
374 | ||
375 | Commit Ordering | |
376 | ~~~~~~~~~~~~~~~ | |
377 | ||
378 | By default, the commits are shown in reverse chronological order. | |
379 | ||
380 | --topo-order:: | |
381 | ||
382 | This option makes them appear in topological order (i.e. | |
383 | descendant commits are shown before their parents). | |
384 | ||
385 | --date-order:: | |
386 | ||
387 | This option is similar to '--topo-order' in the sense that no | |
388 | parent comes before all of its children, but otherwise things | |
389 | are still ordered in the commit timestamp order. | |
390 | ||
9c5e66e9 JS |
391 | --reverse:: |
392 | ||
393 | Output the commits in reverse order. | |
620e729d | 394 | Cannot be combined with '\--walk-reflogs'. |
9c5e66e9 | 395 | |
8c02eee2 JF |
396 | Object Traversal |
397 | ~~~~~~~~~~~~~~~~ | |
398 | ||
399 | These options are mostly targeted for packing of git repositories. | |
400 | ||
401 | --objects:: | |
402 | ||
403 | Print the object IDs of any object referenced by the listed | |
404 | commits. 'git-rev-list --objects foo ^bar' thus means "send me | |
405 | all object IDs which I need to download if I have the commit | |
406 | object 'bar', but not 'foo'". | |
407 | ||
408 | --objects-edge:: | |
409 | ||
410 | Similar to '--objects', but also print the IDs of excluded | |
411 | commits prefixed with a "-" character. This is used by | |
412 | gitlink:git-pack-objects[1] to build "thin" pack, which records | |
413 | objects in deltified form based on objects contained in these | |
414 | excluded commits to reduce network traffic. | |
415 | ||
416 | --unpacked:: | |
417 | ||
418 | Only useful with '--objects'; print the object IDs that are not | |
419 | in packs. | |
3dfb9278 | 420 | |
8e64006e JS |
421 | --no-walk:: |
422 | ||
423 | Only show the given revs, but do not traverse their ancestors. | |
424 | ||
425 | --do-walk:: | |
426 | ||
427 | Overrides a previous --no-walk. | |
428 | ||
331b51d2 JN |
429 | |
430 | include::pretty-formats.txt[] | |
431 | ||
432 | ||
2cf565c5 DG |
433 | Author |
434 | ------ | |
435 | Written by Linus Torvalds <torvalds@osdl.org> | |
436 | ||
437 | Documentation | |
438 | -------------- | |
8c02eee2 JF |
439 | Documentation by David Greaves, Junio C Hamano, Jonas Fonseca |
440 | and the git-list <git@vger.kernel.org>. | |
2cf565c5 DG |
441 | |
442 | GIT | |
443 | --- | |
a7154e91 | 444 | Part of the gitlink:git[7] suite |