diff mbox series

[v3,5/8] rebase: rename merge_base to branch_base

Message ID 00f70c9034452bd87c82fb3aea9658aec32f2ec1.1665650564.git.gitgitgadget@gmail.com (mailing list archive)
State Superseded
Headers show
Series rebase --keep-base: imply --reapply-cherry-picks and --no-fork-point | expand

Commit Message

Phillip Wood Oct. 13, 2022, 8:42 a.m. UTC
From: Phillip Wood <phillip.wood@dunelm.org.uk>

merge_base is not a very descriptive name, the variable always holds
the merge-base of 'branch' and 'onto' which is commit at the base of
the branch being rebased so rename it to branch_base.

Signed-off-by: Phillip Wood <phillip.wood@dunelm.org.uk>
---
 builtin/rebase.c | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

Comments

Ævar Arnfjörð Bjarmason Oct. 13, 2022, 7:16 p.m. UTC | #1
On Thu, Oct 13 2022, Phillip Wood via GitGitGadget wrote:

> From: Phillip Wood <phillip.wood@dunelm.org.uk>
>
> merge_base is not a very descriptive name, the variable always holds
> the merge-base of 'branch' and 'onto' which is commit at the base of
> the branch being rebased so rename it to branch_base.

To me "branch" means or has heavier implications of "named branch" than
just a merge base, and this command is perfectly happy to work on
commits disconnected from any named branch.

But more to the point, the rebase docs for --onto discuss a "merge
base", so you'd read those, and then encounter this code talking about a
"branch base", and wonder what the difference was...
Phillip Wood Oct. 17, 2022, 9:49 a.m. UTC | #2
On 13/10/2022 20:16, Ævar Arnfjörð Bjarmason wrote:
> 
> On Thu, Oct 13 2022, Phillip Wood via GitGitGadget wrote:
> 
>> From: Phillip Wood <phillip.wood@dunelm.org.uk>
>>
>> merge_base is not a very descriptive name, the variable always holds
>> the merge-base of 'branch' and 'onto' which is commit at the base of
>> the branch being rebased so rename it to branch_base.
> 
> To me "branch" means or has heavier implications of "named branch" than
> just a merge base, and this command is perfectly happy to work on
> commits disconnected from any named branch.
> > But more to the point, the rebase docs for --onto discuss a "merge
> base", so you'd read those, and then encounter this code talking about a
> "branch base", and wonder what the difference was...

Aren't the docs saying the merge base is the base of the commits (i.e. 
branch) being rebased? I don't think merge_base is a particularly 
helpful name as it doesn't tell us what it is the merge base of and 
branch_base was the best I could come up with. I see what you mean in 
the detached HEAD case, but as the command also works with named 
branches I hope it is fairly obvious what "branch_base" is in the 
detached HEAD case.

Best Wishes

Phillip
Ævar Arnfjörð Bjarmason Oct. 17, 2022, 11:27 a.m. UTC | #3
On Mon, Oct 17 2022, Phillip Wood wrote:

> On 13/10/2022 20:16, Ævar Arnfjörð Bjarmason wrote:
>> On Thu, Oct 13 2022, Phillip Wood via GitGitGadget wrote:
>> 
>>> From: Phillip Wood <phillip.wood@dunelm.org.uk>
>>>
>>> merge_base is not a very descriptive name, the variable always holds
>>> the merge-base of 'branch' and 'onto' which is commit at the base of
>>> the branch being rebased so rename it to branch_base.
>> To me "branch" means or has heavier implications of "named branch"
>> than
>> just a merge base, and this command is perfectly happy to work on
>> commits disconnected from any named branch.
>> > But more to the point, the rebase docs for --onto discuss a "merge
>> base", so you'd read those, and then encounter this code talking about a
>> "branch base", and wonder what the difference was...
>
> Aren't the docs saying the merge base is the base of the commits
> (i.e. branch) being rebased? I don't think merge_base is a
> particularly helpful name as it doesn't tell us what it is the merge
> base of and branch_base was the best I could come up with. I see what
> you mean in the detached HEAD case, but as the command also works with
> named branches I hope it is fairly obvious what "branch_base" is in
> the detached HEAD case.

