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@xxxxxxxxxxxxx>
>>>
>>> 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".
