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