@matheusbsbs / matheus-bagliano / commits / 3fb0028253
Fork 0

user-manual: Add section "Why bisecting merge commits can be harder ..."

This commit adds a discussion of the challenge of bisecting merge commits to the user manual. The original author is Junio C Hamano <gitster@pobox.com>, who posted the text to the mailing list <http://marc.info/?l=git&m=119403257315527&w=2>. His email was adapted for the manual. The discussion is added to "Rewriting history and maintainig patch series". The text added requires good understanding of merging and rebasing. Therefore it should not be placed too early in the manual. Right after the section on "Problems with rewriting history", the discussion of bisect gives another reason for linearizing as much of the history as possible. The text includes suggestions and fixes by Ralf Wildenhues <Ralf.Wildenhues@gmx.de> and Benoit Sigoure <tsuna@lrde.epita.fr>. Signed-off-by: Steffen Prohaska <prohaska@zib.de> Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>

Steffen Prohaska committed Nov 10, 2007 at 14:49 UTC 3fb00282538409daf4d05ce4631a2c3eae235c69
1 file changed +66
Documentation/user-manual.txt
+66
@@ -2554,6 +2554,72 @@ branches into their own work.
2554 For true distributed development that supports proper merging,
2555 published branches should never be rewritten.
2556
2557 +[[bisect-merges]]
2558 +Why bisecting merge commits can be harder than bisecting linear history
2559 +-----------------------------------------------------------------------
2560 +
2561 +The gitlink:git-bisect[1] command correctly handles history that
2562 +includes merge commits. However, when the commit that it finds is a
2563 +merge commit, the user may need to work harder than usual to figure out
2564 +why that commit introduced a problem.
2565 +
2566 +Imagine this history:
2567 +
2568 +................................................
2569 + ---Z---o---X---...---o---A---C---D
2570 + \ /
2571 + o---o---Y---...---o---B
2572 +................................................
2573 +
2574 +Suppose that on the upper line of development, the meaning of one
2575 +of the functions that exists at Z is changed at commit X. The
2576 +commits from Z leading to A change both the function's
2577 +implementation and all calling sites that exist at Z, as well
2578 +as new calling sites they add, to be consistent. There is no
2579 +bug at A.
2580 +
2581 +Suppose that in the meantime on the lower line of development somebody
2582 +adds a new calling site for that function at commit Y. The
2583 +commits from Z leading to B all assume the old semantics of that
2584 +function and the callers and the callee are consistent with each
2585 +other. There is no bug at B, either.
2586 +
2587 +Suppose further that the two development lines merge cleanly at C,
2588 +so no conflict resolution is required.
2589 +
2590 +Nevertheless, the code at C is broken, because the callers added
2591 +on the lower line of development have not been converted to the new
2592 +semantics introduced on the upper line of development. So if all
2593 +you know is that D is bad, that Z is good, and that
2594 +gitlink:git-bisect[1] identifies C as the culprit, how will you
2595 +figure out that the problem is due to this change in semantics?
2596 +
2597 +When the result of a git-bisect is a non-merge commit, you should
2598 +normally be able to discover the problem by examining just that commit.
2599 +Developers can make this easy by breaking their changes into small
2600 +self-contained commits. That won't help in the case above, however,
2601 +because the problem isn't obvious from examination of any single
2602 +commit; instead, a global view of the development is required. To
2603 +make matters worse, the change in semantics in the problematic
2604 +function may be just one small part of the changes in the upper
2605 +line of development.
2606 +
2607 +On the other hand, if instead of merging at C you had rebased the
2608 +history between Z to B on top of A, you would have gotten this
2609 +linear history:
2610 +
2611 +................................................................
2612 + ---Z---o---X--...---o---A---o---o---Y*--...---o---B*--D*
2613 +................................................................
2614 +
2615 +Bisecting between Z and D* would hit a single culprit commit Y*,
2616 +and understanding why Y* was broken would probably be easier.
2617 +
2618 +Partly for this reason, many experienced git users, even when
2619 +working on an otherwise merge-heavy project, keep the history
2620 +linear by rebasing against the latest upstream version before
2621 +publishing.
2622 +
2623 [[advanced-branch-management]]
2624 Advanced branch management
2625 ==========================