From: Julia Evans Date: Wed, 14 Oct 2026 19:24:13 GMT Subject: Re: [PATCH v3 1/6] doc: add new gitmergeconflicts man page Message-ID: <89df0444-1447-4267-9e28-bc4dc70b0478@app.fastmail.com> In-Reply-To: On Mon, Oct 12, 2026, at 2:16 PM, Junio C Hamano wrote: > "Julia Evans via GitGitGadget" writes: > >> From: Julia Evans >> >> Introduce a new page, `gitmergeconflicts`, that explains the process of >> handling a merge conflict in a way that addresses the following issues, >> which came from feedback from Git users on the current explanation of >> merge conflicts in the `git merge` man page: >> >> - The process for resolving a merge conflict is only explained in the >> ... >> - It sometimes uses the term "area" and sometimes uses the term "hunk" > > It looks a bit annoying that these sentences in the enumeration all > lack their full stops. Sure, will fix. >> Only discuss merge, rebase, cherry-pick, and revert for now even though >> there are other ways that merge conflicts can happen because it's >> awkward to talk about `am`, `apply`, and `checkout -m`. > > I do not know "because it's awkward" is a good justification, > though. "awkward" why? It's because `apply` and `am` can also apply patches, and that's a whole separate topic than explaining the 3-way merge. I think explaining the difference between applying a patch and doing a 3-way merge could be interesting to do in the future but this is already quite a big patch series. > It might be tempting to omit some commands that are less common for > new users, but we are touching the main part of the technical manual > that are meant ot be used by everybody, so that is not a good reason > to choose covering some but not others. > > I however agree that it is better to avoid appearing to be complete > and leaving others (including future ones we add) with "any other > command that does a merge" as this round of document gives. > >> diff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc >> ... >> +There are 3 ways to handle a merge conflict: >> + >> +* Resolve the conflict. (see <> >> + below for details) >> +* Stop the operation and return your branch to its original state >> + with the appropriate `--abort` command, for example `git merge --abort` >> + or `git rebase --abort`. See <> below >> + for how to find the command to run. >> +* Or (if you're in a multi-step rebase or cherry-pick) skip the problematic >> + commit with the appropriate `--skip` command > > The third entry is a nice addition. multi-step anything are the > same, including revert, right? I'd recommend updating it to > something like "if you are in a multi-step operation like `rebase`" > in the same spirit as the "or any other command" change you made at > the beginning of this file. Done. >> +When there's a merge conflict, Git will update the conflicted file >> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`. >> +For example, here's a merge conflict where both sides edited a list of >> +fruits in different ways -- one side added "cherry" and the other side >> +added "banana": > > You added "-- one side added ..." at the end, which I think sends a > wrong message. With rcs-merge style conflict, you cannot simply > tell, because it is ambiguous. The original may have had both > banana and cherry, in which case the sample output shows the result > of one side removing banana and the other side removing cherry. Make sense, will replace "added" with "has". >> +[[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. >> + >> +With this view, you can see that both sides fixed a spelling >> +mistake in "mango", and each added one fruit to the list. >> + >> +---- >> +FRUITS = [ >> + "apple", >> +<<<<<<< HEAD >> + "cherry", >> + "mango", >> +||||||| 1c22e48 >> + "mangoooo", >> +======= >> + "banana", >> + "mango", >> +>>>>>>> add-fruit >> + "orange", >> +] >> +---- > > THis is a great example. > > But an even better example would be to give this: > > FRUITS = [ > "apple", > <<<<<<< HEAD > "cherry", > "mango", > ||||||| 1c22e48 > "banana", > "cherry", > "mangoooo", > ======= > "banana", > "mango", > >>>>>>> add-fruit > "orange", > ] > > and tell the readers that that the correct resolution is to have > "apply, mango, orange", as each of cherry and banana was removed by > one side while the other side did not touch it. Having cherry and > banana in the result is a tempting but not always correct conclusion > unexperienced people would draw from the rcs-merge style output that > is ambiguous, and here is a great place to teach it in this flow. Thanks, this is a much better example, for the reasons you say. Will use it. I always appreciate thinking carefully about which examples to give, it's so important. > Especially because it would make it stand out that the point of > diff3's verboseness compared to the rcs-merge output is to > disambiguate two cases. If you start from ABCmO and one side has > ABMO while the other side has ACMO, the right resolution would be > AMO (the above case I added), but if your starting point were AmO > and the two sides ends with ABMO and ACMO respectively, the right > resolution would be ABCMO. The rcs-merge output does not tell you > which is more likely to be correct, diff3 disambiguates these two > cases by being more verbose. > > And telling that value of diff3 is about disambiguating is valuable > when ... > >> +[NOTE] >> +================================ >> +`zdiff3` is an alternative to `diff3` that makes the merge conflict >> +shorter by making it more ambiguous. >> +================================ > > ... this note tells the readers that zdiff3 is a ambigous variant of > diff3, hinting its flaw.