On Wed, 2017-11-29 at 09:10 +0900, Junio C Hamano wrote:
> Kaartic Sivaraam <kaartic.sivar...@gmail.com> writes:
>
> > If <ref> is the correct substitute <branch>, I could try to send a
> > patch that fixes this.
>
> I do not think the above is a good change in the first place for at
> least two reasons. By saying <ref>, the updated text says "not just
> branches but you can also give tags and remote-tracking branches".
I used <ref> as you could actually use tags, remote-tracking branches
and even "notes" (i.e.) any kind of <ref> for the <branch> part. That's
how the code for rebasing works currently (specifically the elif part),
if git show-ref --verify --quiet -- "refs/heads/$1" &&
orig_head=$(git rev-parse -q --verify "refs/heads/$1")
then
head_name="refs/heads/$1"
elif orig_head=$(git rev-parse -q --verify "$1")
then
head_name="detached HEAD"
else
die "$(eval_gettext "fatal: no such branch: \$branch_name")"
fi
Which means that you could not only do,
$ git rebase origin/next refs/remotes/origin/maint
You could even get creative and do,
$ git rebase origin/next refs/notes/$something
It just works (of course, I couldn't understand what it did)! I didn't
want to lie to the user. So, I used <ref>. So, should we just update
the <branch> part of the doc or should we update the code for 'rebase'?
I'm unsure.
> In reality, however, it can take any commit-ish, as the "no we are
> not rebasing the current checkout" form of the command is merely a
> short-hand to check it out first [*1*]. It gives appearance that
> the change is making it more broad, but not making it broad enough.
> At the same time, more than 90% of the time, people give a branch
> name there. Saying "branch-or-commit" for a short description of
> the command line (which is what synopsis section is) does not add
> that much value. The body text of the description where we refer to
> the <branch> parameter of course need to be updated to say "in
> addition, instead of a branch name, you can give a commit-ish that
> is *not* a branch name. When you do so, instead of checking out the
> branch, the HEAD is detached at that commit before the history
> leading to it is rebased."
>
> And because we have to say "it can be a non-branch commit-ish and
> here is what happens when you do so" anyway, I think the current
> synopsis as-is would be better than making it less clear and more
> scary by replacing <branch> with other things like <commit-ish> or
> [<branch> | <commit-ish>].
>
>
> [Footnote]
>
> *1* As my "log --first-parent --oneline master..pu" is a strand of
> pearls each of which is a merge of a topic branch,
>
> $ git rebase -i master pu~$n^2
>
> can be a handy way to make a trial rebase (after double checking
> the result of "git tbdiff", I may do "git checkout -B topic" to
> overwrite the original or I may discard the result of rebasing).
