{"thread":{"id":"35504","subject":"[PATCH] Documentation: document pitfalls with 3-way merge","startedAt":"2013-12-08T20:40:27Z","lastAt":"2013-12-08T22:55:20Z","messageCount":3,"participants":["brian m. carlson","Jonathan Nieder"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"231769","messageId":"1386535227-209788-1-git-send-email-sandals@crustytoothpaste.net","threadId":"35504","inReplyTo":null,"subject":"[PATCH] Documentation: document pitfalls with 3-way merge","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2013-12-08T20:40:27Z","receivedAt":"2013-12-08T20:40:27Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"Oftentimes people will make the same change in two branches, revert the change\nin one branch, and then be surprised when a merge reinstitutes that change when\nthe branches are merged.  Add an explanatory paragraph that explains that this\noccurs and the reason why, so people are not surprised.\n\nSigned-off-by: brian m. carlson <sandals@crustytoothpaste.net>\n---\nThis is a documentation fix that I've been holding onto for a week or so.  I\nnoticed that a lot of people were surprised by this behavior, and figured it\nwould be better to document it.  I'm not sure that this is the right place for\nit, and I'm happy to take suggestions on how to improve the wording.\n\n Documentation/merge-strategies.txt | 8 ++++++++\n 1 file changed, 8 insertions(+)\n\ndiff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt\nindex 49a9a7d..fb6e593 100644\n--- a/Documentation/merge-strategies.txt\n+++ b/Documentation/merge-strategies.txt\n@@ -113,3 +113,11 @@ subtree::\n \tmatch the tree structure of A, instead of reading the trees at\n \tthe same level. This adjustment is also done to the common\n \tancestor tree.\n+\n+With the strategies that use 3-way merge (including the default, 'recursive'),\n+if a change is made on both branches, but later reverted on one of the\n+branches, that change will be present in the merged result; some people find\n+this behavior confusing.  It occurs because only the heads and the merge base\n+are considered when performing a merge, not the individual commits.  The merge\n+algorithm therefore considers the reverted change as no change at all, and\n+substitutes the changed version instead.\n-- \n1.8.5.1\n"},{"id":"231773","messageId":"20131208224013.GC9108@google.com","threadId":"35504","inReplyTo":"1386535227-209788-1-git-send-email-sandals@crustytoothpaste.net","subject":"Re: [PATCH] Documentation: document pitfalls with 3-way merge","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2013-12-08T22:40:13Z","receivedAt":"2013-12-08T22:40:13Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Hi,\n\nbrian m. carlson wrote:\n\n> Oftentimes people will make the same change in two branches, revert the change\n> in one branch, and then be surprised when a merge reinstitutes that change when\n> the branches are merged.\n\nLife is even more complicated: if the merge-base chosen happens to be\na descendent of the change on both branches, the merge won't reinstate\nthe change.\n\nThe problem scenario hasn't happened to me recently.  Can you give an\nexample of how it happens?  Why is the same change being made\nindependently on two different branches?  I'm wondering because such a\nstory could make the example in the documentation a little clearer and\navoid having to make the explanation overly technical.\n\nIn any event, that the 3-way merge is really just a stupid 3-way merge\n(modulo multiple merge base madness) does seem worth emphasizing, so\nthanks for working on this.\n\nHope that helps,\nJonathan\n"},{"id":"231774","messageId":"20131208225519.GH118858@vauxhall.crustytoothpaste.net","threadId":"35504","inReplyTo":"20131208224013.GC9108@google.com","subject":"Re: [PATCH] Documentation: document pitfalls with 3-way merge","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2013-12-08T22:55:20Z","receivedAt":"2013-12-08T22:55:20Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On Sun, Dec 08, 2013 at 02:40:13PM -0800, Jonathan Nieder wrote:\n> brian m. carlson wrote:\n> \n> > Oftentimes people will make the same change in two branches, revert\n> > the change in one branch, and then be surprised when a merge\n> > reinstitutes that change when the branches are merged.\n> \n> Life is even more complicated: if the merge-base chosen happens to be\n> a descendent of the change on both branches, the merge won't reinstate\n> the change.\n\nRight.  The text should probably be clearer in that respect.\n\n> The problem scenario hasn't happened to me recently.  Can you give an\n> example of how it happens?  Why is the same change being made\n> independently on two different branches?  I'm wondering because such a\n> story could make the example in the documentation a little clearer and\n> avoid having to make the explanation overly technical.\n\nIt happens pretty much as I described.  There have been two different\nposters to the list who have made the same change on both branches,\nreverted it on one, and then were surprised when it was reinstated\nduring the merge.  Generally people expect conflicts in this case.\n\nI don't have any further details, since it hasn't happened to me and I'm\nnot either one of those posters, but I suspect if someone did a\ncherry-pick of a change from one branch to another that could happen.\nMaybe an important bug fix was picked from a topic branch, but the\nchange was reverted because the problem was solved in a better way.\n\n> In any event, that the 3-way merge is really just a stupid 3-way merge\n> (modulo multiple merge base madness) does seem worth emphasizing, so\n> thanks for working on this.\n\nMy goal is simply to stop having to answer the same question on the list\ntwice within two weeks. :-)\n\n-- \nbrian m. carlson / brian with sandals: Houston, Texas, US\n+1 832 623 2791 | http://www.crustytoothpaste.net/~bmc | My opinion only\nOpenPGP: RSA v4 4096b: 88AC E9B2 9196 305B A994 7552 F1BA 225C 0223 B187\n"}]}