Kaartic Sivaraam <kaartic.sivar...@gmail.com> writes:
> 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).
