Kaartic Sivaraam <kaartic.sivaraam@xxxxxxxxx> writes: >> 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.
