{"thread":{"id":"39597","subject":"[PATCH] Documentation clarification on git-checkout regarding ours/theirs","startedAt":"2015-06-11T11:39:26Z","lastAt":"2015-06-17T15:10:02Z","messageCount":10,"participants":["Simon A. Eugster","Junio C Hamano","Simon Eugster"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"263579","messageId":"1434022766-45397-1-git-send-email-simon.eu@gmail.com","threadId":"39597","inReplyTo":null,"subject":"[PATCH] Documentation clarification on git-checkout regarding ours/theirs","fromName":"Simon A. Eugster","fromEmail":"simon.eu@gmail.com","sentAt":"2015-06-11T11:39:26Z","receivedAt":"2015-06-11T11:39:26Z","isPatch":true,"sender":{"key":"simon.eu@gmail.com","avatar":"https://gravatar.com/avatar/2d01e8abdb24d0b8244013b7e0c7e8df89cebe98587ffe7efad74b8a7bce4e71?d=mp&s=160"},"body":"From: \"Simon A. Eugster\" \n\nSigned-off-by: Simon A. Eugster \n---\n Documentation/git-checkout.txt | 6 +++++-\n 1 file changed, 5 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex d263a56..5c3ef86 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -115,7 +115,11 @@ entries; instead, unmerged entries are ignored.\n --ours::\n --theirs::\n \tWhen checking out paths from the index, check out stage #2\n-\t('ours') or #3 ('theirs') for unmerged paths.\n+\t('ours', HEAD) or #3 ('theirs', MERGE_HEAD) for unmerged paths.\n++\n+After a `git pull --rebase`, for example, 'ours' points to the remote\n+version and 'theirs' points to the local version. See linkgit:git-merge[1]\n+for details about stages #2 and #3.\n \n -b ::\n \tCreate a new branch named and start it at\n-- \n1.8.5.1\n"},{"id":"263596","messageId":"xmqqwpzafe88.fsf@gitster.dls.corp.google.com","threadId":"39597","inReplyTo":"1434022766-45397-1-git-send-email-simon.eu@gmail.com","subject":"Re: [PATCH] Documentation clarification on git-checkout regarding ours/theirs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-06-11T15:37:27Z","receivedAt":"2015-06-11T15:37:27Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Simon A. Eugster\" writes:\n\n> From: \"Simon A. Eugster\" \n>\n> Signed-off-by: Simon A. Eugster \n> ---\n> Documentation/git-checkout.txt | 6 +++++-\n> 1 file changed, 5 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\n> index d263a56..5c3ef86 100644\n> --- a/Documentation/git-checkout.txt\n> +++ b/Documentation/git-checkout.txt\n> @@ -115,7 +115,11 @@ entries; instead, unmerged entries are ignored.\n> --ours::\n> --theirs::\n> \tWhen checking out paths from the index, check out stage #2\n> -\t('ours') or #3 ('theirs') for unmerged paths.\n> +\t('ours', HEAD) or #3 ('theirs', MERGE_HEAD) for unmerged paths.\n> ++\n> +After a `git pull --rebase`, for example, 'ours' points to the remote\n> +version and 'theirs' points to the local version. See linkgit:git-merge[1]\n> +for details about stages #2 and #3.\n\nI think it is a good idea to mention that it takes a switching of\nviewpoint [*1*] when reading ours/theirs during \"git rebase\" (and by\nextension \"git pull --rebase\").\n\nBut I am afraid that it may be detrimental to say 'for example' and\nmentioning _only that_ for two reasons:\n\n - it does not make it clear what is said in that paragraph is an\n exception, which would mislead those who are doing \"git pull\"\n without rebase (for them, --ours is their own work, --theirs is\n what they are pulling from outside).\n\n - it does not make it clear that the paragraph is giving a\n warning---many people who think they know what they are doing\n would stop reading carefully after seeing 'for example', so those\n who do use 'rebase' (either 'git rebase' or 'git pull --rebase')\n would miss the subtlety.\n\nPerhaps rephrasing it to make it clear that this describes a warning\nabout an exception may be needed? Starting the paragraph like so,\nperhaps:\n\n Note that during `git rebase` and `git pull -rebase`, 'ours' and\n 'theirs' may appear to be swapped (i.e. 'ours' is the history\n from the remote or the history onto which you are rebasing, and\n 'theirs' is the history of your private work). This is for such\n and such reasons...\n\n\n[Footnote]\n\n*1* The reason why ours/theirs appear to be swapped during a rebase\nis because you are temporarily assuming the role of the keeper of\nthe canonical history while doing so. A rebase is to treat the\nhistory that came from the remote as the canonical one, and then\ntreat what you did as the \"third party\" work that need to be\nintegrated into the canonical history. That makes what you obtained\nfrom the remote \"ours\" (i.e. the shared history of our project we\ncollectively own) and yoru work \"theirs\" (i.e. other people's work\nto be integrated into \"our\" shared history, but you happen to be\nthat \"other people\" in this case).\n"},{"id":"263856","messageId":"1434372447-51230-1-git-send-email-simon.eu@gmail.com","threadId":"39597","inReplyTo":"xmqqwpzafe88.fsf@gitster.dls.corp.google.com","subject":"[PATCH] Documentation clarification on git-checkout","fromName":"Simon A. Eugster","fromEmail":"simon.eu@gmail.com","sentAt":"2015-06-15T12:47:25Z","receivedAt":"2015-06-15T12:47:25Z","isPatch":true,"sender":{"key":"simon.eu@gmail.com","avatar":"https://gravatar.com/avatar/2d01e8abdb24d0b8244013b7e0c7e8df89cebe98587ffe7efad74b8a7bce4e71?d=mp&s=160"},"body":"\nI hope I managed to get this working with replying to your response, \nJunio, git send-email is all new to me.\n\nThanks a lot for your detailled answer. I tried to integrate it and \nhope it is understandable this way? \n\nSimon\n"},{"id":"263857","messageId":"1434372447-51230-2-git-send-email-simon.eu@gmail.com","threadId":"39597","inReplyTo":"1434372447-51230-1-git-send-email-simon.eu@gmail.com","subject":"[PATCH 1/2] Documentation clarification on git-checkout regarding ours/theirs","fromName":"Simon A. Eugster","fromEmail":"simon.eu@gmail.com","sentAt":"2015-06-15T12:47:26Z","receivedAt":"2015-06-15T12:47:26Z","isPatch":true,"sender":{"key":"simon.eu@gmail.com","avatar":"https://gravatar.com/avatar/2d01e8abdb24d0b8244013b7e0c7e8df89cebe98587ffe7efad74b8a7bce4e71?d=mp&s=160"},"body":"From: \"Simon A. Eugster\" \n\nSigned-off-by: Simon A. Eugster \n---\n Documentation/git-checkout.txt | 6 +++++-\n 1 file changed, 5 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex d263a56..5c3ef86 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -115,7 +115,11 @@ entries; instead, unmerged entries are ignored.\n --ours::\n --theirs::\n \tWhen checking out paths from the index, check out stage #2\n-\t('ours') or #3 ('theirs') for unmerged paths.\n+\t('ours', HEAD) or #3 ('theirs', MERGE_HEAD) for unmerged paths.\n++\n+After a `git pull --rebase`, for example, 'ours' points to the remote\n+version and 'theirs' points to the local version. See linkgit:git-merge[1]\n+for details about stages #2 and #3.\n \n -b ::\n \tCreate a new branch named and start it at\n-- \n1.8.5.1\n"},{"id":"263858","messageId":"1434372447-51230-3-git-send-email-simon.eu@gmail.com","threadId":"39597","inReplyTo":"1434372447-51230-1-git-send-email-simon.eu@gmail.com","subject":"[PATCH 2/2] Documentation on git-checkout --ours/--theirs improved","fromName":"Simon A. Eugster","fromEmail":"simon.eu@gmail.com","sentAt":"2015-06-15T12:47:27Z","receivedAt":"2015-06-15T12:47:27Z","isPatch":true,"sender":{"key":"simon.eu@gmail.com","avatar":"https://gravatar.com/avatar/2d01e8abdb24d0b8244013b7e0c7e8df89cebe98587ffe7efad74b8a7bce4e71?d=mp&s=160"},"body":"---\n Documentation/git-checkout.txt | 39 +++++++++++++++++++++++++++++++++++----\n 1 file changed, 35 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 5c3ef86..ec0be28 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -116,10 +116,41 @@ entries; instead, unmerged entries are ignored.\n --theirs::\n \tWhen checking out paths from the index, check out stage #2\n \t('ours', HEAD) or #3 ('theirs', MERGE_HEAD) for unmerged paths.\n-+\n-After a `git pull --rebase`, for example, 'ours' points to the remote\n-version and 'theirs' points to the local version. See linkgit:git-merge[1]\n-for details about stages #2 and #3.\n+\tSee linkgit:git-merge[1] for details about stages #2 and #3.\n++\n+Note that during `git rebase` and `git pull --rebase`, 'theirs' checks out\n+the local version, and 'ours' the remote version or the history that is rebased\n+against.\n++\n+The reason ours/theirs appear to be swapped during a rebase is that we\n+define the remote history as the canonical history, on top of which our\n+private commits are applied on, as opposed to normal merging where the\n+local history is the canonical one.\n+During merging, we assume the role of the canonical history’s keeper,\n+which, in case of a rebase, is the remote history, and our private commits\n+look to the keeper as “their” commits which need to be integrated on top\n+of “our” work.\n++\n+Normal merging:\n+------------\n+local ---------abC <-- canonical history\n+ | git checkout --ours\n+ v\n+MERGE ---------abC\n+ ^\n+ | git checkout --theirs\n+origin/master ---Xyz\n+------------\n+Rebasing:\n+------------\n+local -----------Abc\n+ | git checkout --theirs\n+ v\n+REBASE --------xyZ\n+ ^\n+ | git checkout --ours\n+origin/master -xyZ <-- canonical history\n+------------\n \n -b ::\n \tCreate a new branch named and start it at\n-- \n1.8.5.1\n"},{"id":"263896","messageId":"xmqq381s91gz.fsf@gitster.dls.corp.google.com","threadId":"39597","inReplyTo":"1434372447-51230-3-git-send-email-simon.eu@gmail.com","subject":"Re: [PATCH 2/2] Documentation on git-checkout --ours/--theirs improved","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-06-15T20:10:52Z","receivedAt":"2015-06-15T20:10:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Simon A. Eugster\" writes:\n\n> ---\n\n- Lack of explanation as to why this is a good thing.\n- Lack of sign-off.\n\nWhy is there still 1/2, if its effect is wholly annulled by a\nsubsequent step 2/2?\n\n> Documentation/git-checkout.txt | 39 +++++++++++++++++++++++++++++++++++----\n> 1 file changed, 35 insertions(+), 4 deletions(-)\n>\n> diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\n> index 5c3ef86..ec0be28 100644\n> --- a/Documentation/git-checkout.txt\n> +++ b/Documentation/git-checkout.txt\n> @@ -116,10 +116,41 @@ entries; instead, unmerged entries are ignored.\n> --theirs::\n> \tWhen checking out paths from the index, check out stage #2\n> \t('ours', HEAD) or #3 ('theirs', MERGE_HEAD) for unmerged paths.\n> -+\n> -After a `git pull --rebase`, for example, 'ours' points to the remote\n> -version and 'theirs' points to the local version. See linkgit:git-merge[1]\n> -for details about stages #2 and #3.\n> +\tSee linkgit:git-merge[1] for details about stages #2 and #3.\n> ++\n> +Note that during `git rebase` and `git pull --rebase`, 'theirs' checks out\n> +the local version, and 'ours' the remote version or the history that is rebased\n> +against.\n> ++\n> +The reason ours/theirs appear to be swapped during a rebase is that we\n> +define the remote history as the canonical history, on top of which our\n> +private commits are applied on, as opposed to normal merging where the\n> +local history is the canonical one.\n\n\"We define\" sounds a bit strange to me.\n\nIt is not \"we\" who define so. Those who use \"rebase\" because they\nemploy a shared central repository workflow are the ones that treat\nthe history of their \"remote repository\" (which is their shared\ncentral repository) as the canonical one.\n\n\n\tNote that during `git rebase` and `git pull --rebase`,\n\t'ours' and 'theirs' may appear swapped; `--ours` gives the\n\tversion from the branch the changes are rebased onto, while\n\t`--theirs` gives the version from the branch that holds your\n\twork that is being rebased.\n\n\tThis is because `rebase` is used in a workflow that treats\n\tthe history at the remote as the shared canonical one, and\n\ttreat the work done on the branch you are rebasing as the\n\tthird-party work to be integrated, and while you are\n\trebasing, you are temporarily assuming the role of the\n\tkeeper of the canonical history. As the keeper of the\n\tcanonical history, you would view the history from the\n\tremote as `ours`, while what you did on your side branch as\n\t`theirs`.\n\n\n\n> +During merging, we assume the role of the canonical history’s keeper,\n> +which, in case of a rebase, is the remote history, and our private commits\n> +look to the keeper as “their” commits which need to be integrated on top\n> +of “our” work.\n> ++\n> +Normal merging:\n> +------------\n> +local ---------abC <-- canonical history\n> + | git checkout --ours\n> + v\n> +MERGE ---------abC\n> + ^\n> + | git checkout --theirs\n> +origin/master ---Xyz\n> +------------\n> +Rebasing:\n> +------------\n> +local -----------Abc\n> + | git checkout --theirs\n> + v\n> +REBASE --------xyZ\n> + ^\n> + | git checkout --ours\n> +origin/master -xyZ <-- canonical history\n> +------------\n\nI can see that an arrow with \"canonical history\" points at different\nthings between the two pictures, but other than that, I am not sure\nwhat these are trying to illustrate. Especially between abc and\nxyz, why does the former choose abc while the latter choooses xyz?\nAre these pictures meant to show what happens when the user says\n\"checkout --ours\" during a conflicted integration (whether it is a\nmerge or a rebase)?\n\nThanks.\n\n> \n> -b ::\n> \tCreate a new branch named and start it at\n"},{"id":"263915","messageId":"CAO8d5Bbi8LHHP0nnYwv=_Qr6KZCJmFPTq5ut2KzeSKJ-i0RZNg@mail.gmail.com","threadId":"39597","inReplyTo":"xmqq381s91gz.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH 2/2] Documentation on git-checkout --ours/--theirs improved","fromName":"Simon Eugster","fromEmail":"simon.eu@gmail.com","sentAt":"2015-06-16T07:03:06Z","receivedAt":"2015-06-16T07:03:06Z","isPatch":true,"sender":{"key":"simon.eu@gmail.com","avatar":"https://gravatar.com/avatar/2d01e8abdb24d0b8244013b7e0c7e8df89cebe98587ffe7efad74b8a7bce4e71?d=mp&s=160"},"body":"2015-06-15 22:10 GMT+02:00 Junio C Hamano :\n>\n> \"Simon A. Eugster\" writes:\n>\n> > ---\n>\n> - Lack of explanation as to why this is a good thing.\n> - Lack of sign-off.\n>\n> Why is there still 1/2, if its effect is wholly annulled by a\n> subsequent step 2/2?\n\n\nSorry for that, still trying to find out how git send-email works.\n\n> > Documentation/git-checkout.txt | 39 +++++++++++++++++++++++++++++++++++----\n> > 1 file changed, 35 insertions(+), 4 deletions(-)\n> >\n> > diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\n> > index 5c3ef86..ec0be28 100644\n> > --- a/Documentation/git-checkout.txt\n> > +++ b/Documentation/git-checkout.txt\n> > @@ -116,10 +116,41 @@ entries; instead, unmerged entries are ignored.\n> > --theirs::\n> > When checking out paths from the index, check out stage #2\n> > ('ours', HEAD) or #3 ('theirs', MERGE_HEAD) for unmerged paths.\n> > -+\n> > -After a `git pull --rebase`, for example, 'ours' points to the remote\n> > -version and 'theirs' points to the local version. See linkgit:git-merge[1]\n> > -for details about stages #2 and #3.\n> > + See linkgit:git-merge[1] for details about stages #2 and #3.\n> > ++\n> > +Note that during `git rebase` and `git pull --rebase`, 'theirs' checks out\n> > +the local version, and 'ours' the remote version or the history that is rebased\n> > +against.\n> > ++\n> > +The reason ours/theirs appear to be swapped during a rebase is that we\n> > +define the remote history as the canonical history, on top of which our\n> > +private commits are applied on, as opposed to normal merging where the\n> > +local history is the canonical one.\n>\n> \"We define\" sounds a bit strange to me.\n>\n> It is not \"we\" who define so. Those who use \"rebase\" because they\n> employ a shared central repository workflow are the ones that treat\n> the history of their \"remote repository\" (which is their shared\n> central repository) as the canonical one.\n\n\nYes, that is how it is meant; I checked other parts of the\ndocumentation of git-checkout, and they use the same style, e.g.:\n > Let’s look at what happens when we checkout commit b (here we show\ntwo ways this may be done)\n\n\n> Note that during `git rebase` and `git pull --rebase`,\n> 'ours' and 'theirs' may appear swapped; `--ours` gives the\n> version from the branch the changes are rebased onto, while\n> `--theirs` gives the version from the branch that holds your\n> work that is being rebased.\n>\n> This is because `rebase` is used in a workflow that treats\n> the history at the remote as the shared canonical one, and\n> treat the work done on the branch you are rebasing as the\n> third-party work to be integrated, and while you are\n> rebasing, you are temporarily assuming the role of the\n> keeper of the canonical history. As the keeper of the\n> canonical history, you would view the history from the\n> remote as `ours`, while what you did on your side branch as\n> `theirs`.\n\nCould you commit your version? I think that's easier.\n\n> > +During merging, we assume the role of the canonical history’s keeper,\n> > +which, in case of a rebase, is the remote history, and our private commits\n> > +look to the keeper as “their” commits which need to be integrated on top\n> > +of “our” work.\n> > ++\n> > +Normal merging:\n> > +------------\n> > +local ---------abC <-- canonical history\n> > + | git checkout --ours\n> > + v\n> > +MERGE ---------abC\n> > + ^\n> > + | git checkout --theirs\n> > +origin/master ---Xyz\n> > +------------\n> > +Rebasing:\n> > +------------\n> > +local -----------Abc\n> > + | git checkout --theirs\n> > + v\n> > +REBASE --------xyZ\n> > + ^\n> > + | git checkout --ours\n> > +origin/master -xyZ <-- canonical history\n> > +------------\n>\n> I can see that an arrow with \"canonical history\" points at different\n> things between the two pictures, but other than that, I am not sure\n> what these are trying to illustrate. Especially between abc and\n> xyz, why does the former choose abc while the latter choooses xyz?\n> Are these pictures meant to show what happens when the user says\n> \"checkout --ours\" during a conflicted integration (whether it is a\n> merge or a rebase)?\n\n\nI tried to create a picture which shows the difference of ours and\ntheirs when merging vs. rebasing, but apparently it did not turn out\nwell, and I will just leave it away.\n\nSimon\n"},{"id":"263947","messageId":"xmqqzj3z64q9.fsf@gitster.dls.corp.google.com","threadId":"39597","inReplyTo":"CAO8d5Bbi8LHHP0nnYwv=_Qr6KZCJmFPTq5ut2KzeSKJ-i0RZNg@mail.gmail.com","subject":"Re: [PATCH 2/2] Documentation on git-checkout --ours/--theirs improved","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-06-16T15:41:02Z","receivedAt":"2015-06-16T15:41:02Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Simon Eugster writes:\n\n> 2015-06-15 22:10 GMT+02:00 Junio C Hamano :\n>>\n>> \"Simon A. Eugster\" writes:\n>>\n>> > ---\n>>\n>> - Lack of explanation as to why this is a good thing.\n>> - Lack of sign-off.\n>>\n>> Why is there still 1/2, if its effect is wholly annulled by a\n>> subsequent step 2/2?\n>\n>\n> Sorry for that, still trying to find out how git send-email works.\n\nI do not think \"git send-email\" is involved in that process in any\nway. The problem is you made the updates on top of the previous\none, without squashing. You fed two commits, instead of a squashed\none commit, to \"git send-email\", and the command obliged and sent\nthem out.\n\n>> > +During merging, we assume the role of the canonical history’s keeper,\n>> > +which, in case of a rebase, is the remote history, and our private commits\n>> > +look to the keeper as “their” commits which need to be integrated on top\n>> > +of “our” work.\n>> > ++\n>> > +Normal merging:\n>> > +------------\n>> > +local ---------abC <-- canonical history\n>> > + | git checkout --ours\n>> > + v\n>> > +MERGE ---------abC\n>> > + ^\n>> > + | git checkout --theirs\n>> > +origin/master ---Xyz\n>> > +------------\n>> > +Rebasing:\n>> > +------------\n>> > +local -----------Abc\n>> > + | git checkout --theirs\n>> > + v\n>> > +REBASE --------xyZ\n>> > + ^\n>> > + | git checkout --ours\n>> > +origin/master -xyZ <-- canonical history\n>> > +------------\n>>\n>> I can see that an arrow with \"canonical history\" points at different\n>> things between the two pictures, but other than that, I am not sure\n>> what these are trying to illustrate. Especially between abc and\n>> xyz, why does the former choose abc while the latter choooses xyz?\n>> Are these pictures meant to show what happens when the user says\n>> \"checkout --ours\" during a conflicted integration (whether it is a\n>> merge or a rebase)?\n>\n> I tried to create a picture which shows the difference of ours and\n> theirs when merging vs. rebasing, but apparently it did not turn out\n> well, and I will just leave it away.\n\nI'll wait for several days to see what other people would say, if\nthey care to comment on this. Maybe they can come up with a more\nintuitive picture, or maybe they say textual description is\nsufficiently clear that we do not need an illustration. I dunno.\n\nThanks.\n"},{"id":"264024","messageId":"CAO8d5BYkgNgB+fV2HjrUasYi0jz9YvZGuFxKNMBbWoaONpAeUA@mail.gmail.com","threadId":"39597","inReplyTo":"xmqqzj3z64q9.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH 2/2] Documentation on git-checkout --ours/--theirs improved","fromName":"Simon Eugster","fromEmail":"simon.eu@gmail.com","sentAt":"2015-06-17T14:31:45Z","receivedAt":"2015-06-17T14:31:45Z","isPatch":true,"sender":{"key":"simon.eu@gmail.com","avatar":"https://gravatar.com/avatar/2d01e8abdb24d0b8244013b7e0c7e8df89cebe98587ffe7efad74b8a7bce4e71?d=mp&s=160"},"body":"2015-06-16 17:41 GMT+02:00 Junio C Hamano :\n> Simon Eugster writes:\n>\n>> 2015-06-15 22:10 GMT+02:00 Junio C Hamano :\n>>>\n>>> \"Simon A. Eugster\" writes:\n>>>\n>>> > ---\n>>>\n>>> - Lack of explanation as to why this is a good thing.\n>>> - Lack of sign-off.\n>>>\n>>> Why is there still 1/2, if its effect is wholly annulled by a\n>>> subsequent step 2/2?\n>>\n>>\n>> Sorry for that, still trying to find out how git send-email works.\n>\n> I do not think \"git send-email\" is involved in that process in any\n> way. The problem is you made the updates on top of the previous\n> one, without squashing. You fed two commits, instead of a squashed\n> one commit, to \"git send-email\", and the command obliged and sent\n> them out.\n\nYes, I somehow expected the two commits would be added to the same\nemail because I provided the Message-Id, and yes, I could just have\nsquashed them.\n\n>>> > +During merging, we assume the role of the canonical history’s keeper,\n>>> > +which, in case of a rebase, is the remote history, and our private commits\n>>> > +look to the keeper as “their” commits which need to be integrated on top\n>>> > +of “our” work.\n>>> > ++\n>>> > +Normal merging:\n>>> > +------------\n>>> > +local ---------abC <-- canonical history\n>>> > + | git checkout --ours\n>>> > + v\n>>> > +MERGE ---------abC\n>>> > + ^\n>>> > + | git checkout --theirs\n>>> > +origin/master ---Xyz\n>>> > +------------\n>>> > +Rebasing:\n>>> > +------------\n>>> > +local -----------Abc\n>>> > + | git checkout --theirs\n>>> > + v\n>>> > +REBASE --------xyZ\n>>> > + ^\n>>> > + | git checkout --ours\n>>> > +origin/master -xyZ <-- canonical history\n>>> > +------------\n>>>\n>>> I can see that an arrow with \"canonical history\" points at different\n>>> things between the two pictures, but other than that, I am not sure\n>>> what these are trying to illustrate. Especially between abc and\n>>> xyz, why does the former choose abc while the latter choooses xyz?\n>>> Are these pictures meant to show what happens when the user says\n>>> \"checkout --ours\" during a conflicted integration (whether it is a\n>>> merge or a rebase)?\n>>\n>> I tried to create a picture which shows the difference of ours and\n>> theirs when merging vs. rebasing, but apparently it did not turn out\n>> well, and I will just leave it away.\n>\n> I'll wait for several days to see what other people would say, if\n> they care to comment on this. Maybe they can come up with a more\n> intuitive picture, or maybe they say textual description is\n> sufficiently clear that we do not need an illustration. I dunno.\n\nA better picture would be nice.\nAnd regarding the textual description, are you going to commit your version?\n"},{"id":"264027","messageId":"xmqqwpz24bhx.fsf@gitster.dls.corp.google.com","threadId":"39597","inReplyTo":"CAO8d5BYkgNgB+fV2HjrUasYi0jz9YvZGuFxKNMBbWoaONpAeUA@mail.gmail.com","subject":"Re: [PATCH 2/2] Documentation on git-checkout --ours/--theirs improved","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-06-17T15:10:02Z","receivedAt":"2015-06-17T15:10:02Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Simon Eugster writes:\n\n> A better picture would be nice.\n> And regarding the textual description, are you going to commit your version?\n\nNah, I'd rather not take credit away from you ;-)\n"}]}