Documentation/rev-list-options.txt: Explain --ancestry-path
Add a short paragraph explaining --ancestry-path, followed by a more detailed example. This mirrors how the other history simplification options are documented. Signed-off-by: Johan Herland <johan@herland.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Johan Herland committed
Jun 4, 2010 at 01:17 UTC
57456ef459f137cf81c1875f771ab9485b1fa810
1 file changed
+48
-2
Documentation/rev-list-options.txt
+48
-2
@@ -384,6 +384,14 @@ Default mode::
384
merges from the resulting history, as there are no selected
385
commits contributing to this merge.
386
387
+--ancestry-path::
388
+
389
+ When given a range of commits to display (e.g. 'commit1..commit2'
390
+ or 'commit2 {caret}commit1'), only display commits that exist
391
+ directly on the ancestry chain between the 'commit1' and
392
+ 'commit2', i.e. commits that are both descendants of 'commit1',
393
+ and ancestors of 'commit2'.
394
+
395
A more detailed explanation follows.
396
397
Suppose you specified `foo` as the <paths>. We shall call commits
@@ -511,8 +519,6 @@ Note that without '\--full-history', this still simplifies merges: if
519
one of the parents is TREESAME, we follow only that one, so the other
520
sides of the merge are never walked.
521
514
-Finally, there is a fourth simplification mode available:
515
-
522
--simplify-merges::
523
524
First, build a history graph in the same way that
@@ -554,6 +560,46 @@ Note the major differences in `N` and `P` over '\--full-history':
560
removed completely, because it had one parent and is TREESAME.
561
--
562
563
+Finally, there is a fifth simplification mode available:
564
+
565
+--ancestry-path::
566
+
567
+ Limit the displayed commits to those directly on the ancestry
568
+ chain between the "from" and "to" commits in the given commit
569
+ range. I.e. only display commits that are ancestor of the "to"
570
+ commit, and descendants of the "from" commit.
571
++
572
+As an example use case, consider the following commit history:
573
++
574
+-----------------------------------------------------------------------
575
+ D---E-------F
576
+ / \ \
577
+ B---C---G---H---I---J
578
+ / \
579
+ A-------K---------------L--M
580
+-----------------------------------------------------------------------
581
++
582
+A regular 'D..M' computes the set of commits that are ancestors of `M`,
583
+but excludes the ones that are ancestors of `D`. This is useful to see
584
+what happened to the history leading to `M` since `D`, in the sense
585
+that "what does `M` have that did not exist in `D`". The result in this
586
+example would be all the commits, except `A` and `B` (and `D` itself,
587
+of course).
588
++
589
+When we want to find out what commits in `M` are contaminated with the
590
+bug introduced by `D` and need fixing, however, we might want to view
591
+only the subset of 'D..M' that are actually descendants of `D`, i.e.
592
+excluding `C` and `K`. This is exactly what the '\--ancestry-path'
593
+option does. Applied to the 'D..M' range, it results in:
594
++
595
+-----------------------------------------------------------------------
596
+ E-------F
597
+ \ \
598
+ G---H---I---J
599
+ \
600
+ L--M
601
+-----------------------------------------------------------------------
602
+
603
The '\--simplify-by-decoration' option allows you to view only the
604
big picture of the topology of the history, by omitting commits
605
that are not referenced by tags. Commits are marked as !TREESAME