1 git-rev-list(1)
2 ===============
4 NAME
5 ----
6 git-rev-list - Lists commit objects in reverse chronological order
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>... ]
32 DESCRIPTION
33 -----------
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.
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:
43 -----------------------------------------------------------------------
44 $ git-rev-list foo bar ^baz
45 -----------------------------------------------------------------------
47 means "list all the commits which are included in 'foo' and 'bar', but
48 not in 'baz'".
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:
54 -----------------------------------------------------------------------
55 $ git-rev-list origin..HEAD
56 $ git-rev-list HEAD ^origin
57 -----------------------------------------------------------------------
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:
63 -----------------------------------------------------------------------
64 $ git-rev-list A B --not $(git-merge-base --all A B)
65 $ git-rev-list A...B
66 -----------------------------------------------------------------------
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].
74 OPTIONS
75 -------
77 Commit Formatting
78 ~~~~~~~~~~~~~~~~~
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]
84 include::pretty-formats.txt[]
86 --relative-date::
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".
92 --header::
94 Print the contents of the commit in raw-format; each record is
95 separated with a NUL character.
97 --parents::
99 Print the parents of the commit.
101 Diff Formatting
102 ~~~~~~~~~~~~~~~
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.
108 -c::
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.
116 --cc::
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.
123 -r::
125 Show recursive diffs.
127 -t::
129 Show the tree objects in the diff output. This implies '-r'.
131 Commit Limiting
132 ~~~~~~~~~~~~~~~
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.
138 --
140 -n 'number', --max-count='number'::
142 Limit the number of commits output.
144 --skip='number'::
146 Skip 'number' commits before starting to show the commit output.
148 --since='date', --after='date'::
150 Show commits more recent than a specific date.
152 --until='date', --before='date'::
154 Show commits older than a specific date.
156 --max-age='timestamp', --min-age='timestamp'::
158 Limit the commits output to specified time range.
160 --author='pattern', --committer='pattern'::
162 Limit the commits output to ones with author/committer
163 header lines that match the specified pattern.
165 --grep='pattern'::
167 Limit the commits output to ones with log message that
168 matches the specified pattern.
170 --remove-empty::
172 Stop when a given path disappears from the tree.
174 --no-merges::
176 Do not print commits with more than one parent.
178 --not::
180 Reverses the meaning of the '{caret}' prefix (or lack thereof)
181 for all following revision specifiers, up to the next '--not'.
183 --all::
185 Pretend as if all the refs in `$GIT_DIR/refs/` are listed on the
186 command line as '<commit>'.
188 --stdin::
190 In addition to the '<commit>' listed on the command
191 line, read them from the standard input.
193 --walk-reflogs::
195 Instead of walking the commit ancestry chain, walk
196 reflog entries from the most recent one to older ones.
197 When this option is used you cannot specify commits to
198 exclude (that is, '{caret}commit', 'commit1..commit2',
199 nor 'commit1...commit2' notations cannot be used).
200 +
201 With '\--pretty' format other than oneline (for obvious reasons),
202 this causes the output to have two extra lines of information
203 taken from the reflog. By default, 'commit@{Nth}' notation is
204 used in the output. When the starting commit is specified as
205 'commit@{now}', output also uses 'commit@{timestamp}' notation
206 instead.
208 --merge::
210 After a failed merge, show refs that touch files having a
211 conflict and don't exist on all heads to merge.
213 --boundary::
215 Output uninteresting commits at the boundary, which are usually
216 not shown.
218 --dense, --sparse::
220 When optional paths are given, the default behaviour ('--dense') is to
221 only output commits that changes at least one of them, and also ignore
222 merges that do not touch the given paths.
224 Use the '--sparse' flag to makes the command output all eligible commits
225 (still subject to count and age limitation), but apply merge
226 simplification nevertheless.
228 --bisect::
230 Limit output to the one commit object which is roughly halfway between
231 the included and excluded commits. Thus, if
233 -----------------------------------------------------------------------
234 $ git-rev-list --bisect foo ^bar ^baz
235 -----------------------------------------------------------------------
237 outputs 'midpoint', the output of the two commands
239 -----------------------------------------------------------------------
240 $ git-rev-list foo ^midpoint
241 $ git-rev-list midpoint ^bar ^baz
242 -----------------------------------------------------------------------
244 would be of roughly the same length. Finding the change which
245 introduces a regression is thus reduced to a binary search: repeatedly
246 generate and test new 'midpoint's until the commit chain is of length
247 one.
249 --
251 Commit Ordering
252 ~~~~~~~~~~~~~~~
254 By default, the commits are shown in reverse chronological order.
256 --topo-order::
258 This option makes them appear in topological order (i.e.
259 descendant commits are shown before their parents).
261 --date-order::
263 This option is similar to '--topo-order' in the sense that no
264 parent comes before all of its children, but otherwise things
265 are still ordered in the commit timestamp order.
267 Object Traversal
268 ~~~~~~~~~~~~~~~~
270 These options are mostly targeted for packing of git repositories.
272 --objects::
274 Print the object IDs of any object referenced by the listed
275 commits. 'git-rev-list --objects foo ^bar' thus means "send me
276 all object IDs which I need to download if I have the commit
277 object 'bar', but not 'foo'".
279 --objects-edge::
281 Similar to '--objects', but also print the IDs of excluded
282 commits prefixed with a "-" character. This is used by
283 gitlink:git-pack-objects[1] to build "thin" pack, which records
284 objects in deltified form based on objects contained in these
285 excluded commits to reduce network traffic.
287 --unpacked::
289 Only useful with '--objects'; print the object IDs that are not
290 in packs.
292 Author
293 ------
294 Written by Linus Torvalds <torvalds@osdl.org>
296 Documentation
297 --------------
298 Documentation by David Greaves, Junio C Hamano, Jonas Fonseca
299 and the git-list <git@vger.kernel.org>.
301 GIT
302 ---
303 Part of the gitlink:git[7] suite