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

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 29, 2017, 00:10 UTC
Message-ID: <xmqqzi7654hx.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <1511877882.10193.2.camel@gmail.com>

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

Show 23 quoted lines

> Something like the following diff with additional changes to other
> places that refer to <branch>,
>
> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
> index 67d48e688..ba4a545bf 100644
> --- a/Documentation/git-rebase.txt
> +++ b/Documentation/git-rebase.txt
> @@ -9,9 +9,9 @@ SYNOPSIS
>  --------
>  [verse]
>  'git rebase' [-i | --interactive] [options] [--exec <cmd>] [--onto <newbase>]
> -       [<upstream> [<branch>]]
> +       [<upstream> [<ref>]]
>  'git rebase' [-i | --interactive] [options] [--exec <cmd>] [--onto <newbase>]
> -       --root [<branch>]
> +       --root [<ref>]
>  'git rebase' --continue | --skip | --abort | --quit | --edit-todo
>  
>  DESCRIPTION
>
>
> 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". 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).