What is the precise meaning of "ours" and "theirs" in git?

Question

This might sound like too basic of a question, but I have searched for answers and I am more confused now than before.

What does "ours" and "theirs" mean in git when merging my branch into my other branch? Both branches are "ours".

In a merge conflict is "ours" always the upper of the two versions displayed?

Does "ours" always refer to the branch that HEAD was pointing to when the merge began? If so then why not use a clear possessive reference like "current branch's" instead of using a possessive pronoun like "ours" that is referentially ambiguous (since both branches are technically ours)?

Or just use the branch name (instead of saying "ours" just say "local master's" or such)?

The most confusing part to me is if I specify in a specific branch's .gitattributes file. Lets say in test branch I have the following .gitattributes file:

config.xml merge=ours 

Now I checkout and point HEAD to master then merge in test. Since master is ours, and test's .gitattributes is not checked out, will it even have an effect? If it does have an effect, since master is now "ours", then what will happen?

Answer 1

I suspect you're confused here because it's fundamentally confusing. To make things worse, the whole ours/theirs stuff switches roles (becomes backwards) when you are doing a rebase.

Ultimately, during a git merge, the "ours" branch refers to the branch you're merging into:

git checkout merge-into-ours 

and the "theirs" branch refers to the (single) branch you're merging:

git merge from-theirs 

and here "ours" and "theirs" makes some sense, as even though "theirs" is probably yours anyway, "theirs" is not the one you were on when you ran git merge.

While using the actual branch name might be pretty cool, it falls apart in more complex cases. For instance, instead of the above, you might do:

git checkout ours git merge 1234567 

where you're merging by raw commit-ID. Worse, you can even do this:

git checkout 7777777    # detach HEAD git merge 1234567       # do a test merge 

in which case there are no branch names involved!

I think it's little help here, but in fact, in gitrevisions syntax, you can refer to an individual path in the index by number, during a conflicted merge

git show :1:README git show :2:README git show :3:README 

Stage #1 is the common ancestor of the files, stage #2 is the target-branch version, and stage #3 is the version you are merging from.

---

The reason the "ours" and "theirs" notions get swapped around during rebase is that rebase works by doing a series of cherry-picks, into an anonymous branch (detached HEAD mode). The target branch is the anonymous branch, and the merge-from branch is your original (pre-rebase) branch: so "--ours" means the anonymous one rebase is building while "--theirs" means "our branch being rebased".

---

As for the gitattributes entry: it could have an effect: "ours" really means "use stage #2" internally. But as you note, it's not actually in place at the time, so it should not have an effect here ... well, not unless you copy it into the work tree before you start.

Also, by the way, this applies to all uses of ours and theirs, but some are on a whole file level (-s ours for a merge strategy; git checkout --ours during a merge conflict) and some are on a piece-by-piece basis (-X ours or -X theirs during a -s recursive merge). Which probably does not help with any of the confusion.

I've never come up with a better name for these, though. And: see VonC's answer to another question, where git mergetool introduces yet more names for these, calling them "local" and "remote"!