checkout: document subtlety around --ours/--theirs
During a 'rebase' (hence 'pull --rebase'), --ours/--theirs may appear to be swapped to those who are not aware of the fact that they are temporarily playing the role of the keeper of the more authoritative history. Add a note to clarify. Helped-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Simon A. Eugster <simon.eugster@eps.ch> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Simon A. Eugster committed
Jul 10, 2015 at 13:07 UTC
f30301657b68561392d910f6196380dd3976549e
1 file changed
+15
Documentation/git-checkout.txt
+15
@@ -116,6 +116,21 @@ entries; instead, unmerged entries are ignored.
116
--theirs::
117
When checking out paths from the index, check out stage #2
118
('ours') or #3 ('theirs') for unmerged paths.
119
++
120
+Note that during `git rebase` and `git pull --rebase`, 'ours' and
121
+'theirs' may appear swapped; `--ours` gives the version from the
122
+branch the changes are rebased onto, while `--theirs` gives the
123
+version from the branch that holds your work that is being rebased.
124
++
125
+This is because `rebase` is used in a workflow that treats the
126
+history at the remote as the shared canonical one, and treats the
127
+work done on the branch you are rebasing as the third-party work to
128
+be integrated, and you are temporarily assuming the role of the
129
+keeper of the canonical history during the rebase. As the keeper of
130
+the canonical history, you need to view the history from the remote
131
+as `ours` (i.e. "our shared canonical history"), while what you did
132
+on your side branch as `theirs` (i.e. "one contributor's work on top
133
+of it").
134
135
-b <new_branch>::
136
Create a new branch named <new_branch> and start it at