Re: [PATCH v2 2/6] doc: git-merge: link to new merge conflicts guide

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

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

> From: Julia Evans <julia@jvns.ca>
>
> All of the info about merge conflicts has been moved to the new guide

In the body text end the sentence with a full stop.

And I just went though the "new guide" with fine toothed comb, I am
very much qualified to judge if the above claim is correct.  Let's
see.

> @@ -231,127 +232,6 @@ git merge v1.2.3^0
>  git merge --ff-only v1.2.3
>  ----
>  
> -HOW CONFLICTS ARE PRESENTED
> ----------------------------
> -
> -During a merge, the working tree files are updated to reflect the result
> -of the merge.  Among the changes made to the common ancestor's version,
> -non-overlapping ones (that is, you changed an area of the file while the
> -other side left that area intact, or vice versa) are incorporated in the
> -final result verbatim.  When both sides made changes to the same area,
> -however, Git cannot randomly pick one side over the other, and asks you to
> -resolve it by leaving what both sides did to that area.

OK.  We said working tree files are updated.  We made a weak
reference to "common ancestor" but with my suggested updates I think
we sufficiently cover this.  "Git cannot ... and asks you ..." had a
nice nuance that we may not have captured in the new document (we
stop at "will not try to guess" and say "asks you to pick" in a
seaprate paragraph, which feels a bit detached than the original
here [***]).

> -By default, Git uses the same style as the one used by the "merge" program
> -from the RCS suite to present such a conflicted hunk, like this:
> -
> -------------
> -Here are lines that are either unchanged from the common
> -ancestor, or cleanly resolved because only one side changed,
> -or cleanly resolved because both sides changed the same way.
> -<<<<<<< yours:sample.txt
> -Conflict resolution is hard;
> -let's go shopping.
> -=======
> -Git makes conflict resolution easy.
> ->>>>>>> theirs:sample.txt
> -And here is another line that is cleanly resolved or unmodified.
> -------------
> -
> -The area where a pair of conflicting changes happened is marked with markers
> -+<<<<<<<+, `=======`, and +>>>>>>>+.  The part before the `=======`
> -is typically your side, and the part afterwards is typically their side.
> -
> -The default format does not show what the original said in the conflicting
> -area.  You cannot tell how many lines are deleted and replaced with
> -Barbie's remark on your side.  The only thing you can tell is that your
> -side wants to say it is hard and you'd prefer to go shopping, while the
> -other side wants to claim it is easy.

We covered all of the above, except for the reference to RCS which
we explicitly wanted to lose.  Good.

> -An alternative style can be used by setting the `merge.conflictStyle`
> ...
> -In addition to the +<<<<<<<+, `=======`, and +>>>>>>>+ markers, it uses
> -another +|||||||+ marker that is followed by the original text.

This is what we were missing in the new guide, which I tried to
rectify without looking at this exact text.  In any shape it should
be preserved somehow [***].

> - You can
> -tell that the original just stated a fact, and your side simply gave in to
> -that statement and gave up, while the other side tried to have a more
> -positive attitude.  You can sometimes come up with a better resolution by
> -viewing the original.

We covered this with "fruits from both sides" example, and I think
the explanation there is shorter and simpler to understand.

> -HOW TO RESOLVE CONFLICTS
> -------------------------
> -
> -After seeing a conflict, you can do two things:
> -
> - * Decide not to merge.  The only clean-ups you need are to reset
> -   the index file to the `HEAD` commit to reverse 2. and to clean
> -   up working tree changes made by 2. and 3.; `git merge --abort`
> -   can be used for this.
> -
> - * Resolve the conflicts.  Git will mark the conflicts in
> -   the working tree.  Edit the files into shape and
> -   `git add` them to the index.  Use `git commit` or
> -   `git merge --continue` to seal the deal. The latter command
> -   checks whether there is a (interrupted) merge in progress
> -   before calling `git commit`.

The new text tried to have a wiggle room with "most common", but
nothing is lost from the above if we tweak it with my suggested
"there are only two" [***].

> -You can work through the conflict with a number of tools:
> -
> - * Use a mergetool.  `git mergetool` to launch a graphical
> -   mergetool which will work through the merge with you.
> -
> - * Look at the diffs.  `git diff` will show a three-way diff,
> -   highlighting changes from both the `HEAD` and `MERGE_HEAD`
> -   versions. `git diff AUTO_MERGE` will show what changes you've
> -   made so far to resolve textual conflicts.
> -
> - * Look at the diffs from each branch. `git log --merge -p <path>`
> -   will show diffs first for the `HEAD` version and then the
> -   `MERGE_HEAD` version.
> -
> - * Look at the originals.  `git show :1:filename` shows the
> -   common ancestor, `git show :2:filename` shows the `HEAD`
> -   version, and `git show :3:filename` shows the `MERGE_HEAD`
> -   version.

We covered this in "Tools for handling" section.  This version
groups AUTO_MERGE together with other tools, which may have its
advantages and disadvantages.  The latter two bullet points in the
above list is about static view, so is three-way O A B diff.  Use of
mergetool and 'diff AUTO_MERGE" are more dynamic "how far have you
come" view.  So separating the "git diff" that shows three-way
comparison and "git diff AUTO_MERGE" in the new document sounds like
an improvement (even though 'mergetool' blurs the boundary between
"how the conflict looked like" and "what your eventual conflict you
are working toward may look like", though [***]).

Overall, I fully agree with these removals.  We may want to take a
few points (marked with [***]) we learned during this review back to
the new document from here, though.

Thanks.