From: Junio C Hamano Date: Mon, 12 Oct 2026 18:16:53 GMT Subject: Re: [PATCH v3 1/6] doc: add new gitmergeconflicts man page Message-ID: In-Reply-To: <7aa0ae7ec3c1d02aa1533c27fa40f4815c03ba6e.1791816795.git.gitgitgadget@gmail.com> "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. > 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 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. > +[NOTE] > +================================ > +Even if Git successfully merges both sides with no conflicts, it's > +possible to end up with code that doesn't work. For example, this can > +happen if one side renames a function, and the other side adds a call to > +the old function. This is called a "semantic merge conflict". > +================================ OK. > +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. The only thing you can say from the sample output below is in the current state "one side has cherry where the other side has banana, and everything else is the same". You cannot say more without seeing diff3 style conflict. > +---- > +FRUITS = [ > + "apple", > +<<<<<<< HEAD > + "cherry", > +======= > + "banana", > +>>>>>>> add-fruit > + "mango", > + "orange", > +] > +---- > + > +The code from one side of the merge conflict is between `<<<<<<<` and > +`=======`, and the code for the other side is between `=======` and > +`>>>>>>>`. See <> below for a full explanation > +of which side is which. > +[[example]] > +EXAMPLE OF RESOLVING A MERGE CONFLICT > +------------------------------------- > + > +If you see this in your code during a merge conflict: > + > +---- > +FRUITS = [ > + "apple", > +<<<<<<< HEAD > + "cherry", > +======= > + "banana", > +>>>>>>> add-fruit > + "mango", > + "orange", > +] > +---- > + > +Then you might edit that part of the code like this, > +which includes the fruits from both sides of the conflict: > + > +---- > +FRUITS = [ > + "apple", > + "banana", > + "cherry", > + "mango", > + "orange", > +] > +---- So, this is one possible resolution. We cannot tell if it is the correct one. > +[[tools]] > +TOOLS FOR HANDLING MERGE CONFLICTS > +---------------------------------- > + > +Here are some ways to get extra context while handling a merge conflict: > ... The incremental changes to this list looks good. > +[[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. 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.