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