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

[Thomas Rast <trast@student.ethz.ch>]

[-- Attachment #1: Type: text/plain, Size: 2816 bytes --]

Junio C Hamano wrote:
> Thomas Rast <trast@student.ethz.ch> writes:
> 
> >   $ g rev-list --pretty=oneline --full-history HEAD -- dir
> > ...
> > But --parents --full-history magically revives the merge:
> > ...
> 
> Personally I do not think --full-history without --parents is of much
> usefulness (I'd let Linus or somebody else defend this usage, or make it
> imply revs.rewrite_parents otherwise).

Well,

  --parents::
          Print the parents of the commit.

does not mention any change in behaviour.  I find it very surprising
that a simple commit formatting option changes the way commits are
_selected_.

> One thing I forgot to mention (but the code of course does not forget to
> do) in the series is that --simplify-merges implies revs.rewrite_parents
> which roughly translates to your experiments from the command line to
> always have --parents option.

Then it makes sense of course.

> >   $ git rev-list --pretty=oneline --sparse --parents --simplify-merges HEAD -- dir
[...]
> I am not sure what one should expect from combination between these two
> options.  --sparse says do not drop commits that are of no interest with
> respect to the paths specified, while --simplify-merges tells it to
> simplify merges so that the remaining graph shows only the ones that have
> relevance to !TREESAME (iow "has some changes") nodes.

It makes sense assuming a one-pass (plus simplify-merges) model.  It
did not fit into my two-pass model that I tried to come up with for an
easier explanation.

So in my current (ahem, new) understanding, that means (assuming the
side effect of --parents):

The simplification follows commits backwards into history according to
the following rules:

--dense:
	Non-merges are included if TREESAME[1], otherwise they are
	skipped.
--sparse:
	Non-merges are always included.

default:
	Merges are included unless they are TREESAME with a parent, in
	which case they are skipped and only that parent is followed.
--full-history:
	Merges are always included.

Conceptually, that builds a subset of the history, although it is
not kept in memory unless absolutely required.  Then:

--simplify-commits:
	Implies --full-history, then applies your algorithm on the
	resulting subset.

Which probably means that --sparse --simplify-commits makes no sense,
but explains the results.

Note that --full-history makes no exceptions, not even for merges that
are TREESAME w.r.t. all parents, unlike current docs state.  (This is
empirically correct.)  If the above is correct, and you think that has
some merit, I'll rewrite my patch to reflect this (with examples) to
update the docs.

- Thomas


[1] I still think "touching" was a pretty neat idea ;-)

-- 
Thomas Rast
trast@student.ethz.ch



[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 197 bytes --]