Merge branch 'jn/grep-open'

[thirdparty/git.git] / Documentation / rev-list-options.txt

diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index b9fb7a86bd4bf91205b77275fb51ff13a3bc5622..cc562a057af3694d3518bc91b52ae322b6b1d9cc 100644 (file)
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -98,6 +98,15 @@ you would get an output like this:
 This implies the '--topo-order' option by default, but the
 '--date-order' option may also be specified.
 
+ifdef::git-rev-list[]
+--count::
+       Print a number stating how many commits would have been
+       listed, and suppress all other output.  When used together
+       with '--left-right', instead print the counts for left and
+       right commits, separated by a tab.
+endif::git-rev-list[]
+
+
 ifndef::git-rev-list[]
 Diff Formatting
 ~~~~~~~~~~~~~~~
@@ -384,6 +393,14 @@ Default mode::
        merges from the resulting history, as there are no selected
        commits contributing to this merge.
 
+--ancestry-path::
+
+       When given a range of commits to display (e.g. 'commit1..commit2'
+       or 'commit2 {caret}commit1'), only display commits that exist
+       directly on the ancestry chain between the 'commit1' and
+       'commit2', i.e. commits that are both descendants of 'commit1',
+       and ancestors of 'commit2'.
+
 A more detailed explanation follows.
 
 Suppose you specified `foo` as the <paths>.  We shall call commits
@@ -440,7 +457,7 @@ This results in:
 +
 -----------------------------------------------------------------------
          .-A---N---O
-        /         /
+        /     /   /
        I---------D
 -----------------------------------------------------------------------
 +
@@ -511,8 +528,6 @@ Note that without '\--full-history', this still simplifies merges: if
 one of the parents is TREESAME, we follow only that one, so the other
 sides of the merge are never walked.
 
-Finally, there is a fourth simplification mode available:
-
 --simplify-merges::
 
        First, build a history graph in the same way that
@@ -554,6 +569,46 @@ Note the major differences in `N` and `P` over '\--full-history':
   removed completely, because it had one parent and is TREESAME.
 --
 
+Finally, there is a fifth simplification mode available:
+
+--ancestry-path::
+
+       Limit the displayed commits to those directly on the ancestry
+       chain between the "from" and "to" commits in the given commit
+       range. I.e. only display commits that are ancestor of the "to"
+       commit, and descendants of the "from" commit.
++
+As an example use case, consider the following commit history:
++
+-----------------------------------------------------------------------
+           D---E-------F
+          /     \       \
+         B---C---G---H---I---J
+        /                     \
+       A-------K---------------L--M
+-----------------------------------------------------------------------
++
+A regular 'D..M' computes the set of commits that are ancestors of `M`,
+but excludes the ones that are ancestors of `D`. This is useful to see
+what happened to the history leading to `M` since `D`, in the sense
+that "what does `M` have that did not exist in `D`". The result in this
+example would be all the commits, except `A` and `B` (and `D` itself,
+of course).
++
+When we want to find out what commits in `M` are contaminated with the
+bug introduced by `D` and need fixing, however, we might want to view
+only the subset of 'D..M' that are actually descendants of `D`, i.e.
+excluding `C` and `K`. This is exactly what the '\--ancestry-path'
+option does. Applied to the 'D..M' range, it results in:
++
+-----------------------------------------------------------------------
+               E-------F
+                \       \
+                 G---H---I---J
+                              \
+                               L--M
+-----------------------------------------------------------------------
+
 The '\--simplify-by-decoration' option allows you to view only the
 big picture of the topology of the history, by omitting commits
 that are not referenced by tags.  Commits are marked as !TREESAME