Re: [PATCH v4 1/6] doc: add new gitmergeconflicts man page

["Julia Evans" <julia@jvns.ca>]

On Fri, Oct 23, 2026, at 3:14 PM, Junio C Hamano wrote:
> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> Things to potentially improve in future docs revisions:
>>
>> - The explanation of zdiff3 is unsatisfying. It would be good if we
>>   could have a clear example of a case where zdiff3 is helpful and a
>>   case where it's harmful, and if we could give a better sense for
>>   the reasons why users are actually choosing zdiff3 over diff3
>>   (or the reverse) in real life.
>
> Is this a stale comment?  I think you reduced this to just a side
> note that says `shoter but ambiguous`, which is probably good
> enough.

It's not, but I'll delete it anyway because I don't think it's adding much.

>> +[[diff3]]
>> +DIFF3
>> +-----
>> +
>> +By default, Git doesn't include the original code when formatting
>> +a merge conflict. To include the original code, you can set the
>> +configuration option `merge.conflictstyle` to `diff3`.
>> +This extra context can make it much easier to understand what's
>> +happening in a merge conflict.
>> +
>> +Here's an example of what a merge conflict would look like when using
>> +`diff3`. There's an extra section (between `|||||||` and `=======`)
>> +with the original code.
>> +
>> +----
>> +FRUITS = [
>> +    "apple",
>> +<<<<<<< HEAD
>> +    "cherry",
>> +    "mango",
>> +||||||| 1c22e48
>> +	"banana",
>> +	"cherry",
>
> These two should be indented with spaces the same way as all the
> other lines in this list.

Will fix, thanks.

>> +    "mangoooo",
>> +=======
>> +    "banana",
>> +    "mango",
>> +>>>>>>> add-fruit
>> +    "orange",
>> +]
>> +----
>> +
>> +With this view, you can see that both sides fixed a spelling
>> +mistake in "mango", and each removed one fruit to the list.
>
> ", and each removed one from the list", I think.

Thanks, will fix.

>> +This makes it more clear how to resolve the merge conflict: since one
>> +side removed `banana` and one side removed `cherry`, it would probably
>> +make sense to remove both from the list, like this:
>
> The reason why removal becomes the correct resolution is not just
> one side removed, but the fact that the other side did not touch
> what was removed by one side.  The "indifference by the other" is
> what makes one's removal the preferred action by the semantics of
> 3-way merge.
>
> So, let's rewrite the reason a bit more tightly.
>
>     since one side removed `banana` while the other side did not
>     touch, and the same happend to `cherry`, it makes sense to
>     remove both from the list ...

I tried to edit this (like below) but only ended up removing "probably".
But "probably" was there for a reason, since this is a made up example
and in the real world you would really need to apply some judgement
to know what the right thing to do is. I left it as is.

-side removed `banana` and one side removed `cherry`, it would probably
-make sense to remove both from the list, like this:
+side removed `banana` and one side removed `cherry`, it makes sense
+to remove both from the list, like this:

> or somethig like that.
>
> Other than that, I did not see anything questionable in the 6
> patches.