@matheusbsbs / matheus-bagliano / commits / 8c02eee29e
Fork 0

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 -