From: Julia Evans Date: Mon, 26 Oct 2026 12:35:47 GMT Subject: Re: [PATCH v4 1/6] doc: add new gitmergeconflicts man page Message-ID: <2564bcc2-2f78-4ea2-9b6f-c033e95983d8@app.fastmail.com> In-Reply-To: On Fri, Oct 23, 2026, at 3:14 PM, Junio C Hamano wrote: > "Julia Evans via GitGitGadget" 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.