Re: [RFC PATCH] Documentation: rev-list-options: clarify history simplification with paths

[Junio C Hamano <gitster@pobox.com>]

Thomas Rast <trast@student.ethz.ch> 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.