Re: [PATCH 1/7] [doc] Add new gitmergeconflicts man page

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

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

> Marie and I worked on the OURS AND THEIRS section today and I think it's clearer
> now but also longer (instead of shorter which was my dream). We added an attempt
> at humor at the end to hopefully help things a bit.
>
> 	"OURS" AND "THEIRS"
> 	-------------------
>
> 	Sometimes during a merge conflict, Git will use the terms "ours" and
> 	"theirs" (or "us" and "them"). For example, `git status` might say that
> 	a file was `deleted by us`.
>
> 	"Ours" and "theirs" are both commits: "ours" is the current
> 	`HEAD` commit, and "theirs" is the other side being merged.
>
> 	The first part of a merge conflict (between `<<<<<<<` and `=======`) is
> 	from the "ours" side, and the second part (between `=======` and
> 	`>>>>>>>`) is from the "theirs" side.
>
> 	----
> 	FRUITS = [
> 	    "apple",
> 	<<<<<<< HEAD
> 	    "cherry",                      <- ours
> 	=======
> 	    "banana",                      <- theirs
> 	>>>>>>> add-fruit
> 	    "mango",
> 	    "orange",
> 	]
> 	----
>
> 	During a rebase, it can seem "upside down" because the "ours" commit is
> 	from the branch you're rebasing on (for instance `main` in `git rebase
> 	main`).
>
> 	These terms in Git all mean the same thing when dealing with a merge
> 	conflict:
>
> 	* "common ancestor" and "base". The files from this commit are "in stage 1".
> 	* "ours", "us", and `HEAD`. The files from this commit are "in stage 2".
> 	* "theirs", "them". The files from this commit are "in stage 3".
>
> 	If you're confused about what something like "deleted by us" means, it's
> 	often easiest to use some of the tools from
> 	<<tools,TOOLS FOR HANDLING MERGE CONFLICTS>> above to get more context.
> 	Finding the commit that deleted the file and seeing why is usually more
> 	helpful than trying to abstractly reason through what "us" means.

May I ask what is in scope for this effort?

We previously discussed updating the conflict markers (the 'HEAD'
and 'add-fruit' labels in the example above).  Doing so would
require code changes, which goes beyond mere documentation updates.
But if a minor code change like that makes the documentation much
easier to understand, I think we should consider doing so.

Along the same line, if git status stopped saying "deleted by us"
and instead used a different phrase, would that help reduce the
"upside down" confusion [*]?  Is it acceptable to bend the code
a little if it helps the documentation?


[Footnote]

 * I suspect that the "upside down" feeling is not really about the
   terms "ours" and "theirs" themselves.  Rather, it comes from how
   one conceptualizes what 'rebase' does compared to 'merge'.
   During a rebase, we temporarily pretend that we are working on
   the upstream branch and replay our local changes on top of it.
   Once the user adopts this mindset, displaying the upstream state
   first (the point from which we start building the consolidated
   history) followed by the local state (what was done differently
   by the local side) becomes consistent with how 'merge' displays
   conflicts (where we start from our local state and merge the
   incoming changes).