[PATCH] Documentation: document pitfalls with 3-way merge

[PATCH] Documentation: document pitfalls with 3-way merge

[brian m. carlson]

Oftentimes people will make the same change in two branches, revert the change
in one branch, and then be surprised when a merge reinstitutes that change when
the branches are merged.  Add an explanatory paragraph that explains that this
occurs and the reason why, so people are not surprised.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
This is a documentation fix that I've been holding onto for a week or so.  I
noticed that a lot of people were surprised by this behavior, and figured it
would be better to document it.  I'm not sure that this is the right place for
it, and I'm happy to take suggestions on how to improve the wording.

 Documentation/merge-strategies.txt | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt
index 49a9a7d..fb6e593 100644
--- a/Documentation/merge-strategies.txt
+++ b/Documentation/merge-strategies.txt
@@ -113,3 +113,11 @@ subtree::
 	match the tree structure of A, instead of reading the trees at
 	the same level. This adjustment is also done to the common
 	ancestor tree.
+
+With the strategies that use 3-way merge (including the default, 'recursive'),
+if a change is made on both branches, but later reverted on one of the
+branches, that change will be present in the merged result; some people find
+this behavior confusing.  It occurs because only the heads and the merge base
+are considered when performing a merge, not the individual commits.  The merge
+algorithm therefore considers the reverted change as no change at all, and
+substitutes the changed version instead.
-- 
1.8.5.1

Re: [PATCH] Documentation: document pitfalls with 3-way merge

[Jonathan Nieder]

Hi,

brian m. carlson wrote:

> Oftentimes people will make the same change in two branches, revert the change
> in one branch, and then be surprised when a merge reinstitutes that change when
> the branches are merged.

Life is even more complicated: if the merge-base chosen happens to be
a descendent of the change on both branches, the merge won't reinstate
the change.

The problem scenario hasn't happened to me recently.  Can you give an
example of how it happens?  Why is the same change being made
independently on two different branches?  I'm wondering because such a
story could make the example in the documentation a little clearer and
avoid having to make the explanation overly technical.

In any event, that the 3-way merge is really just a stupid 3-way merge
(modulo multiple merge base madness) does seem worth emphasizing, so
thanks for working on this.

Hope that helps,
Jonathan

Re: [PATCH] Documentation: document pitfalls with 3-way merge

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 1997 bytes --]

On Sun, Dec 08, 2013 at 02:40:13PM -0800, Jonathan Nieder wrote:
> brian m. carlson wrote:
> 
> > Oftentimes people will make the same change in two branches, revert
> > the change in one branch, and then be surprised when a merge
> > reinstitutes that change when the branches are merged.
> 
> Life is even more complicated: if the merge-base chosen happens to be
> a descendent of the change on both branches, the merge won't reinstate
> the change.

Right.  The text should probably be clearer in that respect.

> The problem scenario hasn't happened to me recently.  Can you give an
> example of how it happens?  Why is the same change being made
> independently on two different branches?  I'm wondering because such a
> story could make the example in the documentation a little clearer and
> avoid having to make the explanation overly technical.

It happens pretty much as I described.  There have been two different
posters to the list who have made the same change on both branches,
reverted it on one, and then were surprised when it was reinstated
during the merge.  Generally people expect conflicts in this case.

I don't have any further details, since it hasn't happened to me and I'm
not either one of those posters, but I suspect if someone did a
cherry-pick of a change from one branch to another that could happen.
Maybe an important bug fix was picked from a topic branch, but the
change was reverted because the problem was solved in a better way.

> In any event, that the 3-way merge is really just a stupid 3-way merge
> (modulo multiple merge base madness) does seem worth emphasizing, so
> thanks for working on this.

My goal is simply to stop having to answer the same question on the list
twice within two weeks. :-)

-- 
brian m. carlson / brian with sandals: Houston, Texas, US
+1 832 623 2791 | http://www.crustytoothpaste.net/~bmc | My opinion only
OpenPGP: RSA v4 4096b: 88AC E9B2 9196 305B A994 7552 F1BA 225C 0223 B187

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]