"Simon A. Eugster" <simon.eu@xxxxxxxxx> writes:
> From: "Simon A. Eugster" <simon.eugster@xxxxxx>
>
> Signed-off-by: Simon A. Eugster <simon.eugster@xxxxxx>
> ---
> 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).
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html