patchDocumentation clarification on git-checkout regarding ours/theirs

>  Documentation/git-checkout.txt | 16 +++++++++++++++-
>  1 file changed, 15 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
> index d263a56..d69306f 100644
> --- a/Documentation/git-checkout.txt
> +++ b/Documentation/git-checkout.txt
> @@ -115,7 +115,21 @@ entries; instead, unmerged entries are ignored.
>  --ours::
>  --theirs::
>  	When checking out paths from the index, check out stage #2
> -	('ours') or #3 ('theirs') for unmerged paths.
> +	('ours', HEAD) or #3 ('theirs', MERGE_HEAD) for unmerged paths.

> +	See linkgit:git-merge[1] for details about stages #2 and #3.
> ++
> +Note that during `git rebase` and `git pull --rebase`, 'theirs' checks out
> +the local version, and 'ours' the remote version or the history that is rebased
> +against.
> ++
> +The reason ours/theirs appear to be swapped during a rebase is that we
> +define the remote history as the canonical history, on top of which our
> +private commits are applied on, as opposed to normal merging where the
> +local history is the canonical one.

> +During merging, we assume the role of the canonical history’s keeper,
> +which, in case of a rebase, is the remote history, and our private commits
> +look to the keeper as “their” commits which need to be integrated on top
> +of “our” work.
>  
>  -b <new_branch>::
>  	Create a new branch named <new_branch> and start it at

> "Simon A. Eugster" <simon.eu@gmail.com> writes:
>
>> From: "Simon A. Eugster" <simon.eugster@eps.ch>
>>
>> Signed-off-by: Simon A. Eugster <simon.eugster@eps.ch>
>> ---
>
> For those who are looking from the sideline, this is a reroll from a
> month-old thread $gmane/271680.
>
>>   Documentation/git-checkout.txt | 16 +++++++++++++++-
>>   1 file changed, 15 insertions(+), 1 deletion(-)
>>
>> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
>> index d263a56..d69306f 100644
>> --- a/Documentation/git-checkout.txt
>> +++ b/Documentation/git-checkout.txt
>> @@ -115,7 +115,21 @@ entries; instead, unmerged entries are ignored.
>>   --ours::
>>   --theirs::
>>   	When checking out paths from the index, check out stage #2
>> -	('ours') or #3 ('theirs') for unmerged paths.
>> +	('ours', HEAD) or #3 ('theirs', MERGE_HEAD) for unmerged paths.
>
> I'd drop the change on this line.  Your conflict may or may not be
> from these two places when you are using "checkout".  Even if it
> came from "git merge", when you are doing "merge", the roles 'ours'
> and 'theirs' are very clear and mentioning HEAD/MERGE_HEAD does not
> add more clarity than it clutters the description, I would think.

>
>> +	See linkgit:git-merge[1] for details about stages #2 and #3.
>> ++
>> +Note that during `git rebase` and `git pull --rebase`, 'theirs' checks out
>> +the local version, and 'ours' the remote version or the history that is rebased
>> +against.
>> ++
>> +The reason ours/theirs appear to be swapped during a rebase is that we
>> +define the remote history as the canonical history, on top of which our
>> +private commits are applied on, as opposed to normal merging where the
>> +local history is the canonical one.
>
> It appears to me that this patch text predates my comment in
> $gmane/271720 and your response to it?

>> +During merging, we assume the role of the canonical history’s keeper,
>> +which, in case of a rebase, is the remote history, and our private commits
>> +look to the keeper as “their” commits which need to be integrated on top
>> +of “our” work.
>>
>>   -b <new_branch>::
>>   	Create a new branch named <new_branch> and start it at
>
> Thanks for reminding of the discussion that did not conclude with a
> patch.
>
> How about this?
>
> -- >8 --
> From: "Simon A. Eugster" <simon.eugster@eps.ch>
> 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 <gitster@pobox.com>
> Signed-off-by: Simon A. Eugster <simon.eugster@eps.ch>
> ---
>   Documentation/git-checkout.txt | 15 +++++++++++++++
>   1 file changed, 15 insertions(+)
>
> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
> index d263a565..8c921e7 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 treat 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

>> +...  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
>
> I think there is an “s” missing in “… and treat the work done on
> the branch …”, but not quite sure.