Re: [PATCH v4] user-manual: Add section "Why bisecting merge commits can be harder ..."

> +[[bisect-merges]]
> +Why bisecting merge commits can be harder than bisecting linear history
> +-----------------------------------------------------------------------
> +
> +This section discusses how gitlink:git-bisect[1] plays
> +with differently shaped histories.  The text is based upon
> +an email by Junio C. Hamano to the git mailing list
> +(link:http://marc.info/?l=git&m=119403257315527&w=2[link:http://marc.info/?l=git&m=119403257315527&w=2]).
> +It was adapted for the user manual.

> +
> +Using gitlink:git-bisect[1] on a history with merges can be
> +challenging.  Bisecting through merges is not a technical
> +problem. The real problem is what to do when the culprit turns
> +out to be a merge commit.  How to spot what really is wrong, and
> +figure out how to fix it.  The problem is not for the tool but
> +for the human, and it is real.

> +
> +Imagine this history:
> +
> +................................................
> +      ---Z---o---X---...---o---A---C---D
> +          \                       /
> +           o---o---Y---...---o---B
> +................................................
> +
> +Suppose that on the upper development line, the meaning of one
> +of the functions that existed at Z was changed at commit X.  The
> +commits from Z leading to A change both the function's
> +implementation and all calling sites that existed at Z, as well
> +as new calling sites they add, to be consistent.  There is no
> +bug at A.
> +
> +Suppose that in the meantime the lower development line somebody
> +added a new calling site for that function at commit Y.  The
> +commits from Z leading to B all assume the old semantics of that
> +function and the callers and the callee are consistent with each
> +other.  There is no bug at B, either.
> +
> +Suppose further that the two development lines were merged at C
> +and there was no textual conflict with this three way merge.
> +The result merged cleanly.
> +
> +Now, during bisect you find that the merge C is broken.  You
> +started to bisect, because you found D is bad and you know Z was
> +good.  The breakage is understandable, as at C, the new calling
> +site of the function added by the lower branch is not converted
> +to the new semantics, while all the other calling sites that
> +already existed at Z would have been converted by the merge.  The
> +new calling site has semantic adjustment needed, but you do not
> +know that yet.
> +
> +You need to find out what is the cause of the breakage by looking
> +at the merge commit C and the history leading to it.  How would
> +you do that?
> +
> +Both "git diff A C" and "git diff B C" would be an enormous patch.
> +Each of them essentially shows the whole change on each branch
> +since they diverged.  The developers may have well behaved to
> +create good commits that follow the "commit small, commit often,
> +commit well contained units" mantra, and each individual commit
> +leading from Z to A and from Z to B may be easy to review and
> +understand, but looking at these small and easily reviewable
> +steps alone would not let you spot the breakage.  You need to
> +have a global picture of what the upper branch did (and
> +among many, one of them is to change the semantics of that
> +particular function) and look first at the huge "diff A C"
> +(which shows the change the lower branch introduces), and see if
> +that huge change is consistent with what have been done between
> +Z and A.
> +
> +On the other hand, if you did not merge at C but rebased the
> +history between Z to B on top of A, you would have get this
> +linear history:
> +
> +................................................................
> +    ---Z---o---X--...---o---A---o---o---Y*--...---o---B*--D*
> +................................................................
> +
> +Bisecting between Z and D* would hit a single culprit commit Y*
> +instead.  This tends to be easier to understand why it is broken.
> +
> +For this reason, many experienced git users, even when they are
> +working on an otherwise merge-heavy project, keep the histories
> +linear by rebasing their work on top of public upstreams before
> +publishing.