It *optionally* works with a <branch>, but doesn't require one. E.g. try
this on git.git:

	git checkout origin/next
	touch f && git add f && git commit -m"file"
	git rebase --onto origin/master^{} HEAD~

Here we transplant a commit on top of "next" to "master", without either
of those *names* being involved, or their branches, just the
corresponding OIDs/tips.

That will go through e.g. can_fast_forward() which you're modifying
here, and now populate a "branch_base" variable, instead of a
"merge_base".

I know that we conflate the meaning of "branch" somewhat, even in our
own docs. E.g. we sometimes use "branch" and "named branch", but usually
by "branch" we mean "named branch", and otherwise talk about a detached
HEAD, <commit> or "tip".

But in this case it's especially confusing in the post-image, because
"git rebase --onto" explicitly uses an optional "<branch>" to
distinguish the "named branch" case from the case where we're operating
on detached a HEAD, or otherwise don't care about the "<branch>" (except
as generic "restore us to where we were" behavior).

So, if anything I'd think that we'd want something like this in various
places in git-rebase.txt to make the distinction clearer:
	
	diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
	index 9cb8931c7ac..e4700a6e777 100644
	--- a/Documentation/git-rebase.txt
	+++ b/Documentation/git-rebase.txt
	@@ -18,7 +18,7 @@ DESCRIPTION
	 -----------
	 If `<branch>` is specified, `git rebase` will perform an automatic
	 `git switch <branch>` before doing anything else.  Otherwise
	-it remains on the current branch.
	+it remains on the current tip or named branch.
	 
	 If `<upstream>` is not specified, the upstream configured in
	 `branch.<name>.remote` and `branch.<name>.merge` options will be used (see

But your post-image seems to be to make this sort of thing explicitly
more confusing, and e.g. these parts:

	@@ -206,8 +206,8 @@ OPTIONS
	 --onto <newbase>::
	 	Starting point at which to create the new commits. If the
	 	`--onto` option is not specified, the starting point is
	-	`<upstream>`.  May be any valid commit, and not just an
	-	existing branch name.
	+	`<upstream>`.  May be any valid commit, and not just an <-- this
	+	existing branch name. <--- this
	 +
	 As a special case, you may use "A\...B" as a shortcut for the
	 merge base of A and B if there is exactly one merge base. You can

To sum up why I find this confusing: Reading this from the docs onwards
I'd think (as is the case) that "<branch>" is optional. Then when I read
the code I'd think a "branch_base" is something that *only* had to do
with the "<branch>" case.

But that's not the case, it's just a generic "merge base" in the same
sense that "git merge-base" accepts all of these

	$ git merge-base origin/master origin/next
	d420dda0576340909c3faff364cfbd1485f70376

(These two are equivalent, just demo'ing that we don't need the peel
syntax):

	$ git merge-base $(git rev-parse origin/master) $(git rev-parse origin/next)
	d420dda0576340909c3faff364cfbd1485f70376
	$ git merge-base origin/master^{} origin/next^{}
	d420dda0576340909c3faff364cfbd1485f70376

What *would* make things much clearer is e.g. calling a variable
"branch_merge_base" *if* there is a case where that's a merge base only
for named branches, but I don't know (and didn't look carefully enough)
if you've got such a case or cases here. It just seems like a generic
"merge-base".
Phillip Wood Oct. 17, 2022, 1:13 p.m. UTC | #4
On 17/10/2022 12:27, Ævar Arnfjörð Bjarmason wrote:
> 
> On Mon, Oct 17 2022, Phillip Wood wrote:
> 
>> On 13/10/2022 20:16, Ævar Arnfjörð Bjarmason wrote:
>>> On Thu, Oct 13 2022, Phillip Wood via GitGitGadget wrote:
>>>
>>>> From: Phillip Wood <phillip.wood@dunelm.org.uk>
>>>>
>>>> merge_base is not a very descriptive name, the variable always holds
>>>> the merge-base of 'branch' and 'onto' which is commit at the base of
>>>> the branch being rebased so rename it to branch_base.
>>> To me "branch" means or has heavier implications of "named branch"
>>> than
>>> just a merge base, and this command is perfectly happy to work on
>>> commits disconnected from any named branch.
>>>> But more to the point, the rebase docs for --onto discuss a "merge
>>> base", so you'd read those, and then encounter this code talking about a
>>> "branch base", and wonder what the difference was...
>>
>> Aren't the docs saying the merge base is the base of the commits
>> (i.e. branch) being rebased? I don't think merge_base is a
>> particularly helpful name as it doesn't tell us what it is the merge
>> base of and branch_base was the best I could come up with. I see what
>> you mean in the detached HEAD case, but as the command also works with
>> named branches I hope it is fairly obvious what "branch_base" is in
>> the detached HEAD case.
> 
> It *optionally* works with a <branch>, but doesn't require one. E.g. try
> this on git.git:

