Contradictory git help rebase

Contradictory git help rebase

[Rodney Bates]

The text and an example in the output of git help rebase seem to contradict about
which branch gets changed by git rebase master topic.  Here is an edited version
of the output, with irrelevant stuff omitted and relationships made specific.

NAME
        git-rebase - Reapply commits on top of another base tip

SYNOPSIS
        git rebase
                                                 [<upstream> [<branch>]]

In the example command below, <upstream> is master and <branch> is topic.


        If <branch> is specified, git rebase will perform an automatic git switch <branch> before doing anything else.
        Otherwise it remains on the current branch.

Current branch is now <branch>=topic.

        If <upstream> is not specified ... (irrelevant)


        All changes made by commits in the current branch (=topic) but that are not in <=upstream> (master) are saved to a temporary area.

        The current branch is reset to <upstream>,

Current branch is now <upstream>=master.

        The commits that were previously saved into the temporary area are then reapplied to the current branch (master), one by
        one, in order.

I.e., master is changed, topic is not.


        Assume the following history exists and the current branch is "topic":

                      A---B---C topic
                     /
                D---E---F---G master

        From this point, the result of either of the following commands:


            git rebase master topic

        would be:

                              A'--B'--C' topic
                             /
                D---E---F---G master

But this diagram shows topic changed, master not.

Re: Contradictory git help rebase

[Nico Williams]

On Mon, Jul 21, 2025 at 02:57:37PM -0500, Rodney Bates wrote:
> The text and an example in the output of git help rebase seem to contradict about
> which branch gets changed by git rebase master topic.  Here is an edited version
> of the output, with irrelevant stuff omitted and relationships made specific.
> 
> NAME
>        git-rebase - Reapply commits on top of another base tip
> 
> SYNOPSIS
>        git rebase
>                                                 [<upstream> [<branch>]]
> 
> In the example command below, <upstream> is master and <branch> is topic.
> 
> 
>        If <branch> is specified, git rebase will perform an automatic git switch <branch> before doing anything else.
>        Otherwise it remains on the current branch.
> 
> Current branch is now <branch>=topic.
> 
>        If <upstream> is not specified ... (irrelevant)
> 
> 
>        All changes made by commits in the current branch (=topic) but that are not in <=upstream> (master) are saved to a temporary area.
> 
>        The current branch is reset to <upstream>,
> 
> Current branch is now <upstream>=master.

No, that's not correct.  "The current branch is reset to <upstream>"
means that the current branch's head commit is reset to the same as
<upstream>'s.  That's what resetting a branch means: it means changing
the commit that the branch points to.

You misinterpreted "[t]he current branch is reset to <upstream>" to mean
"the current workspace's branch is changed to be <upstream>", but this
is wrong.

"Reset" is confusing, so it's no surprise that it confused you.

>        The commits that were previously saved into the temporary area are then reapplied to the current branch (master), one by
>        one, in order.
> 
> I.e., master is changed, topic is not.
>
> [...]
>
> But this diagram shows topic changed, master not.

No, because you misunderstood what reset means.

Nico
--