Merge branch 'se/doc-checkout-ours-theirs' into maint

A "rebase" replays changes of the local branch on top of something
else, as such they are placed in stage #3 and referred to as
"theirs", while the changes in the new base, typically a foreign
work, are placed in stage #2 and referred to as "ours".  Clarify
the "checkout --ours/--theirs".

* se/doc-checkout-ours-theirs:
  checkout: document subtlety around --ours/--theirs

1 files changed, 15 insertions, 0 deletions

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 63b739c550..e269fb1108 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -120,6 +120,21 @@ entries; instead, unmerged entries are ignored.
 --theirs::
 	When checking out paths from the index, check out stage #2
 	('ours') or #3 ('theirs') for unmerged paths.
++
+Note that during `git rebase` and `git pull --rebase`, 'ours' and
+'theirs' may appear swapped; `--ours` gives the version from the
+branch the changes are rebased onto, while `--theirs` gives the
+version from the branch that holds your work that is being rebased.
++
+This is because `rebase` is used in a workflow that treats the
+history at the remote as the shared canonical one, and treats the
+work done on the branch you are rebasing as the third-party work to
+be integrated, and you are temporarily assuming the role of the
+keeper of the canonical history during the rebase.  As the keeper of
+the canonical history, you need to view the history from the remote
+as `ours` (i.e. "our shared canonical history"), while what you did
+on your side branch as `theirs` (i.e. "one contributor's work on top
+of it").
 
 -b <new_branch>::
 	Create a new branch named <new_branch> and start it at