From: Junio C Hamano <gitster@pobox.com>
Date: Wed, 29 Nov 2017 06:47:03 GMT
Subject: Re: [PATCH v2 0/3] rebase: give precise error message
Message-ID: <xmqqshcx4m54.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <1511925118.2486.2.camel@gmail.com>

Kaartic Sivaraam <kaartic.sivaraam@gmail.com> writes:

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