From: Junio C Hamano <gitster@pobox.com>
To: "Simon A. Eugster" <simon.eu@gmail.com>
Cc: git@vger.kernel.org
Subject: Re: [PATCH 2/2] Documentation on git-checkout --ours/--theirs improved
Date: Mon, 15 Jun 2015 13:10:52 -0700 [thread overview]
Message-ID: <xmqq381s91gz.fsf@gitster.dls.corp.google.com> (raw)
In-Reply-To: <1434372447-51230-3-git-send-email-simon.eu@gmail.com> (Simon A. Eugster's message of "Mon, 15 Jun 2015 14:47:27 +0200")
"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)?
Thanks.
>
> -b <new_branch>::
> Create a new branch named <new_branch> and start it at
next prev parent reply other threads:[~2015-06-15 20:11 UTC|newest]
Thread overview: 10+ messages / expand[flat|nested] mbox.gz Atom feed top
2015-06-11 11:39 [PATCH] Documentation clarification on git-checkout regarding ours/theirs Simon A. Eugster
2015-06-11 15:37 ` Junio C Hamano
2015-06-15 12:47 ` [PATCH] Documentation clarification on git-checkout Simon A. Eugster
2015-06-15 12:47 ` [PATCH 1/2] Documentation clarification on git-checkout regarding ours/theirs Simon A. Eugster
2015-06-15 12:47 ` [PATCH 2/2] Documentation on git-checkout --ours/--theirs improved Simon A. Eugster
2015-06-15 20:10 ` Junio C Hamano [this message]
2015-06-16 7:03 ` Simon Eugster
2015-06-16 15:41 ` Junio C Hamano
2015-06-17 14:31 ` Simon Eugster
2015-06-17 15:10 ` Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=xmqq381s91gz.fsf@gitster.dls.corp.google.com \
--to=gitster@pobox.com \
--cc=git@vger.kernel.org \
--cc=simon.eu@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).