Maybe I wasn't clear, I was referring to the fact that if HEAD isn't 
detached then it rebases the current branch not about the optional 
<branch> argument. I also think that the docs are for users, they are 
not a guide to the code. With this change if you search for merge_base 
in builtin/rebase.c you still find the part where we calculate the merge 
base. This commit was added in response to a review comment from Junio 
on V1, as far as I know he is happy with it and at this stage I'm 
disinclined to change it.

Best Wishes

Phillip

> 	git checkout origin/next
> 	touch f && git add f && git commit -m"file"
> 	git rebase --onto origin/master^{} HEAD~
> 
> Here we transplant a commit on top of "next" to "master", without either
> of those *names* being involved, or their branches, just the
> corresponding OIDs/tips.
> 
> That will go through e.g. can_fast_forward() which you're modifying
> here, and now populate a "branch_base" variable, instead of a
> "merge_base".
> 
> I know that we conflate the meaning of "branch" somewhat, even in our
> own docs. E.g. we sometimes use "branch" and "named branch", but usually
> by "branch" we mean "named branch", and otherwise talk about a detached
> HEAD, <commit> or "tip".
> 
> But in this case it's especially confusing in the post-image, because
> "git rebase --onto" explicitly uses an optional "<branch>" to
> distinguish the "named branch" case from the case where we're operating
> on detached a HEAD, or otherwise don't care about the "<branch>" (except
> as generic "restore us to where we were" behavior).
> 
> So, if anything I'd think that we'd want something like this in various
> places in git-rebase.txt to make the distinction clearer:
> 	
> 	diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
> 	index 9cb8931c7ac..e4700a6e777 100644
> 	--- a/Documentation/git-rebase.txt
> 	+++ b/Documentation/git-rebase.txt
> 	@@ -18,7 +18,7 @@ DESCRIPTION
> 	 -----------
> 	 If `<branch>` is specified, `git rebase` will perform an automatic
> 	 `git switch <branch>` before doing anything else.  Otherwise
> 	-it remains on the current branch.
> 	+it remains on the current tip or named branch.
> 	
> 	 If `<upstream>` is not specified, the upstream configured in
> 	 `branch.<name>.remote` and `branch.<name>.merge` options will be used (see
> 
> But your post-image seems to be to make this sort of thing explicitly
> more confusing, and e.g. these parts:
> 
> 	@@ -206,8 +206,8 @@ OPTIONS
> 	 --onto <newbase>::
> 	 	Starting point at which to create the new commits. If the
> 	 	`--onto` option is not specified, the starting point is
> 	-	`<upstream>`.  May be any valid commit, and not just an
> 	-	existing branch name.
> 	+	`<upstream>`.  May be any valid commit, and not just an <-- this
> 	+	existing branch name. <--- this
> 	 +
> 	 As a special case, you may use "A\...B" as a shortcut for the
> 	 merge base of A and B if there is exactly one merge base. You can
> 
> To sum up why I find this confusing: Reading this from the docs onwards
> I'd think (as is the case) that "<branch>" is optional. Then when I read
> the code I'd think a "branch_base" is something that *only* had to do
> with the "<branch>" case.
> 
> But that's not the case, it's just a generic "merge base" in the same
> sense that "git merge-base" accepts all of these
> 
> 	$ git merge-base origin/master origin/next
> 	d420dda0576340909c3faff364cfbd1485f70376
> 
> (These two are equivalent, just demo'ing that we don't need the peel
> syntax):
> 
> 	$ git merge-base $(git rev-parse origin/master) $(git rev-parse origin/next)
> 	d420dda0576340909c3faff364cfbd1485f70376
> 	$ git merge-base origin/master^{} origin/next^{}
> 	d420dda0576340909c3faff364cfbd1485f70376
> 
> What *would* make things much clearer is e.g. calling a variable
> "branch_merge_base" *if* there is a case where that's a merge base only
> for named branches, but I don't know (and didn't look carefully enough)
> if you've got such a case or cases here. It just seems like a generic
> "merge-base".
> 
>
Ævar Arnfjörð Bjarmason Oct. 17, 2022, 4:19 p.m. UTC | #5
On Mon, Oct 17 2022, Phillip Wood wrote:

