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

Kaartic Sivaraam [off-list ref] writes:

quoted

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

By saying <ref>, you are not covering these cases

	git rebase master HEAD^0
	git rebase master pu^2

where the command gets non refs.

Most of the time, people use a <branch>, and rare cases like these
what a user can give is not restricted to a <ref>, so there is *no*
value in replacing <branch> with <ref>.  If we needed to replace it
with something, replacing <branch> with [<branch> | <commit-ish>] is
not wrong per-se, but I do not think it is an improvement.

As <branch> is merely a kind of <commit-ish>, it may be tempting to
instead replace <branch> with <commit-ish>, but I do not think it is
a good idea, either.  No matter what you write there in the synopsis
(and let's call it X), the description would have to say "when X is
the name of a branch, that branch is checked out, its history gets
rebased, and at the end, the tip of that branch points at the
result.  When X is not a branch but just a commit-ish, the HEAD is
detached at that commit, its history gets rebased and you'll be left
in that state".  Having <branch> in that sentence is clear enough
and any intelligent reader would understand what we mean by that
notation: we are showing there can be various things that can come
on the command line depicted in the SYNOPSIS section at the point
where we have a placeholder called <branch>, and the argument does
not necessarily have to be the name of a branch.