Documentation: document pitfalls with 3-way merge
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> Signed-off-by: Junio C Hamano <gitster@pobox.com>
brian m. carlson committed
Dec 8, 2013 at 20:40 UTC
c5665000327388832fa8be0b3bf17669f672481b
1 file changed
+8
Documentation/merge-strategies.txt
+8
@@ -113,3 +113,11 @@ subtree::
113
match the tree structure of A, instead of reading the trees at
114
the same level. This adjustment is also done to the common
115
ancestor tree.
116
+
117
+With the strategies that use 3-way merge (including the default, 'recursive'),
118
+if a change is made on both branches, but later reverted on one of the
119
+branches, that change will be present in the merged result; some people find
120
+this behavior confusing. It occurs because only the heads and the merge base
121
+are considered when performing a merge, not the individual commits. The merge
122
+algorithm therefore considers the reverted change as no change at all, and
123
+substitutes the changed version instead.