> On 17/10/2022 12:27, Ævar Arnfjörð Bjarmason wrote:
>> On Mon, Oct 17 2022, Phillip Wood wrote:
>> 
>>> On 13/10/2022 20:16, Ævar Arnfjörð Bjarmason wrote:
>>>> On Thu, Oct 13 2022, Phillip Wood via GitGitGadget wrote:
>>>>
>>>>> From: Phillip Wood <phillip.wood@dunelm.org.uk>
>>>>>
>>>>> merge_base is not a very descriptive name, the variable always holds
>>>>> the merge-base of 'branch' and 'onto' which is commit at the base of
>>>>> the branch being rebased so rename it to branch_base.
>>>> To me "branch" means or has heavier implications of "named branch"
>>>> than
>>>> just a merge base, and this command is perfectly happy to work on
>>>> commits disconnected from any named branch.
>>>>> But more to the point, the rebase docs for --onto discuss a "merge
>>>> base", so you'd read those, and then encounter this code talking about a
>>>> "branch base", and wonder what the difference was...
>>>
>>> Aren't the docs saying the merge base is the base of the commits
>>> (i.e. branch) being rebased? I don't think merge_base is a
>>> particularly helpful name as it doesn't tell us what it is the merge
>>> base of and branch_base was the best I could come up with. I see what
>>> you mean in the detached HEAD case, but as the command also works with
>>> named branches I hope it is fairly obvious what "branch_base" is in
>>> the detached HEAD case.
>> It *optionally* works with a <branch>, but doesn't require
>> one. E.g. try
>> this on git.git:
>
> Maybe I wasn't clear, I was referring to the fact that if HEAD isn't
> detached then it rebases the current branch not about the optional 
> <branch> argument. I also think that the docs are for users, they are
> not a guide to the code. With this change if you search for merge_base 
> in builtin/rebase.c you still find the part where we calculate the
> merge base. This commit was added in response to a review comment from
> Junio on V1, as far as I know he is happy with it and at this stage
> I'm disinclined to change it.

I was mainly fishing for whether *you* grokked that it wasn't always a
"merge base of a branch" in suggesting the rename. If you do & would
like to keep this it's fine by me.

Having said that.

I hadn't read the original discussion (or maybe I did, and
forgot). Re-reading you're referring to the discussion ending at[1].

I think using "base commit" in this case (your other suggestion) would
be better than either "merge base" or "branch base", just my 0.02.

In that case we could also use it consistently in our docs, and mention
that (in some cases) it's the "merge base", and in others something we
manually provide.

I agree that the docs are "not a guide to the code", and should not be
required to keep the two in sync at all times.

But just do be clear I do think it's a strong signal that the code is
being made more confusing if the variable that holds the "merge base"
now (as discussed in those terms in the docs) is named "branch base",
and we're seemingly unable (or at least I wasn't) to come up with a
corresponding doc change that doesn't start sounding self-contradictory.

I.e. given that the whole point of 5/8 is to come up with a more
descriptive name:

	merge_base is not a very descriptive name, the variable always holds
	the merge-base of 'branch' and 'onto' which is commit at the base of
	the branch being rebased so rename it to branch_base.

Cheers.

1. https://lore.kernel.org/git/c5b01472-7da9-6051-b127-1a8b8ddd2944@gmail.com/

