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

[Junio C Hamano <gitster@pobox.com>]

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Julia Evans <julia@jvns.ca>
>
> 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 <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>
> +  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 <<git_status,EXAMPLE: GIT STATUS OUTPUT>> 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 <<ours,"OURS" AND "THEIRS">> 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.