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

[Kaartic Sivaraam <kaartic.sivaraam@gmail.com>]

On Wed, 2017-11-29 at 09:10 +0900, Junio C Hamano wrote:
> Kaartic Sivaraam <kaartic.sivaraam@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).