rev-list documentation: clarify the two parts of history simplification
One set of options and parameters determine what commits are involved in the simplification process, and another set of options determine how the simplification is done. Clarify their distinction at the beginning. Signed-off-by: Santi Béjar <santi@agolina.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Santi Béjar committed
Nov 12, 2008 at 11:51 UTC
7bc2508bfe0f7e8c0371a68f57ac5b7d4fe7e1f0
1 file changed
+46
-2
Documentation/rev-list-options.txt
+46
-2
@@ -285,8 +285,52 @@ See also linkgit:git-reflog[1].
285
History Simplification
286
~~~~~~~~~~~~~~~~~~~~~~
287
288
-When optional paths are given, 'git-rev-list' simplifies commits with
289
-various strategies, according to the options you have selected.
288
+Sometimes you are only interested in parts of the history, for example the
289
+commits modifying a particular <path>. But there are two parts of
290
+'History Simplification', one part is selecting the commits and the other
291
+is how to do it, as there are various strategies to simplify the history.
292
+
293
+The following options select the commits to be shown:
294
+
295
+<paths>::
296
+
297
+ Commits modifying the given <paths> are selected.
298
+
299
+--simplify-by-decoration::
300
+
301
+ Commits that are referred by some branch or tag are selected.
302
+
303
+Note that extra commits can be shown to give a meaningful history.
304
+
305
+The following options affect the way the simplification is performed:
306
+
307
+Default mode::
308
+
309
+ Simplifies the history to the simplest history explaining the
310
+ final state of the tree. Simplest because it prunes some side
311
+ branches if the end result is the same (i.e. merging branches
312
+ with the same content)
313
+
314
+--full-history::
315
+
316
+ As the default mode but does not prune some history.
317
+
318
+--dense::
319
+
320
+ Only the selected commits are shown, plus some to have a
321
+ meaningful history.
322
+
323
+--sparse::
324
+
325
+ All commits in the simplified history are shown.
326
+
327
+--simplify-merges::
328
+
329
+ Additional option to '--full-history' to remove some needless
330
+ merges from the resulting history, as there are no selected
331
+ commits contributing to this merge.
332
+
333
+A more detailed explanation follows.
334
335
Suppose you specified `foo` as the <paths>. We shall call commits
336
that modify `foo` !TREESAME, and the rest TREESAME. (In a diff