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>

diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt
index 49a9a7d53f5836ecf2c5bcadb30f0d314414afe0..fb6e593e7c6f287612f30be6206c0492d77e38d3 100644 (file)
--- 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.
        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.