Re: [PATCH] simplify history by default

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

"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_.

> 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.