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

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 29, 2017, 06:47 UTC
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:

Show 11 quoted lines

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