From f30301657b68561392d910f6196380dd3976549e Mon Sep 17 00:00:00 2001 From: "Simon A. Eugster" Date: Fri, 10 Jul 2015 13:07:11 -0700 Subject: 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 Signed-off-by: Simon A. Eugster Signed-off-by: Junio C Hamano --- Documentation/git-checkout.txt | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'Documentation') diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 33ad2adf5c..d74d605574 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -116,6 +116,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 :: Create a new branch named and start it at -- cgit v1.2.3