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

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

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

> Like I mentioned before elsewhere it takes a super light approach to
> introducing the 3-way merge. (there is intentionally no mention
> of "since they diverged from the common ancestor" etc)
>
>     WHAT IS A MERGE CONFLICT?
>     -------------------------
>
>     When Git merges two commits together, it looks at the changes that
>     each side has made and combines those changes. For example, if one side
>     edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of
>     `hello.py`, then it can easily combine them.

Some immediate reactions.

 - Is it obvious that the reason why it can "easily combine" them,
   or would it help to be more explicit (i.e., "as there is no
   overlap")?

 - The second "of `hello.py`" forced me to go back and look at the
   first one again to make sure we are talking about the same file.
   I would imagine if the latter were "lines 20-25 of the same file",
   it would have read better at least to me.

>     But if both sides edited overlapping lines of the same file (for example
>     one side edited lines 1-5 and the other edited lines 3-6), Git will
>     not try to guess how to combine those changes. This is called a "merge
>     conflict".

 - "cannot guess" would be more direct than "will not try to guess".

>     When this happens, Git shows you both sides' edits and asks you to pick
>     how to resolve them. It:
>
>     * Stages all of the files which were successfully merged

 - "merged without conflicts" would be more direct than "successfully merged".

>     * For the files with conflicts, it leaves them unstaged, puts both
>       sides' edits in the file, and leaves <<markers, merge conflict markers>>
>       that you need to resolve.

 - "unstaged" sounds as if somebody ran "git rm --cached" on the
   paths, but that is not what you want to tell your readers.

 - "it leaves them unstaged" -> "it remembers them as conflicted",
   perhaps?  This hints that Git has a mechanism to remember the
   conflicted paths even after you removed the conflict markers from
   the file to your readers.