{"thread":{"id":"45584","subject":"[PATCH] Documentation: make 3-way merge warning more generic","startedAt":"2017-04-01T13:31:34Z","lastAt":"2017-04-01T19:26:39Z","messageCount":2,"participants":["brian m. carlson","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"316006","messageId":"20170401133124.10479-1-sandals@crustytoothpaste.net","threadId":"45584","inReplyTo":null,"subject":"[PATCH] Documentation: make 3-way merge warning more generic","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2017-04-01T13:31:24Z","receivedAt":"2017-04-01T13:31:34Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"The documentation for merge strategies noted that if a change was\nreverted on only one branch of a merge, the resultant merge would\ncontain the change.  However, similar surprising behavior can occur\nwhere cherry-picking only one commit from a series to the other branch\ncan cause conflicts.\n\nAdjust the text to state in the first sentence that only the heads and\nthe merge base are considered for three-way merge, instead of hiding\nthis in the second sentence after introducing a scenario which might not\napply to the user.  This makes it easier for users to understand by\nfirst introducing the general rule (which applies to many scenarios),\nand only then providing a specific example.\n\nSigned-off-by: brian m. carlson <sandals@crustytoothpaste.net>\n---\n\nI ran into this scenario with a co-worker who is a fairly advanced Git\nuser.  He created a series of five commits that modified a file on our\ndevelopment branch and requested the cherry-pick of one of those onto\nour maintenance branch.  When we merged the maintenance branch into the\ndevelopment branch, he was surprised that there were conflicts.  He\nexpected Git to realize that the commit was already present and ignore\nit.\n\nI pointed out the documentation to him, but realized that it didn't\ncover this case well, so I decided to reword it such that it covers this\ncase a little better, as well as addressing the original issue.\n\nFeedback on how I did in that regard would be welcome.\n\n Documentation/merge-strategies.txt | 12 ++++++------\n 1 file changed, 6 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt\nindex 2eb92b9327..54da2ffa33 100644\n--- a/Documentation/merge-strategies.txt\n+++ b/Documentation/merge-strategies.txt\n@@ -123,9 +123,9 @@ subtree::\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+only the heads and the merge base are considered when performing a merge, not\n+the individual commits.  This means that if a change is made on both branches,\n+but later reverted on one of the branches, that change will be present in the\n+merged result; some people find this behavior confusing.  The merge algorithm\n+considers the reverted change as no change at all, and substitutes the changed\n+version instead.\n-- \n2.12.2.564.g063fe858b8\n\n"},{"id":"316027","messageId":"xmqqpogwszdm.fsf@gitster.mtv.corp.google.com","threadId":"45584","inReplyTo":"20170401133124.10479-1-sandals@crustytoothpaste.net","subject":"Re: [PATCH] Documentation: make 3-way merge warning more generic","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-04-01T19:26:29Z","receivedAt":"2017-04-01T19:26:39Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"brian m. carlson\" <sandals@crustytoothpaste.net> writes:\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> +only the heads and the merge base are considered when performing a merge, not\n> +the individual commits.  This means that if a change is made on both branches,\n> +but later reverted on one of the branches, that change will be present in the\n> +merged result; some people find this behavior confusing.  The merge algorithm\n> +considers the reverted change as no change at all, and substitutes the changed\n> +version instead.\n\nI agree that it makes sense to say 3-way merge considers only three\npoints upfront.  \n\nI do not think \"this means\" is helpful to the readers, though.  Drop\n\"This means that\" and instead rewrite the remainder of the paragraph\nafter \"present in the merged result\", perhaps?\n\n\tIf a change is made on both branches but later reverted on\n\tone of the branches, the net effect the branch that reverted\n\tthe change has to the project is nothing, while the net\n\teffect of the other branch is to make that change.  The\n\t3-way merge, i.e. \"if one branch did something while the\n\tother branch didn't do that something, merge result is to do\n\tthat something\", rule keeps the change in the merge result.\n\nWe do not need to say \"some people find this confusing\" buried in a\nlong paragraph, which would not even serve the purpose of attracting\nreaders' eyes by shouting \"THIS MAY BE DIFFICULT, PAY ATTENTION\".\nThe last sentence in the original (and your version) only repeats\nthe same thing without saying what the real 3-way merge rule is, and\nI think a rewrite like the above that makes it more explicit is\neasier to understand.\n\n\n"}]}