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