Re: [PATCH v4 1/6] doc: add new gitmergeconflicts man page
- From
Julia Evans <julia@jvns.ca>
- Date
- Oct 26, 2026, 12:35 UTC
- Message-ID
- <2564bcc2-2f78-4ea2-9b6f-c033e95983d8@app.fastmail.com>
- In-Reply-To
- <xmqqtsmc44c1.fsf@gitster.g>
On Fri, Oct 23, 2026, at 3:14 PM, Junio C Hamano wrote:
Show 13 quoted lines
> "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.
Show 26 quoted lines
>> +[[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.
Show 13 quoted lines
>> + "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.
Show 15 quoted lines
>> +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.