threads / discuss / 59776

I think there is error in merge documents - current branch

Subject: I think there is error in merge documents - current branch

## tl;dr

9 messages between May 20, 2023 and May 21, 2023.

replies: 8people: 4as markdown or json

Minnie Shi· May 20, 2023, 08:01 UTC · lore

Hi team, In there git merge document: https://git-scm.com/docs/git-merge

If you search the word “current”, you will see the paragraph describing a situation which changed the context. More specifically below the screenshot, the last one should be commit H instead of commit C , because the description talks about the `current branch is master`, and `git merge topic`` is being described.

in summary the sentence should be read as

Before the operation, ORIG_HEAD is set to the tip of the current branch (H). instead of Before the operation, ORIG_HEAD is set to the tip of the current branch (C).

Kind regards Min

Kristoffer Haugsbakk· May 20, 2023, 08:44 UTC · re: Minnie Shi · lore

[PATCH] doc: merge: fix mention of `ORIG_HEAD`

`ORIG_HEAD` before the attempted merge points at the commit that you are on (the tip of `master`), not the tip of the branch that you are trying to merge in.

Reported-by: Minnie Shi <minnie.shi@gmail.com>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-merge.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 0aeff572a59..9019b6a1e50 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -38,7 +38,7 @@ Then "`git merge topic`" will replay the changes made on the
 its current commit (`C`) on top of `master`, and record the result
 in a new commit along with the names of the two parent commits and
 a log message from the user describing the changes. Before the operation,
-`ORIG_HEAD` is set to the tip of the current branch (`C`).
+`ORIG_HEAD` is set to the tip of the current branch (`G`).
 
 ------------
 	  A---B---C topic

-- 
2.41.0.rc1
Minnie Shi· May 20, 2023, 09:25 UTC · re: Kristoffer Haugsbakk · lore

Re: [PATCH] doc: merge: fix mention of `ORIG_HEAD`

The document says the “current” branch is master , which means the HEAD is (G), which does not matter, it is not what I am challenging.

What I am challenging is that it continues the context and says:

Before the operation, -`ORIG_HEAD` is set to the tip of the "current" branch (`C`).

that is not true, current branch is master, and it is (G), Maybe it should be changed to "topic branch", so it reads like this:

Before the operation, -`ORIG_HEAD` is set to the tip of the ”topic” branch (`C`).

Min

On Sat, May 20, 2023 at 10:45 AM Kristoffer Haugsbakk <code@khaugsbakk.name> wrote:

Show 27 quoted lines
>
> `ORIG_HEAD` before the attempted merge points at the commit that you are
> on (the tip of `master`), not the tip of the branch that you are trying
> to merge in.
>
> Reported-by: Minnie Shi <minnie.shi@gmail.com>
> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
> ---
>  Documentation/git-merge.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
> index 0aeff572a59..9019b6a1e50 100644
> --- a/Documentation/git-merge.txt
> +++ b/Documentation/git-merge.txt
> @@ -38,7 +38,7 @@ Then "`git merge topic`" will replay the changes made on the
>  its current commit (`C`) on top of `master`, and record the result
>  in a new commit along with the names of the two parent commits and
>  a log message from the user describing the changes. Before the operation,
> -`ORIG_HEAD` is set to the tip of the current branch (`C`).
> +`ORIG_HEAD` is set to the tip of the current branch (`G`).
>
>  ------------
>           A---B---C topic
> --
> 2.41.0.rc1
>
-- 
Kind regards
Min
Minnie Shi· May 20, 2023, 09:41 UTC · re: Minnie Shi · lore

Re: [PATCH] doc: merge: fix mention of `ORIG_HEAD`

Okay, i read one more time, i think it should be read as

Before the operation, -`ORIG_HEAD` is set to the tip of the "current" branch (`G`)

instead of Before the operation, -`ORIG_HEAD` is set to the tip of the "current" branch (`C`)

On Sat, May 20, 2023 at 11:25 AM Minnie Shi <minnie.shi@gmail.com> wrote:
Show 52 quoted lines
>
> The document says the “current” branch is master , which means the
> HEAD is (G), which does not matter, it is not what I am challenging.
>
> What I am challenging is that it continues the context and says:
>
> Before the operation,
> -`ORIG_HEAD` is set to the tip of the "current" branch (`C`).
>
> that is not true, current branch is master, and it is (G), Maybe it
> should be changed to "topic branch", so it reads like this:
>
> Before the operation,
> -`ORIG_HEAD` is set to the tip of the ”topic” branch (`C`).
>
>
> Min
>
> On Sat, May 20, 2023 at 10:45 AM Kristoffer Haugsbakk
> <code@khaugsbakk.name> wrote:
> >
> > `ORIG_HEAD` before the attempted merge points at the commit that you are
> > on (the tip of `master`), not the tip of the branch that you are trying
> > to merge in.
> >
> > Reported-by: Minnie Shi <minnie.shi@gmail.com>
> > Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
> > ---
> >  Documentation/git-merge.txt | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> >
> > diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
> > index 0aeff572a59..9019b6a1e50 100644
> > --- a/Documentation/git-merge.txt
> > +++ b/Documentation/git-merge.txt
> > @@ -38,7 +38,7 @@ Then "`git merge topic`" will replay the changes made on the
> >  its current commit (`C`) on top of `master`, and record the result
> >  in a new commit along with the names of the two parent commits and
> >  a log message from the user describing the changes. Before the operation,
> > -`ORIG_HEAD` is set to the tip of the current branch (`C`).
> > +`ORIG_HEAD` is set to the tip of the current branch (`G`).
> >
> >  ------------
> >           A---B---C topic
> > --
> > 2.41.0.rc1
> >
>
>
> --
> Kind regards
> Min
-- 
Kind regards
Min
Junio C Hamano· May 20, 2023, 22:27 UTC · re: Minnie Shi · lore

Re: I think there is error in merge documents - current branch

Minnie Shi <minnie.shi@gmail.com> writes:
Show 5 quoted lines
> in summary the sentence should be read as
>
> Before the operation, ORIG_HEAD is set to the tip of the current branch (H).
> instead of
> Before the operation, ORIG_HEAD is set to the tip of the current branch (C).
Not C but G (i.e. the tip _before_ the history is updated).

I notice that we overuse "current" there. One is to refer to the most recent commit on a branch, the other is to refer to the branch that is checked out. For the former, we say "the tip" in the other sentence, and it probably will make it less ambiguous if used that phrase.

    Then "`git merge topic`" will replay the changes made on the
    `topic` branch since it diverged from `master` (i.e., `E`) until
    the commit at the tip of the `topic` (`C`) on top of `master`,
    and record the result
    in a new commit along with the names of the two parent commits and
    a log message from the user describing the changes. Before the operation,
    `ORIG_HEAD` is set to the tip of the current branch (`G`).

My reading also hiccupped with "replay"; the first sentence to explain the command says "incorporate the changes", and that may be a less confusing expression; "replay" somehow makes me imagine that the changes are cherry-picked one by one---it may be only me, so I left it as-is in the suggestion above.

Thanks.
Kristoffer Haugsbakk· May 21, 2023, 10:49 UTC · re: Junio C Hamano · lore

Re: I think there is error in merge documents - current branch

On Sun, May 21, 2023, at 00:27, Junio C Hamano wrote:
Show 5 quoted lines
> My reading also hiccupped with "replay"; the first sentence to
> explain the command says "incorporate the changes", and that may be
> a less confusing expression; "replay" somehow makes me imagine that
> the changes are cherry-picked one by one---it may be only me, so I
> left it as-is in the suggestion above.

Yeah, it made me think of cherry-picks, essentially (specifically a rebase). “Replaying” doesn’t seem relevant in this context, but that’s just based on my layman conceptualization of how git-merge works.

“will replay the changes made on the” comes from b40bb374a61 (Documentation: merge: add an overview, 2010-01-23), which expanded the first paragraph of Description and added the two examples.

-- 
Kristoffer Haugsbakk
Sergey Organov· May 21, 2023, 12:23 UTC · re: Junio C Hamano · lore

Re: I think there is error in merge documents - current branch

Junio C Hamano <gitster@pobox.com> writes:
Show 29 quoted lines
> Minnie Shi <minnie.shi@gmail.com> writes:
>
>> in summary the sentence should be read as
>>
>> Before the operation, ORIG_HEAD is set to the tip of the current branch (H).
>> instead of
>> Before the operation, ORIG_HEAD is set to the tip of the current branch (C).
>
> Not C but G (i.e. the tip _before_ the history is updated).
>
> I notice that we overuse "current" there.  One is to refer to the
> most recent commit on a branch, the other is to refer to the branch
> that is checked out.  For the former, we say "the tip" in the other
> sentence, and it probably will make it less ambiguous if used that
> phrase.
>
>     Then "`git merge topic`" will replay the changes made on the
>     `topic` branch since it diverged from `master` (i.e., `E`) until
>     the commit at the tip of the `topic` (`C`) on top of `master`,
>     and record the result
>     in a new commit along with the names of the two parent commits and
>     a log message from the user describing the changes. Before the operation,
>     `ORIG_HEAD` is set to the tip of the current branch (`G`).
>
> My reading also hiccupped with "replay"; the first sentence to
> explain the command says "incorporate the changes", and that may be
> a less confusing expression; "replay" somehow makes me imagine that
> the changes are cherry-picked one by one---it may be only me, so I
> left it as-is in the suggestion above.

For me "apply changes" or even "apply cumulative changes" works much better than "replay changes" in this context, especially provided we will apparently have "git replay" soon.

Thanks, -- Sergey Organov

Minnie Shi· May 21, 2023, 13:28 UTC · re: Sergey Organov · lore

Re: I think there is error in merge documents - current branch

Hi All,

What is the procedure to update the document to correct the error? As I responded yesterday, see below. we need to change the error.

From: Minnie Shi <minnie.shi@gmail.com>
Date: Sat, May 20, 2023 at 11:41 AM
Subject: Re: [PATCH] doc: merge: fix mention of `ORIG_HEAD`
To: Kristoffer Haugsbakk <code@khaugsbakk.name>
Cc: <git@vger.kernel.org>, Kristoffer Haugsbakk <code@khaugsbakk.name>
Okay, i read one more time, i think it should be read as

Before the operation, -`ORIG_HEAD` is set to the tip of the "current" branch (`G`)

instead of Before the operation, -`ORIG_HEAD` is set to the tip of the "current" branch (`C`)

Kind regards, Mi

On Sun, May 21, 2023 at 2:23 PM Sergey Organov <sorganov@gmail.com> wrote:
Show 39 quoted lines
>
> Junio C Hamano <gitster@pobox.com> writes:
>
> > Minnie Shi <minnie.shi@gmail.com> writes:
> >
> >> in summary the sentence should be read as
> >>
> >> Before the operation, ORIG_HEAD is set to the tip of the current branch (H).
> >> instead of
> >> Before the operation, ORIG_HEAD is set to the tip of the current branch (C).
> >
> > Not C but G (i.e. the tip _before_ the history is updated).
> >
> > I notice that we overuse "current" there.  One is to refer to the
> > most recent commit on a branch, the other is to refer to the branch
> > that is checked out.  For the former, we say "the tip" in the other
> > sentence, and it probably will make it less ambiguous if used that
> > phrase.
> >
> >     Then "`git merge topic`" will replay the changes made on the
> >     `topic` branch since it diverged from `master` (i.e., `E`) until
> >     the commit at the tip of the `topic` (`C`) on top of `master`,
> >     and record the result
> >     in a new commit along with the names of the two parent commits and
> >     a log message from the user describing the changes. Before the operation,
> >     `ORIG_HEAD` is set to the tip of the current branch (`G`).
> >
> > My reading also hiccupped with "replay"; the first sentence to
> > explain the command says "incorporate the changes", and that may be
> > a less confusing expression; "replay" somehow makes me imagine that
> > the changes are cherry-picked one by one---it may be only me, so I
> > left it as-is in the suggestion above.
>
> For me "apply changes" or even "apply cumulative changes" works much
> better than "replay changes" in this context, especially provided we
> will apparently have "git replay" soon.
>
> Thanks,
> -- Sergey Organov
-- 
Kind regards
Min
Minnie Shi· May 21, 2023, 13:49 UTC · re: Minnie Shi · lore

Re: I think there is error in merge documents - current branch

do not worry, I found the instructions: https://git-scm.com/docs/SubmittingPatches; also just realized that Kristofer Haugsbakk already submitted a patch (initially I thought his email was just a response). We are all good now.

Thanks for your time.
Min
On Sun, May 21, 2023 at 3:28 PM Minnie Shi <minnie.shi@gmail.com> wrote:
Show 71 quoted lines
>
> Hi All,
>
> What is the procedure to update the document to correct the error? As
> I responded yesterday, see below. we need to change the error.
>
> From: Minnie Shi <minnie.shi@gmail.com>
> Date: Sat, May 20, 2023 at 11:41 AM
> Subject: Re: [PATCH] doc: merge: fix mention of `ORIG_HEAD`
> To: Kristoffer Haugsbakk <code@khaugsbakk.name>
> Cc: <git@vger.kernel.org>, Kristoffer Haugsbakk <code@khaugsbakk.name>
>
>
> Okay, i read one more time, i think it should be read as
>
> Before the operation,
> -`ORIG_HEAD` is set to the tip of the "current" branch (`G`)
>
> instead of
> Before the operation,
> -`ORIG_HEAD` is set to the tip of the "current" branch (`C`)
>
> Kind regards,
> Mi
>
> On Sun, May 21, 2023 at 2:23 PM Sergey Organov <sorganov@gmail.com> wrote:
> >
> > Junio C Hamano <gitster@pobox.com> writes:
> >
> > > Minnie Shi <minnie.shi@gmail.com> writes:
> > >
> > >> in summary the sentence should be read as
> > >>
> > >> Before the operation, ORIG_HEAD is set to the tip of the current branch (H).
> > >> instead of
> > >> Before the operation, ORIG_HEAD is set to the tip of the current branch (C).
> > >
> > > Not C but G (i.e. the tip _before_ the history is updated).
> > >
> > > I notice that we overuse "current" there.  One is to refer to the
> > > most recent commit on a branch, the other is to refer to the branch
> > > that is checked out.  For the former, we say "the tip" in the other
> > > sentence, and it probably will make it less ambiguous if used that
> > > phrase.
> > >
> > >     Then "`git merge topic`" will replay the changes made on the
> > >     `topic` branch since it diverged from `master` (i.e., `E`) until
> > >     the commit at the tip of the `topic` (`C`) on top of `master`,
> > >     and record the result
> > >     in a new commit along with the names of the two parent commits and
> > >     a log message from the user describing the changes. Before the operation,
> > >     `ORIG_HEAD` is set to the tip of the current branch (`G`).
> > >
> > > My reading also hiccupped with "replay"; the first sentence to
> > > explain the command says "incorporate the changes", and that may be
> > > a less confusing expression; "replay" somehow makes me imagine that
> > > the changes are cherry-picked one by one---it may be only me, so I
> > > left it as-is in the suggestion above.
> >
> > For me "apply changes" or even "apply cumulative changes" works much
> > better than "replay changes" in this context, especially provided we
> > will apparently have "git replay" soon.
> >
> > Thanks,
> > -- Sergey Organov
>
>
>
> --
> Kind regards
> Min
-- 
Kind regards
Min

← back to recent threads