[PATCH] Documentation clarification on git-checkout regarding ours/theirs

[PATCH] Documentation clarification on git-checkout regarding ours/theirs

[Simon A. Eugster]

From: "Simon A. Eugster" <simon.eugster@eps.ch>

Signed-off-by: Simon A. Eugster <simon.eugster@eps.ch>
---
 Documentation/git-checkout.txt | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index d263a56..5c3ef86 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -115,7 +115,11 @@ 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.
++
+After a `git pull --rebase`, for example, 'ours' points to the remote
+version and 'theirs' points to the local version. See linkgit:git-merge[1]
+for details about stages #2 and #3.
 
 -b <new_branch>::
 	Create a new branch named <new_branch> and start it at
-- 
1.8.5.1

Re: [PATCH] Documentation clarification on git-checkout regarding ours/theirs

[Junio C Hamano]

"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>
> ---
>  Documentation/git-checkout.txt | 6 +++++-
>  1 file changed, 5 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
> index d263a56..5c3ef86 100644
> --- a/Documentation/git-checkout.txt
> +++ b/Documentation/git-checkout.txt
> @@ -115,7 +115,11 @@ 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.
> ++
> +After a `git pull --rebase`, for example, 'ours' points to the remote
> +version and 'theirs' points to the local version. See linkgit:git-merge[1]
> +for details about stages #2 and #3.

I think it is a good idea to mention that it takes a switching of
viewpoint [*1*] when reading ours/theirs during "git rebase" (and by
extension "git pull --rebase").

But I am afraid that it may be detrimental to say 'for example' and
mentioning _only that_ for two reasons:

 - it does not make it clear what is said in that paragraph is an
   exception, which would mislead those who are doing "git pull"
   without rebase (for them, --ours is their own work, --theirs is
   what they are pulling from outside).

 - it does not make it clear that the paragraph is giving a
   warning---many people who think they know what they are doing
   would stop reading carefully after seeing 'for example', so those
   who do use 'rebase' (either 'git rebase' or 'git pull --rebase')
   would miss the subtlety.

Perhaps rephrasing it to make it clear that this describes a warning
about an exception may be needed?  Starting the paragraph like so,
perhaps:

    Note that during `git rebase` and `git pull -rebase`, 'ours' and
    'theirs' may appear to be swapped (i.e. 'ours' is the history
    from the remote or the history onto which you are rebasing, and
    'theirs' is the history of your private work).  This is for such
    and such reasons...


[Footnote]

*1* The reason why ours/theirs appear to be swapped during a rebase
is because you are temporarily assuming the role of the keeper of
the canonical history while doing so.  A rebase is to treat the
history that came from the remote as the canonical one, and then
treat what you did as the "third party" work that need to be
integrated into the canonical history.  That makes what you obtained
from the remote "ours" (i.e. the shared history of our project we
collectively own) and yoru work "theirs" (i.e. other people's work
to be integrated into "our" shared history, but you happen to be
that "other people" in this case).

[PATCH] Documentation clarification on git-checkout regarding ours/theirs

[Simon A. Eugster]

From: "Simon A. Eugster" <simon.eugster@eps.ch>

Signed-off-by: Simon A. Eugster <simon.eugster@eps.ch>
---
 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
-- 
1.8.5.1

Re: [PATCH] Documentation clarification on git-checkout regarding ours/theirs

[Junio C Hamano]

"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

Re: [PATCH] Documentation clarification on git-checkout regarding ours/theirs

[Simon A. Eugster]

Am 10.07.2015 um 22:07 schrieb Junio C Hamano:
> "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.

Agree! How about the reference to git-merge? I had to google for stage 
to find the documentation on it.
>
>> +	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?

Yes.

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

I think there is an “s” missing in “… and treat the work done on the 
branch …”, but not quite sure.

Apart from this, very clear and perfect to me.

Thanks for your effort!
Simon

Re: [PATCH] Documentation clarification on git-checkout regarding ours/theirs

[Junio C Hamano]

"Simon A. Eugster" <simon.eu@gmail.com> writes:

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

Thanks, you are right.  Will fix.