From: Junio C Hamano Date: Fri, 02 Oct 2026 17:50:12 GMT Subject: Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide Message-ID: In-Reply-To: <4e579181-e93a-4746-8c2d-b127cb0e053d@app.fastmail.com> "Julia Evans" 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 <> > 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.