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

From: Julia Evans <julia@jvns.ca>
Date: Oct 5, 2026, 19:11 UTC
Message-ID: <e2ef9cf9-a87b-4374-bedd-8f7ab1114961@app.fastmail.com>
In-Reply-To: <xmqqik3gjc5j.fsf@gitster.g>

Show 29 quoted lines

>> 	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?

I agree that would make sense. I have some changes to advice (on other areas) in local branches on my machine already :)

I think of it as sort of "documentation driven development" (write the documentation, and if it feels upsetting what the documentation is saying, then try to change the code so we're happier with the docs!)

I don't have a clear idea for how to improve the way `git status` presents merge conflicts to make it less confusing right now though.

Brainstorming a bit, here's some commentary on this `git status` output:

	On branch main
	Your branch and 'origin/main' have diverged,
	and have 2 and 1 different commits each, respectively.
	  (use "git pull" if you want to integrate the remote branch with yours)

	You have unmerged paths.
	  (fix conflicts and run "git commit")
	  (use "git merge --abort" to abort the merge)

	Unmerged paths:
	  (use "git add <file>..." to mark resolution)
	        both modified:   fruits.py

	no changes added to commit (use "git add" and/or "git commit -a")

1.  `(use "git pull" if you want to integrate the remote branch with yours)`
   is not helpful advice here, it's not even allowed to run `git pull`
   in the middle of a merge conflict.
2. `git add` is sort of not helpful here, all of the unmerged files currently
  have conflict markers, so the next step is definitely not to run `git add`,
  it's to edit one of the unmerged files. But perhaps it's unrealistic to
  be running the equivalent of `git diff --check` in `git status` just to
  help users out.
3. Not sure if "unmerged" is the best term here, maybe "conflicted"?
4. It gives the advice to use `git add` twice which is weird. 
5. One part of the advice refers to the process of fixing conflicts as
  "fix conflicts" but the other part calls it "mark resolution". Should
  probably be consistent there.

But as you can see those comments are all over the place, some of them are just wording changes, some of them would involve adding a bunch of conditional logic to the advice system that might not be realistic, I don't know.

Show 13 quoted lines

> [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).

I will say that I know all of these facts but it has never helped me to remember "ours" and "theirs" :). I'm pretty resistant in general to telling people they need to adopt the "right mindset", IMO it's normal for people to have different points of view.

When explaining Git I heard a lot of "yes I know all that but I just don't like to think about it that way" and it really helped me to learn to respect when folks said that and try to see it from their point of view.