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

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

"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.

> +[[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.

> +    "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.

> +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 ...

or somethig like that.

Other than that, I did not see anything questionable in the 6
patches.