>> 	git checkout origin/next
>> 	touch f && git add f && git commit -m"file"
>> 	git rebase --onto origin/master^{} HEAD~
>> Here we transplant a commit on top of "next" to "master", without
>> either
>> of those *names* being involved, or their branches, just the
>> corresponding OIDs/tips.
>> That will go through e.g. can_fast_forward() which you're modifying
>> here, and now populate a "branch_base" variable, instead of a
>> "merge_base".
>> I know that we conflate the meaning of "branch" somewhat, even in
>> our
>> own docs. E.g. we sometimes use "branch" and "named branch", but usually
>> by "branch" we mean "named branch", and otherwise talk about a detached
>> HEAD, <commit> or "tip".
>> But in this case it's especially confusing in the post-image,
>> because
>> "git rebase --onto" explicitly uses an optional "<branch>" to
>> distinguish the "named branch" case from the case where we're operating
>> on detached a HEAD, or otherwise don't care about the "<branch>" (except
>> as generic "restore us to where we were" behavior).
>> So, if anything I'd think that we'd want something like this in
>> various
>> places in git-rebase.txt to make the distinction clearer:
>> 	
>> 	diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
>> 	index 9cb8931c7ac..e4700a6e777 100644
>> 	--- a/Documentation/git-rebase.txt
>> 	+++ b/Documentation/git-rebase.txt
>> 	@@ -18,7 +18,7 @@ DESCRIPTION
>> 	 -----------
>> 	 If `<branch>` is specified, `git rebase` will perform an automatic
>> 	 `git switch <branch>` before doing anything else.  Otherwise
>> 	-it remains on the current branch.
>> 	+it remains on the current tip or named branch.
>> 	
>> 	 If `<upstream>` is not specified, the upstream configured in
>> 	 `branch.<name>.remote` and `branch.<name>.merge` options will be used (see
>> But your post-image seems to be to make this sort of thing
>> explicitly
>> more confusing, and e.g. these parts:
>> 	@@ -206,8 +206,8 @@ OPTIONS
>> 	 --onto <newbase>::
>> 	 	Starting point at which to create the new commits. If the
>> 	 	`--onto` option is not specified, the starting point is
>> 	-	`<upstream>`.  May be any valid commit, and not just an
>> 	-	existing branch name.
>> 	+	`<upstream>`.  May be any valid commit, and not just an <-- this
>> 	+	existing branch name. <--- this
>> 	 +
>> 	 As a special case, you may use "A\...B" as a shortcut for the
>> 	 merge base of A and B if there is exactly one merge base. You can
>> To sum up why I find this confusing: Reading this from the docs
>> onwards
>> I'd think (as is the case) that "<branch>" is optional. Then when I read
>> the code I'd think a "branch_base" is something that *only* had to do
>> with the "<branch>" case.
>> But that's not the case, it's just a generic "merge base" in the
>> same
>> sense that "git merge-base" accepts all of these
>> 	$ git merge-base origin/master origin/next
>> 	d420dda0576340909c3faff364cfbd1485f70376
>> (These two are equivalent, just demo'ing that we don't need the peel
>> syntax):
>> 	$ git merge-base $(git rev-parse origin/master) $(git
>> rev-parse origin/next)
>> 	d420dda0576340909c3faff364cfbd1485f70376
>> 	$ git merge-base origin/master^{} origin/next^{}
>> 	d420dda0576340909c3faff364cfbd1485f70376
>> What *would* make things much clearer is e.g. calling a variable
>> "branch_merge_base" *if* there is a case where that's a merge base only
>> for named branches, but I don't know (and didn't look carefully enough)
>> if you've got such a case or cases here. It just seems like a generic
>> "merge-base".
>>
Phillip Wood Oct. 19, 2022, 3:35 p.m. UTC | #6
On 17/10/2022 17:19, Ævar Arnfjörð Bjarmason wrote:
> 
> On Mon, Oct 17 2022, Phillip Wood wrote:
> 
>> On 17/10/2022 12:27, Ævar Arnfjörð Bjarmason wrote:
>>> On Mon, Oct 17 2022, Phillip Wood wrote:
>>>
>>>> On 13/10/2022 20:16, Ævar Arnfjörð Bjarmason wrote:
>>>>> On Thu, Oct 13 2022, Phillip Wood via GitGitGadget wrote:
>>>>>
>>>>>> From: Phillip Wood <phillip.wood@dunelm.org.uk>
>>>>>>
>>>>>> merge_base is not a very descriptive name, the variable always holds
>>>>>> the merge-base of 'branch' and 'onto' which is commit at the base of
>>>>>> the branch being rebased so rename it to branch_base.
>>>>> To me "branch" means or has heavier implications of "named branch"
>>>>> than
>>>>> just a merge base, and this command is perfectly happy to work on
>>>>> commits disconnected from any named branch.
>>>>>> But more to the point, the rebase docs for --onto discuss a "merge
>>>>> base", so you'd read those, and then encounter this code talking about a
>>>>> "branch base", and wonder what the difference was...
>>>>
>>>> Aren't the docs saying the merge base is the base of the commits
>>>> (i.e. branch) being rebased? I don't think merge_base is a
>>>> particularly helpful name as it doesn't tell us what it is the merge
>>>> base of and branch_base was the best I could come up with. I see what
>>>> you mean in the detached HEAD case, but as the command also works with
>>>> named branches I hope it is fairly obvious what "branch_base" is in
>>>> the detached HEAD case.
>>> It *optionally* works with a <branch>, but doesn't require
>>> one. E.g. try
>>> this on git.git:
>>
>> Maybe I wasn't clear, I was referring to the fact that if HEAD isn't
>> detached then it rebases the current branch not about the optional
>> <branch> argument. I also think that the docs are for users, they are
>> not a guide to the code. With this change if you search for merge_base
>> in builtin/rebase.c you still find the part where we calculate the
>> merge base. This commit was added in response to a review comment from
>> Junio on V1, as far as I know he is happy with it and at this stage
>> I'm disinclined to change it.
> 
> I was mainly fishing for whether *you* grokked that it wasn't always a
> "merge base of a branch" in suggesting the rename. If you do & would
> like to keep this it's fine by me.

