Re: [PATCH v2 0/3] rebase: give precise error message

On Wed, 2017-11-29 at 09:10 +0900, Junio C Hamano wrote:

Kaartic Sivaraam [off-list ref] writes:

quoted

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).