Re: [PATCH 2/2] Documentation on git-checkout --ours/--theirs improved

>
> "Simon A. Eugster" <simon.eu@gmail.com> writes:
>
> > ---
>
> - Lack of explanation as to why this is a good thing.
> - Lack of sign-off.
>
> Why is there still 1/2, if its effect is wholly annulled by a
> subsequent step 2/2?

> >  Documentation/git-checkout.txt | 39 +++++++++++++++++++++++++++++++++++----
> >  1 file changed, 35 insertions(+), 4 deletions(-)
> >
> > diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
> > index 5c3ef86..ec0be28 100644
> > --- a/Documentation/git-checkout.txt
> > +++ b/Documentation/git-checkout.txt
> > @@ -116,10 +116,41 @@ entries; instead, unmerged entries are ignored.
> >  --theirs::
> >       When checking out paths from the index, check out stage #2
> >       ('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.
> > +     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.
>
> "We define" sounds a bit strange to me.
>
> It is not "we" who define so.  Those who use "rebase" because they
> employ a shared central repository workflow are the ones that treat
> the history of their "remote repository" (which is their shared
> central repository) as the canonical one.

>         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 while you are
>         rebasing, you are temporarily assuming the role of the
>         keeper of the canonical history.  As the keeper of the
>         canonical history, you would view the history from the
>         remote as `ours`, while what you did on your side branch as
>         `theirs`.

> > +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.
> > ++
> > +Normal merging:
> > +------------
> > +local ---------abC                  <-- canonical history
> > +                 | git checkout --ours
> > +                 v
> > +MERGE ---------abC
> > +                 ^
> > +                 | git checkout --theirs
> > +origin/master ---Xyz
> > +------------
> > +Rebasing:
> > +------------
> > +local -----------Abc
> > +                 | git checkout --theirs
> > +                 v
> > +REBASE --------xyZ
> > +                 ^
> > +                 | git checkout --ours
> > +origin/master -xyZ                    <-- canonical history
> > +------------
>
> I can see that an arrow with "canonical history" points at different
> things between the two pictures, but other than that, I am not sure
> what these are trying to illustrate.  Especially between abc and
> xyz, why does the former choose abc while the latter choooses xyz?
> Are these pictures meant to show what happens when the user says
> "checkout --ours" during a conflicted integration (whether it is a
> merge or a rebase)?