Thanks, maybe base_commit would have been clearer but I'm not sure I can 
face re-rolling just for that.

Best Wishes

Phillip

> Having said that.
> 
> I hadn't read the original discussion (or maybe I did, and
> forgot). Re-reading you're referring to the discussion ending at[1].
> 
> I think using "base commit" in this case (your other suggestion) would
> be better than either "merge base" or "branch base", just my 0.02.
> 
> In that case we could also use it consistently in our docs, and mention
> that (in some cases) it's the "merge base", and in others something we
> manually provide.
> 
> I agree that the docs are "not a guide to the code", and should not be
> required to keep the two in sync at all times.
> 
> But just do be clear I do think it's a strong signal that the code is
> being made more confusing if the variable that holds the "merge base"
> now (as discussed in those terms in the docs) is named "branch base",
> and we're seemingly unable (or at least I wasn't) to come up with a
> corresponding doc change that doesn't start sounding self-contradictory.
> 
> I.e. given that the whole point of 5/8 is to come up with a more
> descriptive name:
> 
> 	merge_base is not a very descriptive name, the variable always holds
> 	the merge-base of 'branch' and 'onto' which is commit at the base of
> 	the branch being rebased so rename it to branch_base.
> 
> Cheers.
> 
> 1. https://lore.kernel.org/git/c5b01472-7da9-6051-b127-1a8b8ddd2944@gmail.com/
> 
>>> 	git checkout origin/next
>>> 	touch f && git add f && git commit -m"file"
>>> 	git rebase --onto origin/master^{} HEAD~
>>> Here we transplant a commit on top of "next" to "master", without
>>> either
>>> of those *names* being involved, or their branches, just the
>>> corresponding OIDs/tips.
>>> That will go through e.g. can_fast_forward() which you're modifying
>>> here, and now populate a "branch_base" variable, instead of a
>>> "merge_base".
>>> I know that we conflate the meaning of "branch" somewhat, even in
>>> our
>>> own docs. E.g. we sometimes use "branch" and "named branch", but usually
>>> by "branch" we mean "named branch", and otherwise talk about a detached
>>> HEAD, <commit> or "tip".
>>> But in this case it's especially confusing in the post-image,
>>> because
>>> "git rebase --onto" explicitly uses an optional "<branch>" to
>>> distinguish the "named branch" case from the case where we're operating
>>> on detached a HEAD, or otherwise don't care about the "<branch>" (except
>>> as generic "restore us to where we were" behavior).
>>> So, if anything I'd think that we'd want something like this in
>>> various
>>> places in git-rebase.txt to make the distinction clearer:
>>> 	
>>> 	diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
>>> 	index 9cb8931c7ac..e4700a6e777 100644
>>> 	--- a/Documentation/git-rebase.txt
>>> 	+++ b/Documentation/git-rebase.txt
>>> 	@@ -18,7 +18,7 @@ DESCRIPTION
>>> 	 -----------
>>> 	 If `<branch>` is specified, `git rebase` will perform an automatic
>>> 	 `git switch <branch>` before doing anything else.  Otherwise
>>> 	-it remains on the current branch.
>>> 	+it remains on the current tip or named branch.
>>> 	
>>> 	 If `<upstream>` is not specified, the upstream configured in
>>> 	 `branch.<name>.remote` and `branch.<name>.merge` options will be used (see
>>> But your post-image seems to be to make this sort of thing
>>> explicitly
>>> more confusing, and e.g. these parts:
>>> 	@@ -206,8 +206,8 @@ OPTIONS
>>> 	 --onto <newbase>::
>>> 	 	Starting point at which to create the new commits. If the
>>> 	 	`--onto` option is not specified, the starting point is
>>> 	-	`<upstream>`.  May be any valid commit, and not just an
>>> 	-	existing branch name.
>>> 	+	`<upstream>`.  May be any valid commit, and not just an <-- this
>>> 	+	existing branch name. <--- this
>>> 	 +
>>> 	 As a special case, you may use "A\...B" as a shortcut for the
>>> 	 merge base of A and B if there is exactly one merge base. You can
>>> To sum up why I find this confusing: Reading this from the docs
>>> onwards
>>> I'd think (as is the case) that "<branch>" is optional. Then when I read
>>> the code I'd think a "branch_base" is something that *only* had to do
>>> with the "<branch>" case.
>>> But that's not the case, it's just a generic "merge base" in the
>>> same
>>> sense that "git merge-base" accepts all of these
>>> 	$ git merge-base origin/master origin/next
>>> 	d420dda0576340909c3faff364cfbd1485f70376
>>> (These two are equivalent, just demo'ing that we don't need the peel
>>> syntax):
>>> 	$ git merge-base $(git rev-parse origin/master) $(git
>>> rev-parse origin/next)
>>> 	d420dda0576340909c3faff364cfbd1485f70376
>>> 	$ git merge-base origin/master^{} origin/next^{}
>>> 	d420dda0576340909c3faff364cfbd1485f70376
>>> What *would* make things much clearer is e.g. calling a variable
>>> "branch_merge_base" *if* there is a case where that's a merge base only
>>> for named branches, but I don't know (and didn't look carefully enough)
>>> if you've got such a case or cases here. It just seems like a generic
>>> "merge-base".
>>>
>
diff mbox series

