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

["Julia Evans" <julia@jvns.ca>]

>> [snip]
>>> +[[ours]]
>>> +"OURS" AND "THEIRS"
>>> +-------------------
>>> +
>>> +Git refers to the first part of a merge conflict (between `<<<<<<<`
>>> +and `=======`) as "ours" and the second part (between `=======` and
>>> +`>>>>>>>`) as "theirs".
>>> +
>>> +Normally, "ours" is the commit that was checked out before you started
>>> +the merge, and "theirs" is the other commit.
>>> +
>>> +But when the merge conflict was caused by a `git rebase`, it's the
>>> +opposite: "theirs" is the commit that was checked out before you started
>>> +the merge. This is because under the hood, `git rebase main` checks out
>>> +the `main` commit first before doing the merge operation.
>>
>> Hmm. This part is a bit confusing to me. "ours" is always the commit
>> that's currently checked out, and "theirs" is always the one that is
>> getting merged into the checked-out commit.
>>
>> How about a variant of the following instead?
>>
>>   In a conflict, the side between `<<<<<<<` and `=======` is "ours"
>>   and the side between `=======` and `>>>>>>>` is "theirs". "Ours" is
>>   always the side that `HEAD` points to while the merge happens; "theirs"
>>   is the commit being merged into it.
>>
>>   For `git merge <other>`, `HEAD` is your current branch, so "ours" is
>>   your branch and "theirs" is `<other>`.
>>
>>   For `git rebase <upstream>`, `HEAD` is first moved to `<upstream>` and
>>   your commits are then replayed on top one at a time. So "ours" is the
>>   already-rebased history starting at `<upstream>`, and "theirs" is the
>>   commit from your original branch that is currently being replayed.
>
> Thanks, your suggestion gives me some other ways to think about this.
>
> I think I'll try to write something shorter that is unambiguous, 
> instead of trying
> to use more words to make it feel more intuitive. I don't think I 
> actually know
> anyone who feels it's easy to understand the way merge conflicts are
> presented, and more explanation may not help.
>
> It might be more useful here to encourage (again) folks to use one of the many
> amazing tools available (in the "tools" section) to get more context.
>
>>> +These terms in Git all mean the same thing when dealing with a merge
>>> +conflict:
>>> +
>>> +* "common ancestor", "base", and "stage 1"
>>> +* "ours", "us", "stage 2", and `HEAD`
>>> +* "theirs", "them", and "stage 3"
>>
>> I wouldn't say that "stage N" is equivalent to the respective other
>> terms. These stages rather refer to the different versions of a specific
>> file as recorded in the index, they do not indicate a specific commit.
>> In contrast to that, all the other terms may also indicate a specific
>> version of a file, but may also refer to the commits.
>
> Thanks, will try to figure out how to make it more accurate.
> We could also refer to gitdatamodel if folks want to learn what the
> term "stage" means too.

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.