{"thread":{"id":"61919","subject":"Documentation bug (?) when describing `zdiff3` merge format","startedAt":"2024-08-08T01:22:47Z","lastAt":"2024-08-08T20:25:59Z","messageCount":5,"participants":["punk.lion0906@fastmail.com","Johannes Sixt","Junio C Hamano","Kyle Lippincott"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"500379","messageId":"ab0fcc2e-936f-4d76-8059-fb2bc8a4f661@app.fastmail.com","threadId":"61919","inReplyTo":null,"subject":"Documentation bug (?) when describing `zdiff3` merge format","fromName":"","fromEmail":"punk.lion0906@fastmail.com","sentAt":"2024-08-08T01:22:26Z","receivedAt":"2024-08-08T01:22:47Z","isPatch":false,"sender":{"key":"punk.lion0906@fastmail.com","avatar":null},"body":"The docs at https://git-scm.com/docs/git-merge#_how_conflicts_are_presented describe the following snippets in `diff3` and `zdiff3` style as equivalent. They do not seem equivalent to me, so either this is a mistake or the `zdiff3` style is counterintuitive needs a better explanation.\n\ndiff3 style:\n\n```\nHere are lines that are either unchanged from the common\nancestor, or cleanly resolved because only one side changed,\n<<<<<<< yours:sample.txt\nor cleanly resolved because both sides changed the same way.\nConflict resolution is hard;\nlet's go shopping.\n||||||| base:sample.txt\nor cleanly resolved because both sides changed identically.\nConflict resolution is hard.\n=======\nor cleanly resolved because both sides changed the same way.\nGit makes conflict resolution easy.\n>>>>>>> theirs:sample.txt\nAnd here is another line that is cleanly resolved or unmodified.\n```\n\nzdiff3 style:\n\n```\nHere are lines that are either unchanged from the common\nancestor, or cleanly resolved because only one side changed,\nor cleanly resolved because both sides changed the same way.\n<<<<<<< yours:sample.txt\nConflict resolution is hard;\nlet's go shopping.\n||||||| base:sample.txt\nor cleanly resolved because both sides changed identically.\nConflict resolution is hard.\n=======\nGit makes conflict resolution easy.\n>>>>>>> theirs:sample.txt\nAnd here is another line that is cleanly resolved or unmodified.\n```\n\nThe problem is that, I believe, the \"or cleanly resolved because both sides changed identically.\" sentence should not be part of the **base** in the latter example, since that whole line was moved outside the conflict.\n\nI'd appreciate knowing which it is.\n\n Thanks,\n Ilya\n"},{"id":"500403","messageId":"a8bc907a-de6f-4b99-a72c-41dd885fde55@kdbg.org","threadId":"61919","inReplyTo":"ab0fcc2e-936f-4d76-8059-fb2bc8a4f661@app.fastmail.com","subject":"Re: Documentation bug (?) when describing `zdiff3` merge format","fromName":"Johannes Sixt","fromEmail":"j6t@kdbg.org","sentAt":"2024-08-08T06:49:35Z","receivedAt":"2024-08-08T06:49:53Z","isPatch":false,"sender":{"key":"j6t@kdbg.org","avatar":"https://avatars.githubusercontent.com/u/14810926?v=4"},"body":"Am 08.08.24 um 03:22 schrieb punk.lion0906@fastmail.com:\n> The docs at\n> https://git-scm.com/docs/git-merge#_how_conflicts_are_presented\n> describe the following snippets in `diff3` and `zdiff3` style as\n> equivalent. They do not seem equivalent to me, so either this is a\n> mistake or the `zdiff3` style is counterintuitive needs a better\n> explanation.\n\nI don't think that the documentation wants to claim any equivalence. I\ncan only see it says that \"diff3 shows the conflict like this\", and\n\"zdiff3 shows the conflict like that\".\n\n> zdiff3 style:\n> \n> ```\n> Here are lines that are either unchanged from the common\n> ancestor, or cleanly resolved because only one side changed,\n> or cleanly resolved because both sides changed the same way.\n> <<<<<<< yours:sample.txt\n> Conflict resolution is hard;\n> let's go shopping.\n> ||||||| base:sample.txt\n> or cleanly resolved because both sides changed identically.\n> Conflict resolution is hard.\n> =======\n> Git makes conflict resolution easy.\n>>>>>>>> theirs:sample.txt\n> And here is another line that is cleanly resolved or unmodified.\n> ```\n> \n> The problem is that, I believe, the \"or cleanly resolved because both\n> sides changed identically.\" sentence should not be part of the\n> **base** in the latter example, since that whole line was moved\n> outside the conflict.\nThis is exactly the problem that zdiff3 has: There is no way to indicate\nthat some line in the common ancester was resolved identically and is\nnow outside the conflict markers. Do not use zdiff3 if you cannot live\nwith this deficiency. This is in fact not made explicit in the\ndocumentation.\n\n-- Hannes\n\n"},{"id":"500489","messageId":"xmqqjzgrj8cf.fsf@gitster.g","threadId":"61919","inReplyTo":"a8bc907a-de6f-4b99-a72c-41dd885fde55@kdbg.org","subject":"Re: Documentation bug (?) when describing `zdiff3` merge format","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-08-08T16:19:12Z","receivedAt":"2024-08-08T16:19:24Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Johannes Sixt writes:\n\n> This is exactly the problem that zdiff3 has: There is no way to indicate\n> that some line in the common ancester was resolved identically and is\n> now outside the conflict markers. Do not use zdiff3 if you cannot live\n> with this deficiency. This is in fact not made explicit in the\n> documentation.\n\nYes, indeed that is a problem and that is not I personally do not\ntouch it even with a 10ft pole. We might want to stress it a bit\nmore to warn potential users in our documentation.\n\n#leftoverbits then?\n\nThanks.\n"},{"id":"500508","messageId":"CAO_smVg=1gFBudrd70V2_AXSPOUTFz=j7QqBpbkvR7P_KqnBtQ@mail.gmail.com","threadId":"61919","inReplyTo":"ab0fcc2e-936f-4d76-8059-fb2bc8a4f661@app.fastmail.com","subject":"Re: Documentation bug (?) when describing `zdiff3` merge format","fromName":"Kyle Lippincott","fromEmail":"spectral@google.com","sentAt":"2024-08-08T17:22:11Z","receivedAt":"2024-08-08T17:22:30Z","isPatch":false,"sender":{"key":"spectral@google.com","avatar":"https://avatars.githubusercontent.com/u/6371650?v=4"},"body":"On Wed, Aug 7, 2024 at 6:22 PM wrote:\n>\n> The docs at https://git-scm.com/docs/git-merge#_how_conflicts_are_presented describe the following snippets in `diff3` and `zdiff3` style as equivalent. They do not seem equivalent to me, so either this is a mistake or the `zdiff3` style is counterintuitive needs a better explanation.\n>\n> diff3 style:\n>\n> ```\n> Here are lines that are either unchanged from the common\n> ancestor, or cleanly resolved because only one side changed,\n> <<<<<<< yours:sample.txt\n> or cleanly resolved because both sides changed the same way.\n> Conflict resolution is hard;\n> let's go shopping.\n> ||||||| base:sample.txt\n> or cleanly resolved because both sides changed identically.\n> Conflict resolution is hard.\n> =======\n> or cleanly resolved because both sides changed the same way.\n> Git makes conflict resolution easy.\n> >>>>>>> theirs:sample.txt\n> And here is another line that is cleanly resolved or unmodified.\n> ```\n>\n> zdiff3 style:\n>\n> ```\n> Here are lines that are either unchanged from the common\n> ancestor, or cleanly resolved because only one side changed,\n> or cleanly resolved because both sides changed the same way.\n> <<<<<<< yours:sample.txt\n> Conflict resolution is hard;\n> let's go shopping.\n> ||||||| base:sample.txt\n> or cleanly resolved because both sides changed identically.\n> Conflict resolution is hard.\n> =======\n> Git makes conflict resolution easy.\n> >>>>>>> theirs:sample.txt\n> And here is another line that is cleanly resolved or unmodified.\n> ```\n>\n> The problem is that, I believe, the \"or cleanly resolved because both sides changed identically.\" sentence should not be part of the **base** in the latter example, since that whole line was moved outside the conflict.\n\nThis line _still changed_, even though there were conflicts around it,\nmeaning that if we didn't have the \"... identically\" line in base, we\nwouldn't see that this line was removed anywhere in the diff. I agree\nwith the other responders that this is awkward, as it means you can't\nreconstruct the original 'base' version from these diff markers; if\nyou tried, you'd get a base version that has \"or cleanly ... the same\nway\" followed by \"or cleanly ... identically\". For manual conflict\nresolution where you generally won't ever keep 'base' or attempt to\nreconstruct it, however, it seems fine to me if you're aware of it\nhappening.\n\n>\n>\n> I'd appreciate knowing which it is.\n>\n> Thanks,\n> Ilya\n>\n"},{"id":"500519","messageId":"9c46732a-eea5-4849-91d8-aa4cc3dc92f1@app.fastmail.com","threadId":"61919","inReplyTo":"CAO_smVg=1gFBudrd70V2_AXSPOUTFz=j7QqBpbkvR7P_KqnBtQ@mail.gmail.com","subject":"Re: Documentation bug (?) when describing `zdiff3` merge format","fromName":"","fromEmail":"punk.lion0906@fastmail.com","sentAt":"2024-08-08T20:25:37Z","receivedAt":"2024-08-08T20:25:59Z","isPatch":false,"sender":{"key":"punk.lion0906@fastmail.com","avatar":null},"body":"> This line _still changed_, even though there were conflicts around it,\n\nAh, thanks for pointing this out, I absolutely missed that. My mind parsed\n\"... identically\" and \"... the same way\" in the same way.\n\nNow the situation makes a bit more sense, I'm getting a sense of *what* `zdiff3` is doing, even though I still don't quite follow the why.\n\nIn any case, in my mind this is now a documentation bug where `zdiff3` is not explained as well as it could be. I don't understand the situation enough to provide the fix, though.\n\nThank you, everyone, for the help!\n Ilya.\n"}]}