On Sun, Oct 24, 2010 at 11:51 AM, Štěpán Němec [off-list ref] wrote:

Provide a few examples on argument and option notation in usage strings
and command synopses.

I think this is a great idea.

+ Specific number of occurences is indicated as follows:
+   <commit>{0,2}
+   (Up to two <commit>s.)

I suggest removing this notation - it is confusing and is only used by
git-diff.txt and git-difftool.txt.  We already have notation to serve
this purpose:

    [<commit> [<commit>]]

+ Parentheses are used for grouping, often combined with vertical bar
+ to indicate alternatives:
+   [(<rev>|<range>)...]
+   (Any number of either <rev> or <range>.  Parens are needed to make
+   it clear that "..." pertains to both <rev> and <range>.)

You could also mention that parentheses are not needed if square
brackets will do:
    [-q | --quiet]

Also, should there be a standard for spacing and for whether the short
or the long option comes first?

git-add.txt:
    [--patch | -p]
git-commit.txt:
    [-a | --interactive]
git-stash.txt:
    [-q|--quiet]

Otherwise, I think this patch looks good.