Package: git Version: 1:1.7.2.5-3 Severity: minor Nearly all of the examples in git-rebase(1) supply the second positional argument `branch'. This is unhelpful because specifying `branch' is not usually what is wanted.
I think this is probably because the examples were intended not as recipes for users to adapt, but as illustrations of git rebase's behaviour - and the railway diagrams are slightly easier if they can be written without regard to the question of what the current branch is. But IMO this is unhelpful because examples in manpages are mostly used by people as recipes, rather than illustrations. Particularly, examples found in manpages like git-rebase(1). I have just encountered a user who got into trouble because they used the examples as recipes, and when adapting them substituted `HEAD' for the 2nd positional parameter to avoid having to write out the name of the current branch. (Of course this left them with a detached HEAD, leaving what was their current branch unrewritten.) I would propose the following changes to the manpage: * In each example railway diagram, mark the current branch (eg with * like `git branch') does. * Whenever a single rune is given with two positional arguments, put the second one in [ ] to indicate that it is optional. If this is likely to meet with approval I will prepare a patch. Thanks, Ian. -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org
