Re: [PATCH] simplify history by default

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 30, 2007, 07:25 UTC
Message-ID: <7vir6x8ow2.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <20070830062512.GB16312@mellanox.co.il>

"Michael S. Tsirkin" <mst@dev.mellanox.co.il> writes:

> Which is better IMO, because the a branch is actually ignored.
> But, is this behaviour documented?

Formal documentation is probably lacking. Both Linus and I have explained this "history simplification" countless times here and on #git. As a matter of fact, I think I did my latest round of explanation on #git just a few days ago.

The thing is, neither of us is very good at documention --- we tend to offer explanation on demand _in context_.

Show 12 quoted lines

> Further, man git-rev-list says
> --full-history::
>
> 	Show also parts of history irrelevant to current state of a given path.
> 		This turns off history simplification, which removed merges
> 		which didn't change anything at all at some child. It will still
> 		actually simplify away merges that didn't change anything at all
> 		into either child.
>
> which makes it seem like the default should be to do history simplification, but
> what actually happens is that the default is not to do simplification
> unless you give a path, in which case the default is to do simplification,

I would agree around the part you quoted is a good place to add descriptions we gave in the past, and it is a good idea to do so at the very technical level.

At the same time, I think section #2 of the user manual "Exploring git history" should talk about path limited, simplified history, in its "Browsing revisions" subsection, when it gives the example

	$ git log v2.5.. Makefile fs/

As the previous section has already introduced the history diagram, it would help to draw a merge graph and how the history is simplified.

Slides #116, #117 and #118 from

	http://members.cox.net/junkio/200607-ols.pdf

talk about history simplification, which may be a good starting point to steal from.

As to your patch, I am a bit reluctant to make the history simplification for the "whole tree" history traversal default, even with --no-merges. One thing we often use --no-merges is for shortlog and I do want to see commits from both branches, when I have something like this:

 ... maint ...----o----A----B---C'
                             \   \
                              \   \
 ... master ... -----o----C----M---N

where I first made a fix C on the 'master' branch, later backported it to 'maint' as C' to fix the same issue (but applicable for the context of 'maint'). The merge made at N will most likely result as if 'maint' was merged using 'ours' strategy to 'master' because at point M, the master branch is supposed to be in sync with and contain everything from 'maint', including the effect C' would bring to 'maint'. I feel somewhat uneasy to drop C' when I am preparing to write release notes for N (or later). Maybe this is just superstition, but when not using path-limiting, I am really interested in who contributed in the whole system, whether the fruits of their efforts survived at the end or not. The use case is quite different when looking at history with path limiters.