From: Junio C Hamano <gitster@pobox.com>
Date: Mon, 3 Aug 2015 18:01:25 +0000 (-0700)
Subject: Merge branch 'se/doc-checkout-ours-theirs'
X-Git-Tag: v2.6.0-rc0~94
X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/c0b901eaf71ca700eb6c8711af0c848df2d011c5?hp=-c

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

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

c0b901eaf71ca700eb6c8711af0c848df2d011c5
diff --combined Documentation/git-checkout.txt
index 63b739c550,d74d605574..e269fb1108
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@@ -3,7 -3,7 +3,7 @@@ git-checkout(1
  
  NAME
  ----
 -git-checkout - Checkout a branch or paths to the working tree
 +git-checkout - Switch branches or restore working tree files
  
  SYNOPSIS
  --------
@@@ -89,10 -89,6 +89,10 @@@ Omitting <branch> detaches HEAD at the 
  	(i.e.  commit, tag or tree) to update the index for the given
  	paths before updating the working tree.
  +
 +'git checkout' with <paths> or `--patch` is used to restore modified or
 +deleted paths to their original contents from the index or replace paths
 +with the contents from a named <tree-ish> (most often a commit-ish).
 ++
  The index may contain unmerged entries because of a previous failed merge.
  By default, if you try to check out such an entry from the index, the
  checkout operation will fail and nothing will be checked out.
@@@ -120,6 -116,21 +120,21 @@@ entries; instead, unmerged entries are 
  --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
@@@ -148,7 -159,7 +163,7 @@@ explicitly give a name with '-b' in suc
  
  --no-track::
  	Do not set up "upstream" configuration, even if the
 -	branch.autosetupmerge configuration variable is true.
 +	branch.autoSetupMerge configuration variable is true.
  
  -l::
  	Create the new branch's reflog; see linkgit:git-branch[1] for
@@@ -214,7 -225,7 +229,7 @@@ the conflicted merge in the specified p
  --conflict=<style>::
  	The same as --merge option above, but changes the way the
  	conflicting hunks are presented, overriding the
 -	merge.conflictstyle configuration variable.  Possible values are
 +	merge.conflictStyle configuration variable.  Possible values are
  	"merge" (default) and "diff3" (in addition to what is shown by
  	"merge" style, shows the original contents).
  
@@@ -229,12 -240,6 +244,12 @@@ This means that you can use `git checko
  edits from your current working tree. See the ``Interactive Mode''
  section of linkgit:git-add[1] to learn how to operate the `--patch` mode.
  
 +--ignore-other-worktrees::
 +	`git checkout` refuses when the wanted ref is already checked
 +	out by another worktree. This option makes it check the ref
 +	out anyway. In other words, the ref can be held by more than one
 +	worktree.
 +
  <branch>::
  	Branch to checkout; if it refers to a branch (i.e., a name that,
  	when prepended with "refs/heads/", is a valid ref), then that