Re: Documentation bug (?) when describing `zdiff3` merge format

From: Kyle Lippincott <spectral@google.com>
Date: Aug 8, 2024, 17:22 UTC
Message-ID: <CAO_smVg=1gFBudrd70V2_AXSPOUTFz=j7QqBpbkvR7P_KqnBtQ@mail.gmail.com>
In-Reply-To: <ab0fcc2e-936f-4d76-8059-fb2bc8a4f661@app.fastmail.com>

On Wed, Aug 7, 2024 at 6:22 PM <punk.lion0906@fastmail.com> wrote:

Show 41 quoted lines

>
> 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.
>
> diff3 style:
>
> ```
> Here are lines that are either unchanged from the common
> ancestor, or cleanly resolved because only one side changed,
> <<<<<<< yours:sample.txt
> or cleanly resolved because both sides changed the same way.
> Conflict resolution is hard;
> let's go shopping.
> ||||||| base:sample.txt
> or cleanly resolved because both sides changed identically.
> Conflict resolution is hard.
> =======
> or cleanly resolved because both sides changed the same way.
> Git makes conflict resolution easy.
> >>>>>>> theirs:sample.txt
> And here is another line that is cleanly resolved or unmodified.
> ```
>
> zdiff3 style:
>
> ```
> Here are lines that are either unchanged from the common
> ancestor, or cleanly resolved because only one side changed,
> or cleanly resolved because both sides changed the same way.
> <<<<<<< yours:sample.txt
> Conflict resolution is hard;
> let's go shopping.
> ||||||| base:sample.txt
> or cleanly resolved because both sides changed identically.
> Conflict resolution is hard.
> =======
> Git makes conflict resolution easy.
> >>>>>>> theirs:sample.txt
> And here is another line that is cleanly resolved or unmodified.
> ```
>
> 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.

This line _still changed_, even though there were conflicts around it, meaning that if we didn't have the "... identically" line in base, we wouldn't see that this line was removed anywhere in the diff. I agree with the other responders that this is awkward, as it means you can't reconstruct the original 'base' version from these diff markers; if you tried, you'd get a base version that has "or cleanly ... the same way" followed by "or cleanly ... identically". For manual conflict resolution where you generally won't ever keep 'base' or attempt to reconstruct it, however, it seems fine to me if you're aware of it happening.

Show 7 quoted lines

>
>
> I'd appreciate knowing which it is.
>
>         Thanks,
>              Ilya
>