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

From: Thomas Rast <trast@student.ethz.ch>
Date: Aug 10, 2008, 21:31 UTC
Message-ID: <200808102331.55385.trast@student.ethz.ch>
In-Reply-To: <7vabfk3cge.fsf@gitster.siamese.dyndns.org>

Junio C Hamano wrote:

Show 10 quoted lines

> 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

[...]

Show 5 quoted lines

> 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