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.
+
+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.