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

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

"Julia Evans" <julia@jvns.ca> writes:

>>> +* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>
>>> +  below for details)
>>> +* Or 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.
>>
>> Both are good options and I do not think of a middle way.  Perhaps
>> we do not have to say that these are "the most common" and instead
>> say "You handle a merge conflict by doing either of these two"?
>
> I agree the "the most common" is kind of weaselly and I'd like to be more clear.
> The reason I wrote "typically" is that during a rebase, there's an extra
> "skip" option, so it's not strictly true to say that there are just two options.
> Not sure if there's another option I'm not thinking of other than the
> "skip" in rebase.

I do not think anything like "rebase --skip" in a multi-step
integration is what this document covers particularly well to begin
with.  Taking each conflicted step individually, with "skip", you
are stopping the operation without resolving the conflict.

Perhaps make it clear that in the above you are talking about what
to do with each individual opportunity to give back conflict
resolution to the command?  If you describe these two choices in the
context of multi-step operation, each "we stopped due to conflict
and gave control back to you" opportunity gives you these choices:

 * Give up, pretend this step did not exist, and continue.
 * Resolve the conflict, record it, and continue.

In addition, you have "--abort" to give up the whole thing.
And a single step operation like "git merge" is a degenerated case
of the above.  "and continue" part does not exist.

> I was thinking about that too. Maybe we can briefly mention that git's
> merges are not guaranteed to produce working code even when they
> succeed and point to an example further down the page.
> Added to my list of things to work on.

It's not limited to "GIt's merges" but applies in general.

>>> +[[tools]]
>>> +TOOLS FOR HANDLING MERGE CONFLICTS
>>> +----------------------------------
>>> +
>>> +Here are some ways to get extra context while handling a merge conflict:
>>> +
>>> +* There are many graphical "merge tools" for Git, which will normally
>>> +  show you the different versions of the code side by side.
>>> +  If you have a mergetool configured, `git mergetool` will launch it.
>>> +  See also `merge.tool` in linkgit:git-config[1] for a list of
>>> +  the mergetools Git supports.
>>> +
>>> +* You can set the configuration option `merge.conflictstyle=diff3`.
>>> +  See <<diff3,DIFF3 AND ZDIFF3>> below for more.
>>
>> These are called 'configuration variables' throughout the manual
>> pages.  Be consistent and replace "configuration option" with
>> "configuration variable", perhaps?
>
> They seem to be both used interchangeably already:
>
> ```
> $ grep 'configuration variable' *.adoc | wc -l
>      256
> $ grep 'configuration option' *.adoc | wc -l
>       46
> ```

Do not make it worse.  The latter were mostly added people like you
who responds like the above; aim to be more consistent instead.

>>> +* `git log --merge -p <filename>`  will list all commits which
>>> +  caused the merge conflict for `<filename>`, and the diff
>>> +  of how they changed the file.
>>
>> Maybe worth mentioning that `--left-right` often helps when you are
>> not super familiar with the histories being merged.
>
> I don't understand what this does or what it would be useful for so
> it's not possible for me to explain it  :). From my perspective
> "ours" and "theirs" are already confusing enough and introducing
> "left" and "right" seems like a lot. Is "left" the same as "ours"?

If you do not understand what it does, perhaps try it out?

"git log -p --merge" is to break down the ours/theirs into
individual steps when changes on these sides were brought in in
multiple steps.  It shows individual changes per commit, but if you
are not super familiar with these histories being merged, it is not
obvious which commit came from which side.  And --left-right option
is a way to help you tell which one came from which.

>>> +* Use `git diff AUTO_MERGE` to show what changes you've made so far to
>>> +  resolve the conflicts.
>>
>> Does a "See below" here help readers who haven't learned what
>> AUTO_MERGE is?  If you can describe what AUTO_MERGE records (in
>> other words, what you are comparing your progress against) in a
>> sentence of two here, that would alleviate the need to assure them
>> that we have more in-depth coverage on this topic elsewhere.
>
> I think this is okay the way it is.

Is it because, unlike --left-right, you understand what it does?
Not everybody shares what you know, you know ;-)

 * AUTO_MERGE records the initial merge result with conflict
   markers.  `git diff AUTO_MERGE` can be used to show how much
   progress you made to resolve these conflicts.

perhaps.

> Maybe we could add a note like this somewhere?
>
>    NOTE: zdiff3 was an experimental alternative to diff3 that makes
>    the merge conflict shorter by introducing more ambiguity.
>    It's still there for backwards compatibility but we don't recommend it.

Drop "experimental" and I am 100% behind that statement ;-).

>> By the way, is it just me who finds those "Here's", "there's"
>> contractions disturbing in an official manual?  I've seen many of
>> them while reviewing this to be annoyed enough and had to blurt it
>> out X-<.
>
> I find "here is" and "there is" to be distracting and overly formal,
> different people are different I guess :)

I would prefer to be consistent in a single documentation set, though.

>> The text comes from ffb1a4bed5 (Documentation: Describe merge
>> operation a bit better., 2005-11-28) that had "When there are
>> conflicts, these things happen. 1. HEAD does not move, 2. Cleanly
>> merged paths are updated in the index 3. Conflicts are recorded in
>> higher stage index entries and working tree files show conflict
>> markers, 4. No other changes are done" well before the mysterious
>> reference to 2. and 3.
>>
>> When ebef7e5049 (Documentation: simplify How Merge Works,
>> 2010-01-23) tried to simplify the description, the list of "these
>> things happen" were removed/rewritten, and yet instructions on how
>> to reset are left behind, still referring to 2. and 3.
>>
>> We probably want a separate patch for Documentation/git-merge.adoc
>> to rectify this 16 year old mistake.
>
> Thanks for investigating!

Heh, you already did the separate patch, which is [2/6], which I am
happy with.