Thomas Rast <trast@xxxxxxxxxxxxxxx> writes:
> diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
> index ee6822a..0eaefd2 100644
> --- a/Documentation/rev-list-options.txt
> +++ b/Documentation/rev-list-options.txt
> @@ -191,20 +191,6 @@ endif::git-rev-list[]
> ...
> +--
What was the meaning of the double-dash at the beginning of line in
AsciiDoc markup? I forgot.
> +History Simplification
> +~~~~~~~~~~~~~~~~~~~~~~
> +
> +When optional paths are given, 'git-rev-list' simplifies merge and
> +non-merge commits separately. First, all non-merge commits that do
> +not touch the given paths are marked as such. We'll call them
> +'non-touching' commits, and all other commits 'touching'.
> +
> +Second, merges are simplified. You can choose three levels. We
> +illustrate the strategies with the following example history, where
> +touching commits are shown with capital letters and both B and C
> +contain the same changes:
> +
> +-----------------------------------------------------------------------
> + o -- A -- B -- m
> + |\ /|
> + | \- C -/ |
> + \ /
> + \-- d --/
> +-----------------------------------------------------------------------
Please draw it a bit more consistently with pictures in other existing
documentation, perhaps like this:
d---.
/ \
o---A---B---m
\ /
C---.
> +--prune-merges::
> +
> + This is the default. A merge is has its parents rewritten as
> + follows:
> ++
> + * All parents that do not have any touching ancestors are
> + removed.
> ++
> + * Of a set of parents that agree on the path contents, only
> + the first is kept.
> ++
> +In our example, we get the following:
> ++
> +-----------------------------------------------------------------------
> + o -- A -- B -- m
> +-----------------------------------------------------------------------
I'd rather make this the part of the base text. In other words, remove
the "--prune-merges" header, dedent the description and start the sentence
with "By default, parents of a merge is rewritten with the following
rules:".
Then before listing the options, say something like "You can influence how
simplification works using the following options".
> +--simplify-merges::
> +
> + For each commit C, compute its replacement in the final history:
> ++
> +* First compute the replacements of all parents of C, and
> + rewrite C to have these parents. Then remove parents that
> + are either identical to or ancestors of an existing parent.
> ++
> +* If, after this simplification, the commit is touching, a root or
> + merge commit, or marked as uninteresting, it remains.
> ++
> +In the example, history is simplified as follows. (Note that while
> +'o' remains, it will not be output with '\--dense'.)
> ++
Also this option implies --full-history's true meaning "do not cull side
branches even when they led to the same conclusion", with --parent's
meaning "do not drop merges that are necessary to keep the rewritten
history still connected".
> +-----------------------------------------------------------------------
> + o -- A -- B -- m
> + \ /
> + \- C -/
> +-----------------------------------------------------------------------
Same comment on the way the picture is drawn.
> +--full-history::
> +
> + Do not simplify merges at all. Their ancestor lines are still
> + only shown if they have any touching commits, but the merges
> + themselves are always output.
With clarification from Linus yesterday, this would need rewording. It is
not about "simplifying merges", but its main focus is "do not cull side
branches". When --parents is in effect, merges need to be shown because
otherwise the resulting list of commits won't be connected, but otherwise
you are getting a flat list of commits and useless merges won't be shown.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
