bzr <cmd> help -- Synopsis syntax should follow de facto conventions

Jari Aalto jari.aalto at
Wed Sep 20 12:25:21 BST 2006

Please take a moment to review all help texts to next release. Take
for an example:

    $ bzr help checkout
    usage: bzr checkout [BRANCH_LOCATION] [TO_LOCATION]
    aliases: co

    Create a new checkout of an existing branch.

    If BRANCH_LOCATION is omitted, checkout will reconstitute a working tree for
    the branch found in '.'. This is useful if you have removed the working tree
    or if it was never created - i.e. if you pushed the branch to its current
    location using SFTP.

While the text explains it, the Synopsis reads:

    usage: bzr checkout [BRANCH_LOCATION] [TO_LOCATION]

which would suggest that both parameters are optional. In Unix manul
page parlance (de facto) it is customary to use syntax:


So I'd write the above like:

    usage: bzr checkout <BRANCH_LOCATION> [TO_LOCATION]

Or by using {BRANCH_LOCATION} if that is more to one's style.


More information about the bazaar mailing list