Patch

diff --git a/builtin/rebase.c b/builtin/rebase.c
index 7e6ce374c59..cbafcc41e75 100644
--- a/builtin/rebase.c
+++ b/builtin/rebase.c
@@ -866,22 +866,22 @@  static int is_linear_history(struct commit *from, struct commit *to)
 
 static int can_fast_forward(struct commit *onto, struct commit *upstream,
 			    struct commit *restrict_revision,
-			    struct commit *head, struct object_id *merge_base)
+			    struct commit *head, struct object_id *branch_base)
 {
 	struct commit_list *merge_bases = NULL;
 	int res = 0;
 
 	merge_bases = get_merge_bases(onto, head);
 	if (!merge_bases || merge_bases->next) {
-		oidcpy(merge_base, null_oid());
+		oidcpy(branch_base, null_oid());
 		goto done;
 	}
 
-	oidcpy(merge_base, &merge_bases->item->object.oid);
-	if (!oideq(merge_base, &onto->object.oid))
+	oidcpy(branch_base, &merge_bases->item->object.oid);
+	if (!oideq(branch_base, &onto->object.oid))
 		goto done;
 
-	if (restrict_revision && !oideq(&restrict_revision->object.oid, merge_base))
+	if (restrict_revision && !oideq(&restrict_revision->object.oid, branch_base))
 		goto done;
 
 	if (!upstream)
@@ -1035,7 +1035,7 @@  int cmd_rebase(int argc, const char **argv, const char *prefix)
 	struct strbuf msg = STRBUF_INIT;
 	struct strbuf revisions = STRBUF_INIT;
 	struct strbuf buf = STRBUF_INIT;
-	struct object_id merge_base;
+	struct object_id branch_base;
 	int ignore_whitespace = 0;
 	enum action action = ACTION_NONE;
 	const char *gpg_sign = NULL;
@@ -1653,7 +1653,7 @@  int cmd_rebase(int argc, const char **argv, const char *prefix)
 	} else if (!options.onto_name)
 		options.onto_name = options.upstream_name;
 	if (strstr(options.onto_name, "...")) {
-		if (get_oid_mb(options.onto_name, &merge_base) < 0) {
+		if (get_oid_mb(options.onto_name, &branch_base) < 0) {
 			if (keep_base)
 				die(_("'%s': need exactly one merge base with branch"),
 				    options.upstream_name);
@@ -1661,7 +1661,7 @@  int cmd_rebase(int argc, const char **argv, const char *prefix)
 				die(_("'%s': need exactly one merge base"),
 				    options.onto_name);
 		}
-		options.onto = lookup_commit_or_die(&merge_base,
+		options.onto = lookup_commit_or_die(&branch_base,
 						    options.onto_name);
 	} else {
 		options.onto =
@@ -1699,11 +1699,11 @@  int cmd_rebase(int argc, const char **argv, const char *prefix)
 	 * in which case we could fast-forward without replacing the commits
 	 * with new commits recreated by replaying their changes.
 	 *
-	 * Note that can_fast_forward() initializes merge_base, so we have to
+	 * Note that can_fast_forward() initializes branch_base, so we have to
 	 * call it before checking allow_preemptive_ff.
 	 */
 	if (can_fast_forward(options.onto, options.upstream, options.restrict_revision,
-		    options.orig_head, &merge_base) &&
+		    options.orig_head, &branch_base) &&
 	    allow_preemptive_ff) {
 		int flag;
 
@@ -1745,12 +1745,12 @@  int cmd_rebase(int argc, const char **argv, const char *prefix)
 		struct diff_options opts;
 
 		if (options.flags & REBASE_VERBOSE) {
-			if (is_null_oid(&merge_base))
+			if (is_null_oid(&branch_base))
 				printf(_("Changes to %s:\n"),
 				       oid_to_hex(&options.onto->object.oid));
 			else
 				printf(_("Changes from %s to %s:\n"),
-				       oid_to_hex(&merge_base),
+				       oid_to_hex(&branch_base),
 				       oid_to_hex(&options.onto->object.oid));
 		}
 
@@ -1762,8 +1762,8 @@  int cmd_rebase(int argc, const char **argv, const char *prefix)
 			DIFF_FORMAT_SUMMARY | DIFF_FORMAT_DIFFSTAT;
 		opts.detect_rename = DIFF_DETECT_RENAME;
 		diff_setup_done(&opts);
-		diff_tree_oid(is_null_oid(&merge_base) ?
-			      the_hash_algo->empty_tree : &merge_base,
+		diff_tree_oid(is_null_oid(&branch_base) ?
+			      the_hash_algo->empty_tree : &branch_base,
 			      &options.onto->object.oid, "", &opts);
 		diffcore_std(&opts);
 		diff_flush(&opts);
@@ -1794,7 +1794,7 @@  int cmd_rebase(int argc, const char **argv, const char *prefix)
 	 * we just fast-forwarded.
 	 */
 	strbuf_reset(&msg);
-	if (oideq(&merge_base, &options.orig_head->object.oid)) {
+	if (oideq(&branch_base, &options.orig_head->object.oid)) {
 		printf(_("Fast-forwarded %s to %s.\n"),
 			branch_name, options.onto_name);
 		strbuf_addf(&msg, "rebase finished: %s onto %s",