Skip to content

Commit

Permalink
Documentation/rev-list-options.txt: Explain --ancestry-path
Browse files Browse the repository at this point in the history
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>
  • Loading branch information
Johan Herland authored and Junio C Hamano committed Jun 6, 2010
1 parent f70d058 commit 57456ef
Showing 1 changed file with 48 additions and 2 deletions.
50 changes: 48 additions & 2 deletions Documentation/rev-list-options.txt
Original file line number Diff line number Diff line change
Expand Up @@ -384,6 +384,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
Expand Down Expand Up @@ -511,8 +519,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
Expand Down Expand Up @@ -554,6 +560,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
Expand Down

0 comments on commit 57456ef

Please sign in to comment.