{"thread":{"id":"25387","subject":"[PATCH/RFC] Unify argument and option notation in the docs","startedAt":"2010-10-08T00:52:56Z","lastAt":"2010-11-05T01:57:16Z","messageCount":43,"participants":["Štěpán Němec","Jonathan Nieder","Junio C Hamano","Mark Lodato","Sverre Rabbelier","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"152941","messageId":"20101008005256.GA21738@headley","threadId":"25387","inReplyTo":null,"subject":"[PATCH/RFC] Unify argument and option notation in the docs","fromName":"Štěpán Němec","fromEmail":"stepnem@gmail.com","sentAt":"2010-10-08T00:52:56Z","receivedAt":"2010-10-08T00:52:56Z","isPatch":true,"sender":{"key":"stepnem@gmail.com","avatar":"https://avatars.githubusercontent.com/u/106838?v=4"},"body":"In general, the current usage is already pretty consistent, so it is\nnot too hard to induce the guidelines and correct the rest based on\nthem.\n\nSome examples of what this patch is based on (i.e., the current\nprevalent usage) follow (all coming from existing documentation):\n\nPlaceholders are enclosed in angle brackets:\n  <file>\n  --sort=<key>\n  --abbrev[=<n>]\n\nPossibility of multiple occurences is indicated by three dots:\n  <file>...\n  (One or more of <file>.)\n\nOptional parts are enclosed in square brackets:\ngit-archive:\n  [<extra>]\n  (Zero or one <extra>.)\n\ngit-apply:\n  [<patch>...]\n  (Any number of <patch>. Note that the dots are inside, not outside\n  the brackets.)\n\nParentheses are used for grouping:\ngit-bisect:\n  [(<rev>|<range>)...]\n  (Any number of either <rev> or <range>. Parens are needed to make it\n  clear that `...' pertains to both <rev> and <range>.)\n\ngit-remote:\n  git remote set-head <name> (-a | -d | <branch>)\n  (One and only one of `-a', `-d' or `<branch>' _must_ (no square\n  brackets) be provided.)\n\nLimited number of occurences is indicated as follows:\ngit-diff:\n  <commit>{0,2}\n  (Up to two <commit>s.)\n---\n\n[It is conceivable I could submit this as a series of smaller patches,\nbut the problems this is solving didn't seem diverse enough to me to\nwarrant that.\n\nAs for the \"methodology\" used -- I grepped for places similar to what I\nwanted to fix (cf.\n<http://article.gmane.org/gmane.comp.version-control.git/158445>, then I\nnoticed other related problems and grepped for them etc. All the edits\nare manual, though.]\n\nTwo questions:\n\n1. Is `[--refs [--unpacked | --all]]' in `git-pack-object' documentation\ncorrect? From my reading of builtin/pack-objects.c, `--unpacked' and\n`--all' do the same thing and both imply --refs, so perhaps [--refs |\n--unpacked | --all] would make more sense? (I also noticed that the\n--reflog option is shown in the usage string but undocumented.)\n\n2. I left in one special case, namely the GIT_* variables in `git(1)'\nsynopsis section as values for the `--exec-path' and other options.\nFurther in the text the usual <path> placeholders are used and I believe\nthose should be used in the synopsis as well, but whoever used the GIT_*\nvariables obviously did it to point out that they provide an alternative\nway to set those options, so I figured I'd leave them in for now and ask\nfor opinions first.\n\n Documentation/diff-options.txt       |   14 +++++-----\n Documentation/git-am.txt             |    4 +-\n Documentation/git-apply.txt          |    6 ++--\n Documentation/git-archive.txt        |    4 +-\n Documentation/git-bundle.txt         |    6 ++--\n Documentation/git-checkout-index.txt |    2 +-\n Documentation/git-commit-tree.txt    |    2 +-\n Documentation/git-daemon.txt         |   48 +++++++++++++++++-----------------\n Documentation/git-fast-export.txt    |    2 +-\n Documentation/git-fetch.txt          |    2 +-\n Documentation/git-filter-branch.txt  |    2 +-\n Documentation/git-for-each-ref.txt   |    2 +-\n Documentation/git-index-pack.txt     |    4 +-\n Documentation/git-init.txt           |    2 +-\n Documentation/git-ls-files.txt       |    2 +-\n Documentation/git-ls-tree.txt        |   10 +++---\n Documentation/git-mailsplit.txt      |    2 +-\n Documentation/git-mergetool.txt      |    2 +-\n Documentation/git-pack-objects.txt   |   16 +++++-----\n Documentation/git-relink.txt         |    2 +-\n Documentation/git-remote.txt         |    2 +-\n Documentation/git-repack.txt         |   12 ++++----\n Documentation/git-rev-list.txt       |   18 ++++++------\n Documentation/git-rev-parse.txt      |    2 +-\n Documentation/git-shortlog.txt       |    2 +-\n Documentation/git-show-branch.txt    |    2 +-\n Documentation/git-svn.txt            |    2 +-\n Documentation/git-update-index.txt   |    4 +-\n Documentation/git-web--browse.txt    |   16 +++++-----\n Documentation/git.txt                |    6 ++--\n Documentation/merge-strategies.txt   |    2 +-\n Documentation/pretty-options.txt     |    4 +-\n Documentation/rev-list-options.txt   |   18 ++++++------\n Documentation/user-manual.txt        |    2 +-\n archive.c                            |    4 +-\n builtin/bundle.c                     |    4 +-\n builtin/checkout-index.c             |    2 +-\n builtin/commit-tree.c                |    2 +-\n builtin/fetch.c                      |    2 +-\n builtin/grep.c                       |    2 +-\n builtin/index-pack.c                 |    2 +-\n builtin/ls-files.c                   |    2 +-\n builtin/ls-tree.c                    |    2 +-\n builtin/mailsplit.c                  |    2 +-\n builtin/pack-objects.c               |   10 +++---\n builtin/remote.c                     |    2 +-\n builtin/rev-list.c                   |    8 +++---\n builtin/show-branch.c                |    2 +-\n builtin/update-index.c               |    2 +-\n daemon.c                             |   18 ++++++------\n fast-import.c                        |    2 +-\n git-am.sh                            |    2 +-\n git-relink.perl                      |    2 +-\n git.c                                |    4 +-\n upload-pack.c                        |    2 +-\n 55 files changed, 152 insertions(+), 152 deletions(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex f77a0f8..719f589 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -48,9 +48,9 @@ endif::git-format-patch[]\n --patience::\n \tGenerate a diff using the \"patience diff\" algorithm.\n \n---stat[=width[,name-width]]::\n+--stat[=<width>[,<name-width>]]::\n \tGenerate a diffstat.  You can override the default\n-\toutput width for 80-column terminal by `--stat=width`.\n+\toutput width for 80-column terminal by `--stat=<width>`.\n \tThe width of the filename part can be controlled by\n \tgiving another width to it separated by a comma.\n \n@@ -66,14 +66,14 @@ endif::git-format-patch[]\n \tnumber of modified files, as well as number of added and deleted\n \tlines.\n \n---dirstat[=limit]::\n+--dirstat[=<limit>]::\n \tOutput the distribution of relative amount of changes (number of lines added or\n \tremoved) for each sub-directory. Directories with changes below\n \ta cut-off percent (3% by default) are not shown. The cut-off percent\n-\tcan be set with `--dirstat=limit`. Changes in a child directory is not\n+\tcan be set with `--dirstat=<limit>`. Changes in a child directory are not\n \tcounted for the parent directory, unless `--cumulative` is used.\n \n---dirstat-by-file[=limit]::\n+--dirstat-by-file[=<limit>]::\n \tSame as `--dirstat`, but counts changed files instead of lines.\n \n --summary::\n@@ -248,13 +248,13 @@ endif::git-log[]\n \tIf `n` is specified, it has the same meaning as for `-M<n>`.\n \n ifndef::git-format-patch[]\n---diff-filter=[ACDMRTUXB*]::\n+--diff-filter=<spec>::\n+\t'<spec>' can be any combination of the characters `ACDMRTUXB*`.\n \tSelect only files that are Added (`A`), Copied (`C`),\n \tDeleted (`D`), Modified (`M`), Renamed (`R`), have their\n \ttype (i.e. regular file, symlink, submodule, ...) changed (`T`),\n \tare Unmerged (`U`), are\n \tUnknown (`X`), or have had their pairing Broken (`B`).\n-\tAny combination of the filter characters may be used.\n \tWhen `*` (All-or-none) is added to the combination, all\n \tpaths are selected if there is any file that matches\n \tother criteria in the comparison; if there is no file\ndiff --git a/Documentation/git-am.txt b/Documentation/git-am.txt\nindex 9e62f87..51297d0 100644\n--- a/Documentation/git-am.txt\n+++ b/Documentation/git-am.txt\n@@ -14,7 +14,7 @@ SYNOPSIS\n \t [--ignore-date] [--ignore-space-change | --ignore-whitespace]\n \t [--whitespace=<option>] [-C<n>] [-p<n>] [--directory=<dir>]\n \t [--reject] [-q | --quiet] [--scissors | --no-scissors]\n-\t [<mbox> | <Maildir>...]\n+\t [(<mbox> | <Maildir>)...]\n 'git am' (--continue | --skip | --abort)\n \n DESCRIPTION\n@@ -25,7 +25,7 @@ current branch.\n \n OPTIONS\n -------\n-<mbox>|<Maildir>...::\n+(<mbox>|<Maildir>)...::\n \tThe list of mailbox files to read patches from. If you do not\n \tsupply this argument, the command reads from the standard input.\n \tIf you supply directories, they will be treated as Maildirs.\ndiff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt\nindex 4a74b23..881652f 100644\n--- a/Documentation/git-apply.txt\n+++ b/Documentation/git-apply.txt\n@@ -12,10 +12,10 @@ SYNOPSIS\n 'git apply' [--stat] [--numstat] [--summary] [--check] [--index]\n \t  [--apply] [--no-add] [--build-fake-ancestor=<file>] [-R | --reverse]\n \t  [--allow-binary-replacement | --binary] [--reject] [-z]\n-\t  [-pNUM] [-CNUM] [--inaccurate-eof] [--recount] [--cached]\n+\t  [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached]\n \t  [--ignore-space-change | --ignore-whitespace ]\n-\t  [--whitespace=<nowarn|warn|fix|error|error-all>]\n-\t  [--exclude=PATH] [--include=PATH] [--directory=<root>]\n+\t  [--whitespace=(nowarn|warn|fix|error|error-all)]\n+\t  [--exclude=<path>] [--include=<path>] [--directory=<root>]\n \t  [--verbose] [<patch>...]\n \n DESCRIPTION\ndiff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt\nindex 8d3e666..4163a1b 100644\n--- a/Documentation/git-archive.txt\n+++ b/Documentation/git-archive.txt\n@@ -12,7 +12,7 @@ SYNOPSIS\n 'git archive' [--format=<fmt>] [--list] [--prefix=<prefix>/] [<extra>]\n \t      [-o | --output=<file>] [--worktree-attributes]\n \t      [--remote=<repo> [--exec=<git-upload-archive>]] <tree-ish>\n-\t      [path...]\n+\t      [<path>...]\n \n DESCRIPTION\n -----------\n@@ -73,7 +73,7 @@ OPTIONS\n <tree-ish>::\n \tThe tree or commit to produce an archive for.\n \n-path::\n+<path>::\n \tWithout an optional path parameter, all files and subdirectories\n \tof the current working directory are included in the archive.\n \tIf one or more paths are specified, only these are included.\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex 38e59af..6266a3a 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -11,8 +11,8 @@ SYNOPSIS\n [verse]\n 'git bundle' create <file> <git-rev-list-args>\n 'git bundle' verify <file>\n-'git bundle' list-heads <file> [refname...]\n-'git bundle' unbundle <file> [refname...]\n+'git bundle' list-heads <file> [<refname>...]\n+'git bundle' unbundle <file> [<refname>...]\n \n DESCRIPTION\n -----------\n@@ -68,7 +68,7 @@ unbundle <file>::\n \tpackaged.\n \n \n-[refname...]::\n+[<refname>...]::\n \tA list of references used to limit the references reported as\n \tavailable. This is principally of use to 'git fetch', which\n \texpects to receive only those references asked for and not\ndiff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt\nindex 62f9ab2..0c0a9c1 100644\n--- a/Documentation/git-checkout-index.txt\n+++ b/Documentation/git-checkout-index.txt\n@@ -13,7 +13,7 @@ SYNOPSIS\n \t\t   [--stage=<number>|all]\n \t\t   [--temp]\n \t\t   [-z] [--stdin]\n-\t\t   [--] [<file>]*\n+\t\t   [--] [<file>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt\nindex 349366e..5dcf427 100644\n--- a/Documentation/git-commit-tree.txt\n+++ b/Documentation/git-commit-tree.txt\n@@ -8,7 +8,7 @@ git-commit-tree - Create a new commit object\n \n SYNOPSIS\n --------\n-'git commit-tree' <tree> [-p <parent commit>]* < changelog\n+'git commit-tree' <tree> [(-p <parent commit>)...] < changelog\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt\nindex 01c9f8e..2f0ddf6 100644\n--- a/Documentation/git-daemon.txt\n+++ b/Documentation/git-daemon.txt\n@@ -9,15 +9,15 @@ SYNOPSIS\n --------\n [verse]\n 'git daemon' [--verbose] [--syslog] [--export-all]\n-\t     [--timeout=n] [--init-timeout=n] [--max-connections=n]\n-\t     [--strict-paths] [--base-path=path] [--base-path-relaxed]\n-\t     [--user-path | --user-path=path]\n-\t     [--interpolated-path=pathtemplate]\n-\t     [--reuseaddr] [--detach] [--pid-file=file]\n-\t     [--enable=service] [--disable=service]\n-\t     [--allow-override=service] [--forbid-override=service]\n-\t     [--inetd | [--listen=host_or_ipaddr] [--port=n] [--user=user [--group=group]]\n-\t     [directory...]\n+\t     [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>]\n+\t     [--strict-paths] [--base-path=<path>] [--base-path-relaxed]\n+\t     [--user-path | --user-path=<path>]\n+\t     [--interpolated-path=<pathtemplate>]\n+\t     [--reuseaddr] [--detach] [--pid-file=<file>]\n+\t     [--enable=<service>] [--disable=<service>]\n+\t     [--allow-override=<service>] [--forbid-override=<service>]\n+\t     [--inetd | [--listen=<host_or_ipaddr>] [--port=<n>] [--user=<user> [--group=<group>]]\n+\t     [<directory>...]\n \n DESCRIPTION\n -----------\n@@ -48,7 +48,7 @@ OPTIONS\n \t'git daemon' will refuse to start when this option is enabled and no\n \twhitelist is specified.\n \n---base-path=path::\n+--base-path=<path>::\n \tRemap all the path requests as relative to the given path.\n \tThis is sort of \"GIT root\" - if you run 'git daemon' with\n \t'--base-path=/srv/git' on example.com, then if you later try to pull\n@@ -61,7 +61,7 @@ OPTIONS\n \tThis is useful for switching to --base-path usage, while still\n \tallowing the old paths.\n \n---interpolated-path=pathtemplate::\n+--interpolated-path=<pathtemplate>::\n \tTo support virtual hosting, an interpolated path template can be\n \tused to dynamically construct alternate paths.  The template\n \tsupports %H for the target hostname as supplied by the client but\n@@ -80,27 +80,27 @@ OPTIONS\n \tHave the server run as an inetd service. Implies --syslog.\n \tIncompatible with --port, --listen, --user and --group options.\n \n---listen=host_or_ipaddr::\n+--listen=<host_or_ipaddr>::\n \tListen on a specific IP address or hostname.  IP addresses can\n \tbe either an IPv4 address or an IPv6 address if supported.  If IPv6\n \tis not supported, then --listen=hostname is also not supported and\n \t--listen must be given an IPv4 address.\n \tIncompatible with '--inetd' option.\n \n---port=n::\n+--port=<n>::\n \tListen on an alternative port.  Incompatible with '--inetd' option.\n \n---init-timeout=n::\n+--init-timeout=<n>::\n \tTimeout between the moment the connection is established and the\n \tclient request is received (typically a rather low value, since\n \tthat should be basically immediate).\n \n---timeout=n::\n+--timeout=<n>::\n \tTimeout for specific client sub-requests. This includes the time\n \tit takes for the server to process the sub-request and the time spent\n \twaiting for the next client's request.\n \n---max-connections=n::\n+--max-connections=<n>::\n \tMaximum number of concurrent clients, defaults to 32.  Set it to\n \tzero for no limit.\n \n@@ -109,7 +109,7 @@ OPTIONS\n \t--verbose, thus by default only error conditions will be logged.\n \n --user-path::\n---user-path=path::\n+--user-path=<path>::\n \tAllow {tilde}user notation to be used in requests.  When\n \tspecified with no parameter, requests to\n \tgit://host/{tilde}alice/foo is taken as a request to access\n@@ -129,12 +129,12 @@ OPTIONS\n --detach::\n \tDetach from the shell. Implies --syslog.\n \n---pid-file=file::\n+--pid-file=<file>::\n \tSave the process id in 'file'.  Ignored when the daemon\n \tis run under `--inetd`.\n \n---user=user::\n---group=group::\n+--user=<user>::\n+--group=<group>::\n \tChange daemon's uid and gid before entering the service loop.\n \tWhen only `--user` is given without `--group`, the\n \tprimary group ID for the user is used.  The values of\n@@ -145,16 +145,16 @@ Giving these options is an error when used with `--inetd`; use\n the facility of inet daemon to achieve the same before spawning\n 'git daemon' if needed.\n \n---enable=service::\n---disable=service::\n+--enable=<service>::\n+--disable=<service>::\n \tEnable/disable the service site-wide per default.  Note\n \tthat a service disabled site-wide can still be enabled\n \tper repository if it is marked overridable and the\n \trepository enables the service with a configuration\n \titem.\n \n---allow-override=service::\n---forbid-override=service::\n+--allow-override=<service>::\n+--forbid-override=<service>::\n \tAllow/forbid overriding the site-wide default with per\n \trepository configuration.  By default, all the services\n \tare overridable.\ndiff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt\nindex fcad113..e05b686 100644\n--- a/Documentation/git-fast-export.txt\n+++ b/Documentation/git-fast-export.txt\n@@ -96,7 +96,7 @@ marks the same across runs.\n \tin the commit (as opposed to just listing the files which are\n \tdifferent from the commit's first parent).\n \n-[git-rev-list-args...]::\n+[<git-rev-list-args>...]::\n        A list of arguments, acceptable to 'git rev-parse' and\n        'git rev-list', that specifies the specific objects and references\n        to export.  For example, `master{tilde}10..master` causes the\ndiff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt\nindex 400fe7f..d159e88 100644\n--- a/Documentation/git-fetch.txt\n+++ b/Documentation/git-fetch.txt\n@@ -12,7 +12,7 @@ SYNOPSIS\n \n 'git fetch' [<options>] <group>\n \n-'git fetch' --multiple [<options>] [<repository> | <group>]...\n+'git fetch' --multiple [<options>] [(<repository> | <group>)...]\n \n 'git fetch' --all [<options>]\n \ndiff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt\nindex f51860d..796e748 100644\n--- a/Documentation/git-filter-branch.txt\n+++ b/Documentation/git-filter-branch.txt\n@@ -117,7 +117,7 @@ OPTIONS\n \tThis is the filter for performing the commit.\n \tIf this filter is specified, it will be called instead of the\n \t'git commit-tree' command, with arguments of the form\n-\t\"<TREE_ID> [-p <PARENT_COMMIT_ID>]...\" and the log message on\n+\t\"<TREE_ID> [(-p <PARENT_COMMIT_ID>)...]\" and the log message on\n \tstdin.  The commit id is expected on stdout.\n +\n As a special extension, the commit filter may emit multiple\ndiff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt\nindex d66fd9d..fac1cf5 100644\n--- a/Documentation/git-for-each-ref.txt\n+++ b/Documentation/git-for-each-ref.txt\n@@ -9,7 +9,7 @@ SYNOPSIS\n --------\n [verse]\n 'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl]\n-\t\t   [--sort=<key>]* [--format=<format>] [<pattern>...]\n+\t\t   [(--sort=<key>)...] [--format=<format>] [<pattern>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt\nindex f3ccc72..c2bb810 100644\n--- a/Documentation/git-index-pack.txt\n+++ b/Documentation/git-index-pack.txt\n@@ -59,10 +59,10 @@ OPTIONS\n \tthe newly constructed pack and index before refs can be\n \tupdated to use objects contained in the pack.\n \n---keep='why'::\n+--keep=<msg>::\n \tLike --keep create a .keep file before moving the index into\n \tits final destination, but rather than creating an empty file\n-\tplace 'why' followed by an LF into the .keep file.  The 'why'\n+\tplace '<msg>' followed by an LF into the .keep file.  The '<msg>'\n \tmessage can later be searched for within all .keep files to\n \tlocate any which have outlived their usefulness.\n \ndiff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\nindex 246b07e..00d4a12 100644\n--- a/Documentation/git-init.txt\n+++ b/Documentation/git-init.txt\n@@ -31,7 +31,7 @@ current working directory.\n Specify the directory from which templates will be used.  (See the \"TEMPLATE\n DIRECTORY\" section below.)\n \n---shared[={false|true|umask|group|all|world|everybody|0xxx}]::\n+--shared[=(false|true|umask|group|all|world|everybody|0xxx)]::\n \n Specify that the git repository is to be shared amongst several users.  This\n allows users belonging to the same group to push into that\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 347f447..86abd13 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -17,7 +17,7 @@ SYNOPSIS\n \t\t[--exclude-per-directory=<file>]\n \t\t[--exclude-standard]\n \t\t[--error-unmatch] [--with-tree=<tree-ish>]\n-\t\t[--full-name] [--abbrev] [--] [<file>]*\n+\t\t[--full-name] [--abbrev] [--] [<file>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt\nindex 1f89d36..76ed625 100644\n--- a/Documentation/git-ls-tree.txt\n+++ b/Documentation/git-ls-tree.txt\n@@ -10,8 +10,8 @@ SYNOPSIS\n --------\n [verse]\n 'git ls-tree' [-d] [-r] [-t] [-l] [-z]\n-\t    [--name-only] [--name-status] [--full-name] [--full-tree] [--abbrev=[<n>]]\n-\t    <tree-ish> [paths...]\n+\t    [--name-only] [--name-status] [--full-name] [--full-tree] [--abbrev[=<n>]]\n+\t    <tree-ish> [<path>...]\n \n DESCRIPTION\n -----------\n@@ -19,11 +19,11 @@ Lists the contents of a given tree object, like what \"/bin/ls -a\" does\n in the current working directory.  Note that:\n \n  - the behaviour is slightly different from that of \"/bin/ls\" in that the\n-   'paths' denote just a list of patterns to match, e.g. so specifying\n+   '<path>' denotes just a list of patterns to match, e.g. so specifying\n    directory name (without '-r') will behave differently, and order of the\n    arguments does not matter.\n \n- - the behaviour is similar to that of \"/bin/ls\" in that the 'paths' is\n+ - the behaviour is similar to that of \"/bin/ls\" in that the '<path>' is\n    taken as relative to the current working directory.  E.g. when you are\n    in a directory 'sub' that has a directory 'dir', you can run 'git\n    ls-tree -r HEAD dir' to list the contents of the tree (that is\n@@ -72,7 +72,7 @@ OPTIONS\n \tDo not limit the listing to the current working directory.\n \tImplies --full-name.\n \n-paths::\n+[<path>...]::\n \tWhen paths are given, show them (note that this isn't really raw\n \tpathnames, but rather a list of patterns to match).  Otherwise\n \timplicitly uses the root level of the tree as the sole path argument.\ndiff --git a/Documentation/git-mailsplit.txt b/Documentation/git-mailsplit.txt\nindex a634485..71912a1 100644\n--- a/Documentation/git-mailsplit.txt\n+++ b/Documentation/git-mailsplit.txt\n@@ -7,7 +7,7 @@ git-mailsplit - Simple UNIX mbox splitter program\n \n SYNOPSIS\n --------\n-'git mailsplit' [-b] [-f<nn>] [-d<prec>] [--keep-cr] -o<directory> [--] [<mbox>|<Maildir>...]\n+'git mailsplit' [-b] [-f<nn>] [-d<prec>] [--keep-cr] -o<directory> [--] [(<mbox>|<Maildir>)...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt\nindex e4ed016..1f75a84 100644\n--- a/Documentation/git-mergetool.txt\n+++ b/Documentation/git-mergetool.txt\n@@ -7,7 +7,7 @@ git-mergetool - Run merge conflict resolution tools to resolve merge conflicts\n \n SYNOPSIS\n --------\n-'git mergetool' [--tool=<tool>] [-y|--no-prompt|--prompt] [<file>]...\n+'git mergetool' [--tool=<tool>] [-y|--no-prompt|--prompt] [<file>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt\nindex 8ed09c0..65eff66 100644\n--- a/Documentation/git-pack-objects.txt\n+++ b/Documentation/git-pack-objects.txt\n@@ -11,8 +11,8 @@ SYNOPSIS\n [verse]\n 'git pack-objects' [-q | --progress | --all-progress] [--all-progress-implied]\n \t[--no-reuse-delta] [--delta-base-offset] [--non-empty]\n-\t[--local] [--incremental] [--window=N] [--depth=N]\n-\t[--revs [--unpacked | --all]*] [--stdout | base-name]\n+\t[--local] [--incremental] [--window=<n>] [--depth=<n>]\n+\t[--revs [--unpacked | --all]] [--stdout | base-name]\n \t[--keep-true-parents] < object-list\n \n \n@@ -82,8 +82,8 @@ base-name::\n \treference was included in the resulting packfile.  This\n \tcan be useful to send new tags to native git clients.\n \n---window=[N]::\n---depth=[N]::\n+--window=<n>::\n+--depth=<n>::\n \tThese two options affect how the objects contained in\n \tthe pack are stored using delta compression.  The\n \tobjects are first internally sorted by type, size and\n@@ -95,10 +95,10 @@ base-name::\n \ttimes to get to the necessary object.\n \tThe default value for --window is 10 and --depth is 50.\n \n---window-memory=[N]::\n+--window-memory=<n>::\n \tThis option provides an additional limit on top of `--window`;\n \tthe window size will dynamically scale down so as to not take\n-\tup more than N bytes in memory.  This is useful in\n+\tup more than '<n>' bytes in memory.  This is useful in\n \trepositories with a mix of large and small objects to not run\n \tout of memory with a large window, but still be able to take\n \tadvantage of the large window for the smaller objects.  The\n@@ -106,7 +106,7 @@ base-name::\n \t`--window-memory=0` makes memory usage unlimited, which is the\n \tdefault.\n \n---max-pack-size=[N]::\n+--max-pack-size=<n>::\n \tMaximum size of each output pack file. The size can be suffixed with\n \t\"k\", \"m\", or \"g\". The minimum size allowed is limited to 1 MiB.\n \tIf specified,  multiple packfiles may be created.\n@@ -171,7 +171,7 @@ base-name::\n \twholesale enforcement of a different compression level on the\n \tpacked data is desired.\n \n---compression=[N]::\n+--compression=<n>::\n \tSpecifies compression level for newly-compressed data in the\n \tgenerated pack.  If not specified,  pack compression level is\n \tdetermined first by pack.compression,  then by core.compression,\ndiff --git a/Documentation/git-relink.txt b/Documentation/git-relink.txt\nindex 8a5842b..8fc809f 100644\n--- a/Documentation/git-relink.txt\n+++ b/Documentation/git-relink.txt\n@@ -7,7 +7,7 @@ git-relink - Hardlink common objects in local repositories\n \n SYNOPSIS\n --------\n-'git relink' [--safe] <dir> [<dir>]* <master_dir>\n+'git relink' [--safe] <dir>... <master_dir>\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt\nindex aa021b0..0d28feb 100644\n--- a/Documentation/git-remote.txt\n+++ b/Documentation/git-remote.txt\n@@ -20,7 +20,7 @@ SYNOPSIS\n 'git remote set-url --delete' [--push] <name> <url>\n 'git remote' [-v | --verbose] 'show' [-n] <name>\n 'git remote prune' [-n | --dry-run] <name>\n-'git remote' [-v | --verbose] 'update' [-p | --prune] [group | remote]...\n+'git remote' [-v | --verbose] 'update' [-p | --prune] [(<group> | <remote>)...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt\nindex 9566727..27f7865 100644\n--- a/Documentation/git-repack.txt\n+++ b/Documentation/git-repack.txt\n@@ -8,7 +8,7 @@ git-repack - Pack unpacked objects in a repository\n \n SYNOPSIS\n --------\n-'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [--window=N] [--depth=N]\n+'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [--window=<n>] [--depth=<n>]\n \n DESCRIPTION\n -----------\n@@ -80,8 +80,8 @@ other objects in that pack they already have locally.\n \tthis repository (or a direct copy of it)\n \tover HTTP or FTP.  See linkgit:git-update-server-info[1].\n \n---window=[N]::\n---depth=[N]::\n+--window=<n>::\n+--depth=<n>::\n \tThese two options affect how the objects contained in the pack are\n \tstored using delta compression. The objects are first internally\n \tsorted by type, size and optionally names and compared against the\n@@ -91,10 +91,10 @@ other objects in that pack they already have locally.\n \tto be applied that many times to get to the necessary object.\n \tThe default value for --window is 10 and --depth is 50.\n \n---window-memory=[N]::\n+--window-memory=<n>::\n \tThis option provides an additional limit on top of `--window`;\n \tthe window size will dynamically scale down so as to not take\n-\tup more than N bytes in memory.  This is useful in\n+\tup more than '<n>' bytes in memory.  This is useful in\n \trepositories with a mix of large and small objects to not run\n \tout of memory with a large window, but still be able to take\n \tadvantage of the large window for the smaller objects.  The\n@@ -102,7 +102,7 @@ other objects in that pack they already have locally.\n \t`--window-memory=0` makes memory usage unlimited, which is the\n \tdefault.\n \n---max-pack-size=[N]::\n+--max-pack-size=<n>::\n \tMaximum size of each output pack file. The size can be suffixed with\n \t\"k\", \"m\", or \"g\". The minimum size allowed is limited to 1 MiB.\n \tIf specified,  multiple packfiles may be created.\ndiff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt\nindex 173f3fc..8e1e329 100644\n--- a/Documentation/git-rev-list.txt\n+++ b/Documentation/git-rev-list.txt\n@@ -9,10 +9,10 @@ git-rev-list - Lists commit objects in reverse chronological order\n SYNOPSIS\n --------\n [verse]\n-'git rev-list' [ \\--max-count=number ]\n-\t     [ \\--skip=number ]\n-\t     [ \\--max-age=timestamp ]\n-\t     [ \\--min-age=timestamp ]\n+'git rev-list' [ \\--max-count=<number> ]\n+\t     [ \\--skip=<number> ]\n+\t     [ \\--max-age=<timestamp> ]\n+\t     [ \\--min-age=<timestamp> ]\n \t     [ \\--sparse ]\n \t     [ \\--merges ]\n \t     [ \\--no-merges ]\n@@ -21,10 +21,10 @@ SYNOPSIS\n \t     [ \\--full-history ]\n \t     [ \\--not ]\n \t     [ \\--all ]\n-\t     [ \\--branches[=pattern] ]\n-\t     [ \\--tags[=pattern] ]\n-\t     [ \\--remotes[=pattern] ]\n-\t     [ \\--glob=glob-pattern ]\n+\t     [ \\--branches[=<pattern>] ]\n+\t     [ \\--tags[=<pattern>] ]\n+\t     [ \\--remotes[=<pattern>] ]\n+\t     [ \\--glob=<glob-pattern> ]\n \t     [ \\--stdin ]\n \t     [ \\--quiet ]\n \t     [ \\--topo-order ]\n@@ -37,7 +37,7 @@ SYNOPSIS\n \t     [ \\--regexp-ignore-case | -i ]\n \t     [ \\--extended-regexp | -E ]\n \t     [ \\--fixed-strings | -F ]\n-\t     [ \\--date={local|relative|default|iso|rfc|short} ]\n+\t     [ \\--date=(local|relative|default|iso|rfc|short) ]\n \t     [ [\\--objects | \\--objects-edge] [ \\--unpacked ] ]\n \t     [ \\--pretty | \\--header ]\n \t     [ \\--bisect ]\ndiff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt\nindex 341ca90..4a27643 100644\n--- a/Documentation/git-rev-parse.txt\n+++ b/Documentation/git-rev-parse.txt\n@@ -95,7 +95,7 @@ OPTIONS\n \tunfortunately named tag \"master\"), and show them as full\n \trefnames (e.g. \"refs/heads/master\").\n \n---abbrev-ref[={strict|loose}]::\n+--abbrev-ref[=(strict|loose)]::\n \tA non-ambiguous short name of the objects name.\n \tThe option core.warnAmbiguousRefs is used to select the strict\n \tabbreviation mode.\ndiff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt\nindex bc1ac77..5cc3baf 100644\n--- a/Documentation/git-shortlog.txt\n+++ b/Documentation/git-shortlog.txt\n@@ -44,7 +44,7 @@ OPTIONS\n --email::\n \tShow the email address of each author.\n \n---format[='<format>']::\n+--format[=<format>]::\n \tInstead of the commit subject, use some other information to\n \tdescribe each commit.  '<format>' can be any string accepted\n \tby the `--format` option of 'git log', such as '{asterisk} [%h] %s'.\ndiff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt\nindex 6453263..bd9f886 100644\n--- a/Documentation/git-show-branch.txt\n+++ b/Documentation/git-show-branch.txt\n@@ -12,7 +12,7 @@ SYNOPSIS\n \t\t[--current] [--color[=<when>] | --no-color] [--sparse]\n \t\t[--more=<n> | --list | --independent | --merge-base]\n \t\t[--no-name | --sha1-name] [--topics]\n-\t\t[<rev> | <glob>]...\n+\t\t[(<rev> | <glob>)...]\n \n 'git show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>]\n \ndiff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt\nindex be8a51f..139d314 100644\n--- a/Documentation/git-svn.txt\n+++ b/Documentation/git-svn.txt\n@@ -438,7 +438,7 @@ git rebase --onto remotes/git-svn A^ master\n OPTIONS\n -------\n \n---shared[={false|true|umask|group|all|world|everybody}]::\n+--shared[=(false|true|umask|group|all|world|everybody)]::\n --template=<template_directory>::\n \tOnly used with the 'init' command.\n \tThese are passed directly to 'git init'.\ndiff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt\nindex 74d1d49..a5782a6 100644\n--- a/Documentation/git-update-index.txt\n+++ b/Documentation/git-update-index.txt\n@@ -12,7 +12,7 @@ SYNOPSIS\n 'git update-index'\n \t     [--add] [--remove | --force-remove] [--replace]\n \t     [--refresh] [-q] [--unmerged] [--ignore-missing]\n-\t     [--cacheinfo <mode> <object> <file>]*\n+\t     [(--cacheinfo <mode> <object> <file>)...]\n \t     [--chmod=(+|-)x]\n \t     [--assume-unchanged | --no-assume-unchanged]\n \t     [--skip-worktree | --no-skip-worktree]\n@@ -21,7 +21,7 @@ SYNOPSIS\n \t     [--info-only] [--index-info]\n \t     [-z] [--stdin]\n \t     [--verbose]\n-\t     [--] [<file>]*\n+\t     [--] [<file>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt\nindex e1586c7..51e8e0a 100644\n--- a/Documentation/git-web--browse.txt\n+++ b/Documentation/git-web--browse.txt\n@@ -32,19 +32,19 @@ Custom commands may also be specified.\n \n OPTIONS\n -------\n--b BROWSER::\n---browser=BROWSER::\n-\tUse the specified BROWSER. It must be in the list of supported\n+-b <browser>::\n+--browser=<browser>::\n+\tUse the specified browser. It must be in the list of supported\n \tbrowsers.\n \n--t BROWSER::\n---tool=BROWSER::\n+-t <browser>::\n+--tool=<browser>::\n \tSame as above.\n \n--c CONF.VAR::\n---config=CONF.VAR::\n+-c <conf.var>::\n+--config=<conf.var>::\n \tCONF.VAR is looked up in the git config files. If it's set,\n-\tthen its value specify the browser that should be used.\n+\tthen its value specifies the browser that should be used.\n \n CONFIGURATION VARIABLES\n -----------------------\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex dd57bdc..2e1b2c0 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -12,8 +12,8 @@ SYNOPSIS\n 'git' [--version] [--exec-path[=GIT_EXEC_PATH]] [--html-path]\n     [-p|--paginate|--no-pager] [--no-replace-objects]\n     [--bare] [--git-dir=GIT_DIR] [--work-tree=GIT_WORK_TREE]\n-    [-c name=value]\n-    [--help] COMMAND [ARGS]\n+    [-c <name>=<value>]\n+    [--help] <command> [<args>]\n \n DESCRIPTION\n -----------\n@@ -28,7 +28,7 @@ also want to read linkgit:gitcvs-migration[7].  See\n the link:user-manual.html[Git User's Manual] for a more in-depth\n introduction.\n \n-The COMMAND is either a name of a Git command (see below) or an alias\n+The '<command>' is either a name of a Git command (see below) or an alias\n as defined in the configuration file (see linkgit:git-config[1]).\n \n Formatted and hyperlinked version of the latest git\ndiff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt\nindex 049313d..8676e26 100644\n--- a/Documentation/merge-strategies.txt\n+++ b/Documentation/merge-strategies.txt\n@@ -52,7 +52,7 @@ no-renormalize;;\n \tDisables the `renormalize` option.  This overrides the\n \t`merge.renormalize` configuration variable.\n \n-subtree[=path];;\n+subtree[=<path>];;\n \tThis option is a more advanced form of 'subtree' strategy, where\n \tthe strategy makes a guess on how two trees must be shifted to\n \tmatch with each other when merging.  Instead, the specified path\ndiff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt\nindex 9b6f389..50923e2 100644\n--- a/Documentation/pretty-options.txt\n+++ b/Documentation/pretty-options.txt\n@@ -1,5 +1,5 @@\n---pretty[='<format>']::\n---format='<format>'::\n+--pretty[=<format>]::\n+--format=<format>::\n \n \tPretty-print the contents of the commit logs in a given format,\n \twhere '<format>' can be one of 'oneline', 'short', 'medium',\ndiff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt\nindex ebc0108..7a42567 100644\n--- a/Documentation/rev-list-options.txt\n+++ b/Documentation/rev-list-options.txt\n@@ -13,7 +13,7 @@ include::pretty-options.txt[]\n \n \tSynonym for `--date=relative`.\n \n---date={relative,local,default,iso,rfc,short,raw}::\n+--date=(relative|local|default|iso|rfc|short|raw)::\n \n \tOnly takes effect for dates shown in human-readable format, such\n \tas when using \"--pretty\". `log.date` config variable sets a default\n@@ -246,29 +246,29 @@ endif::git-rev-list[]\n \tPretend as if all the refs in `refs/` are listed on the\n \tcommand line as '<commit>'.\n \n---branches[=pattern]::\n+--branches[=<pattern>]::\n \n \tPretend as if all the refs in `refs/heads` are listed\n-\ton the command line as '<commit>'. If `pattern` is given, limit\n+\ton the command line as '<commit>'. If '<pattern>' is given, limit\n \tbranches to ones matching given shell glob. If pattern lacks '?',\n \t'*', or '[', '/*' at the end is implied.\n \n---tags[=pattern]::\n+--tags[=<pattern>]::\n \n \tPretend as if all the refs in `refs/tags` are listed\n-\ton the command line as '<commit>'. If `pattern` is given, limit\n+\ton the command line as '<commit>'. If '<pattern>' is given, limit\n \ttags to ones matching given shell glob. If pattern lacks '?', '*',\n \tor '[', '/*' at the end is implied.\n \n---remotes[=pattern]::\n+--remotes[=<pattern>]::\n \n \tPretend as if all the refs in `refs/remotes` are listed\n-\ton the command line as '<commit>'. If `pattern`is given, limit\n+\ton the command line as '<commit>'. If '<pattern>' is given, limit\n \tremote tracking branches to ones matching given shell glob.\n \tIf pattern lacks '?', '*', or '[', '/*' at the end is implied.\n \n---glob=glob-pattern::\n-\tPretend as if all the refs matching shell glob `glob-pattern`\n+--glob=<glob-pattern>::\n+\tPretend as if all the refs matching shell glob '<glob-pattern>'\n \tare listed on the command line as '<commit>'. Leading 'refs/',\n \tis automatically prepended if missing. If pattern lacks '?', '*',\n \tor '[', '/*' at the end is implied.\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex ce45bfc..cb3b98a 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -3850,7 +3850,7 @@ You create a commit object by giving it the tree that describes the\n state at the time of the commit, and a list of parents:\n \n -------------------------------------------------\n-$ git commit-tree <tree> -p <parent> [-p <parent2> ..]\n+$ git commit-tree <tree> -p <parent> [(-p <parent2>)...]\n -------------------------------------------------\n \n and then giving the reason for the commit on stdin (either through\ndiff --git a/archive.c b/archive.c\nindex edd6853..f59afda 100644\n--- a/archive.c\n+++ b/archive.c\n@@ -7,9 +7,9 @@\n #include \"unpack-trees.h\"\n \n static char const * const archive_usage[] = {\n-\t\"git archive [options] <tree-ish> [path...]\",\n+\t\"git archive [options] <tree-ish> [<path>...]\",\n \t\"git archive --list\",\n-\t\"git archive --remote <repo> [--exec <cmd>] [options] <tree-ish> [path...]\",\n+\t\"git archive --remote <repo> [--exec <cmd>] [options] <tree-ish> [<path>...]\",\n \t\"git archive --remote <repo> [--exec <cmd>] --list\",\n \tNULL\n };\ndiff --git a/builtin/bundle.c b/builtin/bundle.c\nindex 80649ba..9b87fb9 100644\n--- a/builtin/bundle.c\n+++ b/builtin/bundle.c\n@@ -12,8 +12,8 @@\n static const char builtin_bundle_usage[] =\n   \"git bundle create <file> <git-rev-list args>\\n\"\n   \"   or: git bundle verify <file>\\n\"\n-  \"   or: git bundle list-heads <file> [refname...]\\n\"\n-  \"   or: git bundle unbundle <file> [refname...]\";\n+  \"   or: git bundle list-heads <file> [<refname>...]\\n\"\n+  \"   or: git bundle unbundle <file> [<refname>...]\";\n \n int cmd_bundle(int argc, const char **argv, const char *prefix)\n {\ndiff --git a/builtin/checkout-index.c b/builtin/checkout-index.c\nindex a7a5ee1..65cbee0 100644\n--- a/builtin/checkout-index.c\n+++ b/builtin/checkout-index.c\n@@ -155,7 +155,7 @@ static void checkout_all(const char *prefix, int prefix_length)\n }\n \n static const char * const builtin_checkout_index_usage[] = {\n-\t\"git checkout-index [options] [--] <file>...\",\n+\t\"git checkout-index [options] [--] [<file>...]\",\n \tNULL\n };\n \ndiff --git a/builtin/commit-tree.c b/builtin/commit-tree.c\nindex 87f0591..e065739 100644\n--- a/builtin/commit-tree.c\n+++ b/builtin/commit-tree.c\n@@ -9,7 +9,7 @@\n #include \"builtin.h\"\n #include \"utf8.h\"\n \n-static const char commit_tree_usage[] = \"git commit-tree <sha1> [-p <sha1>]* < changelog\";\n+static const char commit_tree_usage[] = \"git commit-tree <sha1> [(-p <sha1>)...] < changelog\";\n \n static void new_parent(struct commit *parent, struct commit_list **parents_p)\n {\ndiff --git a/builtin/fetch.c b/builtin/fetch.c\nindex 6fc5047..d35f000 100644\n--- a/builtin/fetch.c\n+++ b/builtin/fetch.c\n@@ -16,7 +16,7 @@\n static const char * const builtin_fetch_usage[] = {\n \t\"git fetch [<options>] [<repository> [<refspec>...]]\",\n \t\"git fetch [<options>] <group>\",\n-\t\"git fetch --multiple [<options>] [<repository> | <group>]...\",\n+\t\"git fetch --multiple [<options>] [(<repository> | <group>)...]\",\n \t\"git fetch --all [<options>]\",\n \tNULL\n };\ndiff --git a/builtin/grep.c b/builtin/grep.c\nindex da32f3d..3d5f6ac 100644\n--- a/builtin/grep.c\n+++ b/builtin/grep.c\n@@ -24,7 +24,7 @@\n #endif\n \n static char const * const grep_usage[] = {\n-\t\"git grep [options] [-e] <pattern> [<rev>...] [[--] path...]\",\n+\t\"git grep [options] [-e] <pattern> [<rev>...] [[--] <path>...]\",\n \tNULL\n };\n \ndiff --git a/builtin/index-pack.c b/builtin/index-pack.c\nindex e243d9d..8dc5c0b 100644\n--- a/builtin/index-pack.c\n+++ b/builtin/index-pack.c\n@@ -11,7 +11,7 @@\n #include \"exec_cmd.h\"\n \n static const char index_pack_usage[] =\n-\"git index-pack [-v] [-o <index-file>] [{ --keep | --keep=<msg> }] [--strict] { <pack-file> | --stdin [--fix-thin] [<pack-file>] }\";\n+\"git index-pack [-v] [-o <index-file>] [ --keep | --keep=<msg> ] [--strict] (<pack-file> | --stdin [--fix-thin] [<pack-file>])\";\n \n struct object_entry\n {\ndiff --git a/builtin/ls-files.c b/builtin/ls-files.c\nindex bb4f612..6a307ab 100644\n--- a/builtin/ls-files.c\n+++ b/builtin/ls-files.c\n@@ -424,7 +424,7 @@ int report_path_error(const char *ps_matched, const char **pathspec, int prefix_\n }\n \n static const char * const ls_files_usage[] = {\n-\t\"git ls-files [options] [<file>]*\",\n+\t\"git ls-files [options] [<file>...]\",\n \tNULL\n };\n \ndiff --git a/builtin/ls-tree.c b/builtin/ls-tree.c\nindex a818756..f73e6bd 100644\n--- a/builtin/ls-tree.c\n+++ b/builtin/ls-tree.c\n@@ -24,7 +24,7 @@ static int chomp_prefix;\n static const char *ls_tree_prefix;\n \n static const  char * const ls_tree_usage[] = {\n-\t\"git ls-tree [<options>] <tree-ish> [path...]\",\n+\t\"git ls-tree [<options>] <tree-ish> [<path>...]\",\n \tNULL\n };\n \ndiff --git a/builtin/mailsplit.c b/builtin/mailsplit.c\nindex 99654d0..2d43278 100644\n--- a/builtin/mailsplit.c\n+++ b/builtin/mailsplit.c\n@@ -10,7 +10,7 @@\n #include \"strbuf.h\"\n \n static const char git_mailsplit_usage[] =\n-\"git mailsplit [-d<prec>] [-f<n>] [-b] [--keep-cr] -o<directory> [<mbox>|<Maildir>...]\";\n+\"git mailsplit [-d<prec>] [-f<n>] [-b] [--keep-cr] -o<directory> [(<mbox>|<Maildir>)...]\";\n \n static int is_from_line(const char *line, int len)\n {\ndiff --git a/builtin/pack-objects.c b/builtin/pack-objects.c\nindex d5a8db1..f8eba53 100644\n--- a/builtin/pack-objects.c\n+++ b/builtin/pack-objects.c\n@@ -23,15 +23,15 @@\n #endif\n \n static const char pack_usage[] =\n-  \"git pack-objects [{ -q | --progress | --all-progress }]\\n\"\n+  \"git pack-objects [ -q | --progress | --all-progress ]\\n\"\n   \"        [--all-progress-implied]\\n\"\n-  \"        [--max-pack-size=N] [--local] [--incremental]\\n\"\n-  \"        [--window=N] [--window-memory=N] [--depth=N]\\n\"\n+  \"        [--max-pack-size=<n>] [--local] [--incremental]\\n\"\n+  \"        [--window=<n>] [--window-memory=<n>] [--depth=<n>]\\n\"\n   \"        [--no-reuse-delta] [--no-reuse-object] [--delta-base-offset]\\n\"\n-  \"        [--threads=N] [--non-empty] [--revs [--unpacked | --all]*]\\n\"\n+  \"        [--threads=<n>] [--non-empty] [--revs [--unpacked | --all]]\\n\"\n   \"        [--reflog] [--stdout | base-name] [--include-tag]\\n\"\n   \"        [--keep-unreachable | --unpack-unreachable]\\n\"\n-  \"        [<ref-list | <object-list]\";\n+  \"        [< ref-list | < object-list]\";\n \n struct object_entry {\n \tstruct pack_idx_entry idx;\ndiff --git a/builtin/remote.c b/builtin/remote.c\nindex 48e0a6b..e9a6e09 100644\n--- a/builtin/remote.c\n+++ b/builtin/remote.c\n@@ -15,7 +15,7 @@ static const char * const builtin_remote_usage[] = {\n \t\"git remote set-head <name> (-a | -d | <branch>)\",\n \t\"git remote [-v | --verbose] show [-n] <name>\",\n \t\"git remote prune [-n | --dry-run] <name>\",\n-\t\"git remote [-v | --verbose] update [-p | --prune] [group | remote]\",\n+\t\"git remote [-v | --verbose] update [-p | --prune] [(<group> | <remote>)...]\",\n \t\"git remote set-branches <name> [--add] <branch>...\",\n \t\"git remote set-url <name> <newurl> [<oldurl>]\",\n \t\"git remote set-url --add <name> <newurl>\",\ndiff --git a/builtin/rev-list.c b/builtin/rev-list.c\nindex efe9360..158ce11 100644\n--- a/builtin/rev-list.c\n+++ b/builtin/rev-list.c\n@@ -11,9 +11,9 @@\n static const char rev_list_usage[] =\n \"git rev-list [OPTION] <commit-id>... [ -- paths... ]\\n\"\n \"  limiting output:\\n\"\n-\"    --max-count=nr\\n\"\n-\"    --max-age=epoch\\n\"\n-\"    --min-age=epoch\\n\"\n+\"    --max-count=<n>\\n\"\n+\"    --max-age=<epoch>\\n\"\n+\"    --min-age=<epoch>\\n\"\n \"    --sparse\\n\"\n \"    --no-merges\\n\"\n \"    --remove-empty\\n\"\n@@ -33,7 +33,7 @@ static const char rev_list_usage[] =\n \"    --objects | --objects-edge\\n\"\n \"    --unpacked\\n\"\n \"    --header | --pretty\\n\"\n-\"    --abbrev=nr | --no-abbrev\\n\"\n+\"    --abbrev=<n> | --no-abbrev\\n\"\n \"    --abbrev-commit\\n\"\n \"    --left-right\\n\"\n \"  special purpose:\\n\"\ndiff --git a/builtin/show-branch.c b/builtin/show-branch.c\nindex e8719aa..8663cca 100644\n--- a/builtin/show-branch.c\n+++ b/builtin/show-branch.c\n@@ -6,7 +6,7 @@\n #include \"parse-options.h\"\n \n static const char* show_branch_usage[] = {\n-    \"git show-branch [-a|--all] [-r|--remotes] [--topo-order | --date-order] [--current] [--color[=<when>] | --no-color] [--sparse] [--more=<n> | --list | --independent | --merge-base] [--no-name | --sha1-name] [--topics] [<rev> | <glob>]...\",\n+    \"git show-branch [-a|--all] [-r|--remotes] [--topo-order | --date-order] [--current] [--color[=<when>] | --no-color] [--sparse] [--more=<n> | --list | --independent | --merge-base] [--no-name | --sha1-name] [--topics] [(<rev> | <glob>)...]\",\n     \"git show-branch (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>]\",\n     NULL\n };\ndiff --git a/builtin/update-index.c b/builtin/update-index.c\nindex 3ab214d..62d9f3f 100644\n--- a/builtin/update-index.c\n+++ b/builtin/update-index.c\n@@ -398,7 +398,7 @@ static void read_index_info(int line_termination)\n }\n \n static const char update_index_usage[] =\n-\"git update-index [-q] [--add] [--replace] [--remove] [--unmerged] [--refresh] [--really-refresh] [--cacheinfo] [--chmod=(+|-)x] [--assume-unchanged] [--skip-worktree|--no-skip-worktree] [--info-only] [--force-remove] [--stdin] [--index-info] [--unresolve] [--again | -g] [--ignore-missing] [-z] [--verbose] [--] <file>...\";\n+\"git update-index [-q] [--add] [--replace] [--remove] [--unmerged] [--refresh] [--really-refresh] [--cacheinfo] [--chmod=(+|-)x] [--assume-unchanged] [--skip-worktree|--no-skip-worktree] [--info-only] [--force-remove] [--stdin] [--index-info] [--unresolve] [--again | -g] [--ignore-missing] [-z] [--verbose] [--] [<file>...]\";\n \n static unsigned char head_sha1[20];\n static unsigned char merge_head_sha1[20];\ndiff --git a/daemon.c b/daemon.c\nindex e22a2b7..9326d3a 100644\n--- a/daemon.c\n+++ b/daemon.c\n@@ -20,15 +20,15 @@ static int reuseaddr;\n \n static const char daemon_usage[] =\n \"git daemon [--verbose] [--syslog] [--export-all]\\n\"\n-\"           [--timeout=n] [--init-timeout=n] [--max-connections=n]\\n\"\n-\"           [--strict-paths] [--base-path=path] [--base-path-relaxed]\\n\"\n-\"           [--user-path | --user-path=path]\\n\"\n-\"           [--interpolated-path=path]\\n\"\n-\"           [--reuseaddr] [--detach] [--pid-file=file]\\n\"\n-\"           [--[enable|disable|allow-override|forbid-override]=service]\\n\"\n-\"           [--inetd | [--listen=host_or_ipaddr] [--port=n]\\n\"\n-\"                      [--user=user [--group=group]]\\n\"\n-\"           [directory...]\";\n+\"           [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>]\\n\"\n+\"           [--strict-paths] [--base-path=<path>] [--base-path-relaxed]\\n\"\n+\"           [--user-path | --user-path=<path>]\\n\"\n+\"           [--interpolated-path=<path>]\\n\"\n+\"           [--reuseaddr] [--detach] [--pid-file=<file>]\\n\"\n+\"           [--(enable|disable|allow-override|forbid-override)=<service>]\\n\"\n+\"           [--inetd | [--listen=<host_or_ipaddr>] [--port=<n>]\\n\"\n+\"                      [--user=<user> [--group=<group>]]\\n\"\n+\"           [<directory>...]\";\n \n /* List of acceptable pathname prefixes */\n static char **ok_paths;\ndiff --git a/fast-import.c b/fast-import.c\nindex 2317b0f..eab68d5 100644\n--- a/fast-import.c\n+++ b/fast-import.c\n@@ -2884,7 +2884,7 @@ static int git_pack_config(const char *k, const char *v, void *cb)\n }\n \n static const char fast_import_usage[] =\n-\"git fast-import [--date-format=f] [--max-pack-size=n] [--big-file-threshold=n] [--depth=n] [--active-branches=n] [--export-marks=marks.file]\";\n+\"git fast-import [--date-format=<f>] [--max-pack-size=<n>] [--big-file-threshold=<n>] [--depth=<n>] [--active-branches=<n>] [--export-marks=<marks.file>]\";\n \n static void parse_argv(void)\n {\ndiff --git a/git-am.sh b/git-am.sh\nindex 9317b38..763fd20 100755\n--- a/git-am.sh\n+++ b/git-am.sh\n@@ -5,7 +5,7 @@\n SUBDIRECTORY_OK=Yes\n OPTIONS_KEEPDASHDASH=\n OPTIONS_SPEC=\"\\\n-git am [options] [<mbox>|<Maildir>...]\n+git am [options] [(<mbox>|<Maildir>)...]\n git am [options] (--resolved | --skip | --abort)\n --\n i,interactive   run interactively\ndiff --git a/git-relink.perl b/git-relink.perl\nindex 937c69a..c2a0ef8 100755\n--- a/git-relink.perl\n+++ b/git-relink.perl\n@@ -163,7 +163,7 @@ sub link_two_files($$) {\n \n \n sub usage() {\n-\tprint(\"Usage: git relink [--safe] <dir> [<dir> ...] <master_dir> \\n\");\n+\tprint(\"Usage: git relink [--safe] <dir>... <master_dir> \\n\");\n \tprint(\"All directories should contain a .git/objects/ subdirectory.\\n\");\n \tprint(\"Options\\n\");\n \tprint(\"\\t--safe\\t\" .\ndiff --git a/git.c b/git.c\nindex 50a1401..09855d5 100644\n--- a/git.c\n+++ b/git.c\n@@ -10,10 +10,10 @@ const char git_usage_string[] =\n \t\"           [-p|--paginate|--no-pager] [--no-replace-objects]\\n\"\n \t\"           [--bare] [--git-dir=GIT_DIR] [--work-tree=GIT_WORK_TREE]\\n\"\n \t\"           [-c name=value] [--help]\\n\"\n-\t\"           COMMAND [ARGS]\";\n+\t\"           <command> [<args>]\";\n \n const char git_more_info_string[] =\n-\t\"See 'git help COMMAND' for more information on a specific command.\";\n+\t\"See 'git help <command>' for more information on a specific command.\";\n \n static struct startup_info git_startup_info;\n static int use_pager = -1;\ndiff --git a/upload-pack.c b/upload-pack.c\nindex 92f9530..f05e422 100644\n--- a/upload-pack.c\n+++ b/upload-pack.c\n@@ -11,7 +11,7 @@\n #include \"list-objects.h\"\n #include \"run-command.h\"\n \n-static const char upload_pack_usage[] = \"git upload-pack [--strict] [--timeout=nn] <dir>\";\n+static const char upload_pack_usage[] = \"git upload-pack [--strict] [--timeout=<n>] <dir>\";\n \n /* bits #0..7 in revision.h, #8..10 in commit.c */\n #define THEY_HAVE\t(1u << 11)\n-- \n1.7.3.rc2.221.gbf93f.dirty\n"},{"id":"152955","messageId":"20101008074320.GB4671@burratino","threadId":"25387","inReplyTo":"20101008005256.GA21738@headley","subject":"Re: [PATCH/RFC] Unify argument and option notation in the docs","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-08T07:43:20Z","receivedAt":"2010-10-08T07:43:20Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Štěpán Němec wrote:\n\n> Some examples of what this patch is based on (i.e., the current\n> prevalent usage) follow (all coming from existing documentation):\n> \n> Placeholders are enclosed in angle brackets:\n>   <file>\n>   --sort=<key>\n>   --abbrev[=<n>]\n[etc]\n\nAll sane.\n\n> [It is conceivable I could submit this as a series of smaller patches,\n> but the problems this is solving didn't seem diverse enough to me to\n> warrant that.\n\nSince the documentation processor is known to be, um, picky, could you\ndo that?  That way after bisecting a formatting problem, one has a\ndiff addressing a single issue to look at.\n\nOn the other hand, I am happy enough to comment on a single, monolithic\npatch on list if you publish the smaller patches making it up in a git\nrepository somewhere.\n\n> 1. Is `[--refs [--unpacked | --all]]' in `git-pack-object' documentation\n> correct? From my reading of builtin/pack-objects.c, `--unpacked' and\n> `--all' do the same thing and both imply --refs, so perhaps [--refs |\n> --unpacked | --all] would make more sense?\n\nDoesn't the OPTIONS section explain what --revs, --unpacked, and --all\nmean?\n\nI suspect\n\n\t[--revs] [--unpacked] [--all]\n\nwould be clearer, but\n\n\t[--revs [(--unpacked|--all)...]]\n\nseems fine, too.\n\nBy the way, shouldn't that code path use ALLOC_GROW? [1]\n\n> (I also noticed that the\n> --reflog option is shown in the usage string but undocumented.)\n\nLooks like someone forgot to add it to the man page.\n\n> 2. I left in one special case, namely the GIT_* variables in `git(1)'\n> synopsis section as values for the `--exec-path' and other options.\n\nHmm, --exec-path=GIT_EXEC_PATH currently serves as a reminder of the\nname of the corresponding environment variable, but I don't think\nthat's very important.  --exec-path[=<path>] should be fine.\n\n[1]\n-- 8< --\nSubject: pack-objects: use ALLOC_GROW\n\nInvoke ALLOC_GROW from cache.h instead of recaping its definition\nverbatim.  When this code was first written, the ALLOC_GROW macro\ndidn't exist yet; now that the macro does exist, it can make the\nsource a little shorter and more readable.\n\nNo functional change intended.\n\nSigned-off-by: Jonathan Nieder <jrnieder@gmail.com>\n---\n builtin/pack-objects.c |   16 ++++------------\n 1 files changed, 4 insertions(+), 12 deletions(-)\n\ndiff --git a/builtin/pack-objects.c b/builtin/pack-objects.c\nindex 3756cf3..6ab2878 100644\n--- a/builtin/pack-objects.c\n+++ b/builtin/pack-objects.c\n@@ -896,13 +896,9 @@ static int check_pbase_path(unsigned hash)\n \tif (0 <= pos)\n \t\treturn 1;\n \tpos = -pos - 1;\n-\tif (done_pbase_paths_alloc <= done_pbase_paths_num) {\n-\t\tdone_pbase_paths_alloc = alloc_nr(done_pbase_paths_alloc);\n-\t\tdone_pbase_paths = xrealloc(done_pbase_paths,\n-\t\t\t\t\t    done_pbase_paths_alloc *\n-\t\t\t\t\t    sizeof(unsigned));\n-\t}\n-\tdone_pbase_paths_num++;\n+\tALLOC_GROW(done_pbase_paths,\n+\t\t   ++done_pbase_paths_num,\n+\t\t   done_pbase_paths_alloc);\n \tif (pos < done_pbase_paths_num)\n \t\tmemmove(done_pbase_paths + pos + 1,\n \t\t\tdone_pbase_paths + pos,\n@@ -2248,11 +2244,7 @@ int cmd_pack_objects(int argc, const char **argv, const char *prefix)\n \t\t    !strcmp(\"--reflog\", arg) ||\n \t\t    !strcmp(\"--all\", arg)) {\n \t\t\tuse_internal_rev_list = 1;\n-\t\t\tif (rp_ac >= rp_ac_alloc - 1) {\n-\t\t\t\trp_ac_alloc = alloc_nr(rp_ac_alloc);\n-\t\t\t\trp_av = xrealloc(rp_av,\n-\t\t\t\t\t\t rp_ac_alloc * sizeof(*rp_av));\n-\t\t\t}\n+\t\t\tALLOC_GROW(rp_av, rp_ac + 2, rp_ac_alloc);\n \t\t\trp_av[rp_ac++] = arg;\n \t\t\tcontinue;\n \t\t}\n-- \n1.7.2.3\n"},{"id":"152971","messageId":"87fwwhszsf.fsf@gmail.com","threadId":"25387","inReplyTo":"20101008074320.GB4671@burratino","subject":"Re: [PATCH/RFC] Unify argument and option notation in the docs","fromName":"Štěpán Němec","fromEmail":"stepnem@gmail.com","sentAt":"2010-10-08T11:13:20Z","receivedAt":"2010-10-08T11:13:20Z","isPatch":true,"sender":{"key":"stepnem@gmail.com","avatar":"https://avatars.githubusercontent.com/u/106838?v=4"},"body":"Jonathan Nieder <jrnieder@gmail.com> writes:\n\n> Štěpán Němec wrote:\n>> [It is conceivable I could submit this as a series of smaller patches,\n>> but the problems this is solving didn't seem diverse enough to me to\n>> warrant that.\n>\n> Since the documentation processor is known to be, um, picky, could you\n> do that?  That way after bisecting a formatting problem, one has a\n> diff addressing a single issue to look at.\n\nOK. Another reason I didn't do that is that my patch actually does not\nintroduce any mark-up not already present in the sources, so it\nshouldn't introduce any new breakage AFAICT.\n\n> On the other hand, I am happy enough to comment on a single, monolithic\n> patch on list if you publish the smaller patches making it up in a git\n> repository somewhere.\n>\n>> 1. Is `[--refs [--unpacked | --all]]' in `git-pack-object' documentation\n>> correct? From my reading of builtin/pack-objects.c, `--unpacked' and\n>> `--all' do the same thing and both imply --refs, so perhaps [--refs |\n>> --unpacked | --all] would make more sense?\n>\n> Doesn't the OPTIONS section explain what --revs, --unpacked, and --all\n> mean?\n\nIt does, but IMO it contradicts the synopsis. Doesn't the fact that\n--unpacked and --all _imply_ --rev mean that you don't need to supply\nthe latter if you already gave one of the former two? That's also what I\nunderstood from looking at pack-objects.c. So neither [--revs\n[(--unpacked|--all)...]] nor [--revs [--unpacked|--all]] seem correct to\nme.\n\nI also don't see why you would want to supply --unpacked or --all\nmultiple times, so `...' would be definitely wrong, no?\n\n>> (I also noticed that the\n>> --reflog option is shown in the usage string but undocumented.)\n>\n> Looks like someone forgot to add it to the man page.\n\nOK. I'll leave that to someone who knows what the option is supposed to\ndo; it's a matter for a separate patch anyway.\n\n>> 2. I left in one special case, namely the GIT_* variables in `git(1)'\n>> synopsis section as values for the `--exec-path' and other options.\n>\n> Hmm, --exec-path=GIT_EXEC_PATH currently serves as a reminder of the\n> name of the corresponding environment variable, but I don't think\n> that's very important.  --exec-path[=<path>] should be fine.\n\nYes, that's my opinion as well, thanks for confirmation. I'll include it\nin the next round.\n\nŠtěpán\n"},{"id":"152976","messageId":"20101008164536.GB9212@burratino","threadId":"25387","inReplyTo":"20101008074320.GB4671@burratino","subject":"[PATCH 0/2] pack-objects: use ALLOC_GROW in place of manual growth","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-08T16:45:36Z","receivedAt":"2010-10-08T16:45:36Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Jonathan Nieder wrote:\n\n> -\tdone_pbase_paths_num++;\n> +\tALLOC_GROW(done_pbase_paths,\n> +\t\t   ++done_pbase_paths_num,\n> +\t\t   done_pbase_paths_alloc);\n\nJunio noticed that this makes done_pbase_paths_num grow by 3\nrather than by 1 as intended.  Sorry.\n\nPatch 1 corrects some documentation that could lead one\nastray.  Patch 2 is a corrected patch that uses ALLOC_GROW\ncorrectly (I hope).\n\nJonathan Nieder (2):\n  Documentation: No argument of ALLOC_GROW cannot have side-effects\n  pack-objects: use ALLOC_GROW\n\n builtin/pack-objects.c |   15 ++++-----------\n cache.h                |    2 +-\n 2 files changed, 5 insertions(+), 12 deletions(-)\n\n-- \n1.7.2.3\n"},{"id":"152977","messageId":"20101008164659.GC9212@burratino","threadId":"25387","inReplyTo":"20101008164536.GB9212@burratino","subject":"[PATCH 1/2] Documentation: No argument of ALLOC_GROW should have side-effects","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-08T16:46:59Z","receivedAt":"2010-10-08T16:46:59Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"The explanatory comment before the definition of ALLOC_GROW carefully\nlists arguments that will be used more than once and thus cannot have\nside-effects; a lazy reader might conclude that the arguments not\nlisted are used only once and side effects safe.\n\nCorrect it to list all three arguments, avoiding this confusion.\n\nSigned-off-by: Jonathan Nieder <jrnieder@gmail.com>\n---\n cache.h |    2 +-\n 1 files changed, 1 insertions(+), 1 deletions(-)\n\ndiff --git a/cache.h b/cache.h\nindex 2ef2fa3..23d6d45 100644\n--- a/cache.h\n+++ b/cache.h\n@@ -438,7 +438,7 @@ extern int init_db(const char *template_dir, unsigned int flags);\n  * at least 'nr' entries; the number of entries currently allocated\n  * is 'alloc', using the standard growing factor alloc_nr() macro.\n  *\n- * DO NOT USE any expression with side-effect for 'x' or 'alloc'.\n+ * DO NOT USE any expression with side-effect for 'x', 'nr', or 'alloc'.\n  */\n #define ALLOC_GROW(x, nr, alloc) \\\n \tdo { \\\n-- \n1.7.2.3\n"},{"id":"152978","messageId":"20101008164740.GD9212@burratino","threadId":"25387","inReplyTo":"20101008164536.GB9212@burratino","subject":"[PATCH 2/2] pack-objects: use ALLOC_GROW","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-08T16:47:40Z","receivedAt":"2010-10-08T16:47:40Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Invoke ALLOC_GROW from cache.h instead of recaping its definition\nverbatim.  When this code was first written, the ALLOC_GROW macro\ndidn't exist yet; now that the macro does exist, it can make the\nsource a little shorter and more readable.\n\nNo functional change intended.\n\nSigned-off-by: Jonathan Nieder <jrnieder@gmail.com>\n---\n builtin/pack-objects.c |   15 ++++-----------\n 1 files changed, 4 insertions(+), 11 deletions(-)\n\ndiff --git a/builtin/pack-objects.c b/builtin/pack-objects.c\nindex 3756cf3..60b792d 100644\n--- a/builtin/pack-objects.c\n+++ b/builtin/pack-objects.c\n@@ -896,12 +896,9 @@ static int check_pbase_path(unsigned hash)\n \tif (0 <= pos)\n \t\treturn 1;\n \tpos = -pos - 1;\n-\tif (done_pbase_paths_alloc <= done_pbase_paths_num) {\n-\t\tdone_pbase_paths_alloc = alloc_nr(done_pbase_paths_alloc);\n-\t\tdone_pbase_paths = xrealloc(done_pbase_paths,\n-\t\t\t\t\t    done_pbase_paths_alloc *\n-\t\t\t\t\t    sizeof(unsigned));\n-\t}\n+\tALLOC_GROW(done_pbase_paths,\n+\t\t   done_pbase_paths_num + 1,\n+\t\t   done_pbase_paths_alloc);\n \tdone_pbase_paths_num++;\n \tif (pos < done_pbase_paths_num)\n \t\tmemmove(done_pbase_paths + pos + 1,\n@@ -2248,11 +2245,7 @@ int cmd_pack_objects(int argc, const char **argv, const char *prefix)\n \t\t    !strcmp(\"--reflog\", arg) ||\n \t\t    !strcmp(\"--all\", arg)) {\n \t\t\tuse_internal_rev_list = 1;\n-\t\t\tif (rp_ac >= rp_ac_alloc - 1) {\n-\t\t\t\trp_ac_alloc = alloc_nr(rp_ac_alloc);\n-\t\t\t\trp_av = xrealloc(rp_av,\n-\t\t\t\t\t\t rp_ac_alloc * sizeof(*rp_av));\n-\t\t\t}\n+\t\t\tALLOC_GROW(rp_av, rp_ac + 2, rp_ac_alloc);\n \t\t\trp_av[rp_ac++] = arg;\n \t\t\tcontinue;\n \t\t}\n-- \n1.7.2.3\n"},{"id":"152979","messageId":"20101008170224.GF9212@burratino","threadId":"25387","inReplyTo":"20101008164536.GB9212@burratino","subject":"[PATCH 3/2] Allow side-effects in second argument to ALLOC_GROW","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-08T17:02:24Z","receivedAt":"2010-10-08T17:02:24Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"One might be tempted to try\n\n\tALLOC_GROW(ary, ++nr, alloc);\n\nto increase the size of an array by one, and if one tries, the\ncompiler will happily accept it.  Unfortunately ALLOC_GROW evaluates\nits argument at least twice, so the results are generally not what the\ncaller wanted.\n\nLuckily, it is simple enough to do what the caller meant by storing\nthe value of the second argument in a temporary.\n\nThe first and third arguments still need to be side-effect-free.  The\nname of the temporary is nr_ to avoid conflicting with variables the\ncaller might use in the expansion of ary, nr, or alloc.\n\nSigned-off-by: Jonathan Nieder <jrnieder@gmail.com>\n---\n cache.h |    9 +++++----\n 1 files changed, 5 insertions(+), 4 deletions(-)\n\ndiff --git a/cache.h b/cache.h\nindex 23d6d45..5c9e338 100644\n--- a/cache.h\n+++ b/cache.h\n@@ -438,13 +438,14 @@ extern int init_db(const char *template_dir, unsigned int flags);\n  * at least 'nr' entries; the number of entries currently allocated\n  * is 'alloc', using the standard growing factor alloc_nr() macro.\n  *\n- * DO NOT USE any expression with side-effect for 'x', 'nr', or 'alloc'.\n+ * DO NOT USE any expression with side-effect for 'x' or 'alloc'.\n  */\n #define ALLOC_GROW(x, nr, alloc) \\\n \tdo { \\\n-\t\tif ((nr) > alloc) { \\\n-\t\t\tif (alloc_nr(alloc) < (nr)) \\\n-\t\t\t\talloc = (nr); \\\n+\t\tconst size_t nr_ = (nr); \\\n+\t\tif (nr_ > (alloc)) { \\\n+\t\t\tif (alloc_nr(alloc) < nr_) \\\n+\t\t\t\talloc = nr_; \\\n \t\t\telse \\\n \t\t\t\talloc = alloc_nr(alloc); \\\n \t\t\tx = xrealloc((x), alloc * sizeof(*(x))); \\\n-- \n1.7.2.3\n"},{"id":"152981","messageId":"1286559080-27257-1-git-send-email-stepnem@gmail.com","threadId":"25387","inReplyTo":"87fwwhszsf.fsf@gmail.com","subject":"[PATCH 0/6] Unify argument and option notation in the docs","fromName":"Štěpán Němec","fromEmail":"stepan.nemec@gmail.com","sentAt":"2010-10-08T17:31:14Z","receivedAt":"2010-10-08T17:31:14Z","isPatch":true,"sender":{"key":"stepnem@gmail.com","avatar":"https://avatars.githubusercontent.com/u/106838?v=4"},"body":"Other than splitting up the patch, the only change since the RFC version is\nhaving got rid of the GIT_* special cases in `git(1)' synopsis.\n\n[PATCH 1/6] Use angles for placeholders consistently\n[PATCH 2/6] Fix odd markup in --diff-filter documentation\n[PATCH 3/6] Use parentheses and `...' where appropriate\n[PATCH 4/6] Remove stray quotes in --pretty and --format documentation\n[PATCH 5/6] Put a space between `<' and argument in pack-objects usage string\n[PATCH 6/6] Fix {update,checkout}-index usage strings\n"},{"id":"152986","messageId":"1286559080-27257-2-git-send-email-stepnem@gmail.com","threadId":"25387","inReplyTo":"87fwwhszsf.fsf@gmail.com","subject":"[PATCH 1/6] Use angles for placeholders consistently","fromName":"Štěpán Němec","fromEmail":"stepan.nemec@gmail.com","sentAt":"2010-10-08T17:31:15Z","receivedAt":"2010-10-08T17:31:15Z","isPatch":true,"sender":{"key":"stepnem@gmail.com","avatar":"https://avatars.githubusercontent.com/u/106838?v=4"},"body":"\nSigned-off-by: Štěpán Němec <stepnem@gmail.com>\n---\n Documentation/diff-options.txt     |   10 +++---\n Documentation/git-apply.txt        |    4 +-\n Documentation/git-archive.txt      |    4 +-\n Documentation/git-bundle.txt       |    6 ++--\n Documentation/git-daemon.txt       |   48 ++++++++++++++++++------------------\n Documentation/git-fast-export.txt  |    2 +-\n Documentation/git-index-pack.txt   |    4 +-\n Documentation/git-ls-tree.txt      |   10 +++---\n Documentation/git-pack-objects.txt |   14 +++++-----\n Documentation/git-remote.txt       |    2 +-\n Documentation/git-repack.txt       |   12 ++++----\n Documentation/git-rev-list.txt     |   16 ++++++------\n Documentation/git-web--browse.txt  |   16 ++++++------\n Documentation/git.txt              |   12 ++++----\n Documentation/merge-strategies.txt |    2 +-\n Documentation/rev-list-options.txt |   16 ++++++------\n archive.c                          |    4 +-\n builtin/bundle.c                   |    4 +-\n builtin/grep.c                     |    2 +-\n builtin/ls-tree.c                  |    2 +-\n builtin/pack-objects.c             |    6 ++--\n builtin/remote.c                   |    2 +-\n builtin/rev-list.c                 |    8 +++---\n daemon.c                           |   18 ++++++------\n fast-import.c                      |    2 +-\n git.c                              |    8 +++---\n upload-pack.c                      |    2 +-\n 27 files changed, 118 insertions(+), 118 deletions(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex f77a0f8..cbf3c92 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -48,9 +48,9 @@ endif::git-format-patch[]\n --patience::\n \tGenerate a diff using the \"patience diff\" algorithm.\n \n---stat[=width[,name-width]]::\n+--stat[=<width>[,<name-width>]]::\n \tGenerate a diffstat.  You can override the default\n-\toutput width for 80-column terminal by `--stat=width`.\n+\toutput width for 80-column terminal by `--stat=<width>`.\n \tThe width of the filename part can be controlled by\n \tgiving another width to it separated by a comma.\n \n@@ -66,14 +66,14 @@ endif::git-format-patch[]\n \tnumber of modified files, as well as number of added and deleted\n \tlines.\n \n---dirstat[=limit]::\n+--dirstat[=<limit>]::\n \tOutput the distribution of relative amount of changes (number of lines added or\n \tremoved) for each sub-directory. Directories with changes below\n \ta cut-off percent (3% by default) are not shown. The cut-off percent\n-\tcan be set with `--dirstat=limit`. Changes in a child directory is not\n+\tcan be set with `--dirstat=<limit>`. Changes in a child directory are not\n \tcounted for the parent directory, unless `--cumulative` is used.\n \n---dirstat-by-file[=limit]::\n+--dirstat-by-file[=<limit>]::\n \tSame as `--dirstat`, but counts changed files instead of lines.\n \n --summary::\ndiff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt\nindex 4a74b23..08bf6e7 100644\n--- a/Documentation/git-apply.txt\n+++ b/Documentation/git-apply.txt\n@@ -12,10 +12,10 @@ SYNOPSIS\n 'git apply' [--stat] [--numstat] [--summary] [--check] [--index]\n \t  [--apply] [--no-add] [--build-fake-ancestor=<file>] [-R | --reverse]\n \t  [--allow-binary-replacement | --binary] [--reject] [-z]\n-\t  [-pNUM] [-CNUM] [--inaccurate-eof] [--recount] [--cached]\n+\t  [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached]\n \t  [--ignore-space-change | --ignore-whitespace ]\n \t  [--whitespace=<nowarn|warn|fix|error|error-all>]\n-\t  [--exclude=PATH] [--include=PATH] [--directory=<root>]\n+\t  [--exclude=<path>] [--include=<path>] [--directory=<root>]\n \t  [--verbose] [<patch>...]\n \n DESCRIPTION\ndiff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt\nindex 8d3e666..4163a1b 100644\n--- a/Documentation/git-archive.txt\n+++ b/Documentation/git-archive.txt\n@@ -12,7 +12,7 @@ SYNOPSIS\n 'git archive' [--format=<fmt>] [--list] [--prefix=<prefix>/] [<extra>]\n \t      [-o | --output=<file>] [--worktree-attributes]\n \t      [--remote=<repo> [--exec=<git-upload-archive>]] <tree-ish>\n-\t      [path...]\n+\t      [<path>...]\n \n DESCRIPTION\n -----------\n@@ -73,7 +73,7 @@ OPTIONS\n <tree-ish>::\n \tThe tree or commit to produce an archive for.\n \n-path::\n+<path>::\n \tWithout an optional path parameter, all files and subdirectories\n \tof the current working directory are included in the archive.\n \tIf one or more paths are specified, only these are included.\ndiff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt\nindex 38e59af..6266a3a 100644\n--- a/Documentation/git-bundle.txt\n+++ b/Documentation/git-bundle.txt\n@@ -11,8 +11,8 @@ SYNOPSIS\n [verse]\n 'git bundle' create <file> <git-rev-list-args>\n 'git bundle' verify <file>\n-'git bundle' list-heads <file> [refname...]\n-'git bundle' unbundle <file> [refname...]\n+'git bundle' list-heads <file> [<refname>...]\n+'git bundle' unbundle <file> [<refname>...]\n \n DESCRIPTION\n -----------\n@@ -68,7 +68,7 @@ unbundle <file>::\n \tpackaged.\n \n \n-[refname...]::\n+[<refname>...]::\n \tA list of references used to limit the references reported as\n \tavailable. This is principally of use to 'git fetch', which\n \texpects to receive only those references asked for and not\ndiff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt\nindex 01c9f8e..2f0ddf6 100644\n--- a/Documentation/git-daemon.txt\n+++ b/Documentation/git-daemon.txt\n@@ -9,15 +9,15 @@ SYNOPSIS\n --------\n [verse]\n 'git daemon' [--verbose] [--syslog] [--export-all]\n-\t     [--timeout=n] [--init-timeout=n] [--max-connections=n]\n-\t     [--strict-paths] [--base-path=path] [--base-path-relaxed]\n-\t     [--user-path | --user-path=path]\n-\t     [--interpolated-path=pathtemplate]\n-\t     [--reuseaddr] [--detach] [--pid-file=file]\n-\t     [--enable=service] [--disable=service]\n-\t     [--allow-override=service] [--forbid-override=service]\n-\t     [--inetd | [--listen=host_or_ipaddr] [--port=n] [--user=user [--group=group]]\n-\t     [directory...]\n+\t     [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>]\n+\t     [--strict-paths] [--base-path=<path>] [--base-path-relaxed]\n+\t     [--user-path | --user-path=<path>]\n+\t     [--interpolated-path=<pathtemplate>]\n+\t     [--reuseaddr] [--detach] [--pid-file=<file>]\n+\t     [--enable=<service>] [--disable=<service>]\n+\t     [--allow-override=<service>] [--forbid-override=<service>]\n+\t     [--inetd | [--listen=<host_or_ipaddr>] [--port=<n>] [--user=<user> [--group=<group>]]\n+\t     [<directory>...]\n \n DESCRIPTION\n -----------\n@@ -48,7 +48,7 @@ OPTIONS\n \t'git daemon' will refuse to start when this option is enabled and no\n \twhitelist is specified.\n \n---base-path=path::\n+--base-path=<path>::\n \tRemap all the path requests as relative to the given path.\n \tThis is sort of \"GIT root\" - if you run 'git daemon' with\n \t'--base-path=/srv/git' on example.com, then if you later try to pull\n@@ -61,7 +61,7 @@ OPTIONS\n \tThis is useful for switching to --base-path usage, while still\n \tallowing the old paths.\n \n---interpolated-path=pathtemplate::\n+--interpolated-path=<pathtemplate>::\n \tTo support virtual hosting, an interpolated path template can be\n \tused to dynamically construct alternate paths.  The template\n \tsupports %H for the target hostname as supplied by the client but\n@@ -80,27 +80,27 @@ OPTIONS\n \tHave the server run as an inetd service. Implies --syslog.\n \tIncompatible with --port, --listen, --user and --group options.\n \n---listen=host_or_ipaddr::\n+--listen=<host_or_ipaddr>::\n \tListen on a specific IP address or hostname.  IP addresses can\n \tbe either an IPv4 address or an IPv6 address if supported.  If IPv6\n \tis not supported, then --listen=hostname is also not supported and\n \t--listen must be given an IPv4 address.\n \tIncompatible with '--inetd' option.\n \n---port=n::\n+--port=<n>::\n \tListen on an alternative port.  Incompatible with '--inetd' option.\n \n---init-timeout=n::\n+--init-timeout=<n>::\n \tTimeout between the moment the connection is established and the\n \tclient request is received (typically a rather low value, since\n \tthat should be basically immediate).\n \n---timeout=n::\n+--timeout=<n>::\n \tTimeout for specific client sub-requests. This includes the time\n \tit takes for the server to process the sub-request and the time spent\n \twaiting for the next client's request.\n \n---max-connections=n::\n+--max-connections=<n>::\n \tMaximum number of concurrent clients, defaults to 32.  Set it to\n \tzero for no limit.\n \n@@ -109,7 +109,7 @@ OPTIONS\n \t--verbose, thus by default only error conditions will be logged.\n \n --user-path::\n---user-path=path::\n+--user-path=<path>::\n \tAllow {tilde}user notation to be used in requests.  When\n \tspecified with no parameter, requests to\n \tgit://host/{tilde}alice/foo is taken as a request to access\n@@ -129,12 +129,12 @@ OPTIONS\n --detach::\n \tDetach from the shell. Implies --syslog.\n \n---pid-file=file::\n+--pid-file=<file>::\n \tSave the process id in 'file'.  Ignored when the daemon\n \tis run under `--inetd`.\n \n---user=user::\n---group=group::\n+--user=<user>::\n+--group=<group>::\n \tChange daemon's uid and gid before entering the service loop.\n \tWhen only `--user` is given without `--group`, the\n \tprimary group ID for the user is used.  The values of\n@@ -145,16 +145,16 @@ Giving these options is an error when used with `--inetd`; use\n the facility of inet daemon to achieve the same before spawning\n 'git daemon' if needed.\n \n---enable=service::\n---disable=service::\n+--enable=<service>::\n+--disable=<service>::\n \tEnable/disable the service site-wide per default.  Note\n \tthat a service disabled site-wide can still be enabled\n \tper repository if it is marked overridable and the\n \trepository enables the service with a configuration\n \titem.\n \n---allow-override=service::\n---forbid-override=service::\n+--allow-override=<service>::\n+--forbid-override=<service>::\n \tAllow/forbid overriding the site-wide default with per\n \trepository configuration.  By default, all the services\n \tare overridable.\ndiff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt\nindex fcad113..e05b686 100644\n--- a/Documentation/git-fast-export.txt\n+++ b/Documentation/git-fast-export.txt\n@@ -96,7 +96,7 @@ marks the same across runs.\n \tin the commit (as opposed to just listing the files which are\n \tdifferent from the commit's first parent).\n \n-[git-rev-list-args...]::\n+[<git-rev-list-args>...]::\n        A list of arguments, acceptable to 'git rev-parse' and\n        'git rev-list', that specifies the specific objects and references\n        to export.  For example, `master{tilde}10..master` causes the\ndiff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt\nindex f3ccc72..c2bb810 100644\n--- a/Documentation/git-index-pack.txt\n+++ b/Documentation/git-index-pack.txt\n@@ -59,10 +59,10 @@ OPTIONS\n \tthe newly constructed pack and index before refs can be\n \tupdated to use objects contained in the pack.\n \n---keep='why'::\n+--keep=<msg>::\n \tLike --keep create a .keep file before moving the index into\n \tits final destination, but rather than creating an empty file\n-\tplace 'why' followed by an LF into the .keep file.  The 'why'\n+\tplace '<msg>' followed by an LF into the .keep file.  The '<msg>'\n \tmessage can later be searched for within all .keep files to\n \tlocate any which have outlived their usefulness.\n \ndiff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt\nindex 1f89d36..76ed625 100644\n--- a/Documentation/git-ls-tree.txt\n+++ b/Documentation/git-ls-tree.txt\n@@ -10,8 +10,8 @@ SYNOPSIS\n --------\n [verse]\n 'git ls-tree' [-d] [-r] [-t] [-l] [-z]\n-\t    [--name-only] [--name-status] [--full-name] [--full-tree] [--abbrev=[<n>]]\n-\t    <tree-ish> [paths...]\n+\t    [--name-only] [--name-status] [--full-name] [--full-tree] [--abbrev[=<n>]]\n+\t    <tree-ish> [<path>...]\n \n DESCRIPTION\n -----------\n@@ -19,11 +19,11 @@ Lists the contents of a given tree object, like what \"/bin/ls -a\" does\n in the current working directory.  Note that:\n \n  - the behaviour is slightly different from that of \"/bin/ls\" in that the\n-   'paths' denote just a list of patterns to match, e.g. so specifying\n+   '<path>' denotes just a list of patterns to match, e.g. so specifying\n    directory name (without '-r') will behave differently, and order of the\n    arguments does not matter.\n \n- - the behaviour is similar to that of \"/bin/ls\" in that the 'paths' is\n+ - the behaviour is similar to that of \"/bin/ls\" in that the '<path>' is\n    taken as relative to the current working directory.  E.g. when you are\n    in a directory 'sub' that has a directory 'dir', you can run 'git\n    ls-tree -r HEAD dir' to list the contents of the tree (that is\n@@ -72,7 +72,7 @@ OPTIONS\n \tDo not limit the listing to the current working directory.\n \tImplies --full-name.\n \n-paths::\n+[<path>...]::\n \tWhen paths are given, show them (note that this isn't really raw\n \tpathnames, but rather a list of patterns to match).  Otherwise\n \timplicitly uses the root level of the tree as the sole path argument.\ndiff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt\nindex 8ed09c0..a1dd3e9 100644\n--- a/Documentation/git-pack-objects.txt\n+++ b/Documentation/git-pack-objects.txt\n@@ -11,7 +11,7 @@ SYNOPSIS\n [verse]\n 'git pack-objects' [-q | --progress | --all-progress] [--all-progress-implied]\n \t[--no-reuse-delta] [--delta-base-offset] [--non-empty]\n-\t[--local] [--incremental] [--window=N] [--depth=N]\n+\t[--local] [--incremental] [--window=<n>] [--depth=<n>]\n \t[--revs [--unpacked | --all]*] [--stdout | base-name]\n \t[--keep-true-parents] < object-list\n \n@@ -82,8 +82,8 @@ base-name::\n \treference was included in the resulting packfile.  This\n \tcan be useful to send new tags to native git clients.\n \n---window=[N]::\n---depth=[N]::\n+--window=<n>::\n+--depth=<n>::\n \tThese two options affect how the objects contained in\n \tthe pack are stored using delta compression.  The\n \tobjects are first internally sorted by type, size and\n@@ -95,10 +95,10 @@ base-name::\n \ttimes to get to the necessary object.\n \tThe default value for --window is 10 and --depth is 50.\n \n---window-memory=[N]::\n+--window-memory=<n>::\n \tThis option provides an additional limit on top of `--window`;\n \tthe window size will dynamically scale down so as to not take\n-\tup more than N bytes in memory.  This is useful in\n+\tup more than '<n>' bytes in memory.  This is useful in\n \trepositories with a mix of large and small objects to not run\n \tout of memory with a large window, but still be able to take\n \tadvantage of the large window for the smaller objects.  The\n@@ -106,7 +106,7 @@ base-name::\n \t`--window-memory=0` makes memory usage unlimited, which is the\n \tdefault.\n \n---max-pack-size=[N]::\n+--max-pack-size=<n>::\n \tMaximum size of each output pack file. The size can be suffixed with\n \t\"k\", \"m\", or \"g\". The minimum size allowed is limited to 1 MiB.\n \tIf specified,  multiple packfiles may be created.\n@@ -171,7 +171,7 @@ base-name::\n \twholesale enforcement of a different compression level on the\n \tpacked data is desired.\n \n---compression=[N]::\n+--compression=<n>::\n \tSpecifies compression level for newly-compressed data in the\n \tgenerated pack.  If not specified,  pack compression level is\n \tdetermined first by pack.compression,  then by core.compression,\ndiff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt\nindex aa021b0..b317086 100644\n--- a/Documentation/git-remote.txt\n+++ b/Documentation/git-remote.txt\n@@ -20,7 +20,7 @@ SYNOPSIS\n 'git remote set-url --delete' [--push] <name> <url>\n 'git remote' [-v | --verbose] 'show' [-n] <name>\n 'git remote prune' [-n | --dry-run] <name>\n-'git remote' [-v | --verbose] 'update' [-p | --prune] [group | remote]...\n+'git remote' [-v | --verbose] 'update' [-p | --prune] [<group> | <remote>]...\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt\nindex 9566727..27f7865 100644\n--- a/Documentation/git-repack.txt\n+++ b/Documentation/git-repack.txt\n@@ -8,7 +8,7 @@ git-repack - Pack unpacked objects in a repository\n \n SYNOPSIS\n --------\n-'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [--window=N] [--depth=N]\n+'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [--window=<n>] [--depth=<n>]\n \n DESCRIPTION\n -----------\n@@ -80,8 +80,8 @@ other objects in that pack they already have locally.\n \tthis repository (or a direct copy of it)\n \tover HTTP or FTP.  See linkgit:git-update-server-info[1].\n \n---window=[N]::\n---depth=[N]::\n+--window=<n>::\n+--depth=<n>::\n \tThese two options affect how the objects contained in the pack are\n \tstored using delta compression. The objects are first internally\n \tsorted by type, size and optionally names and compared against the\n@@ -91,10 +91,10 @@ other objects in that pack they already have locally.\n \tto be applied that many times to get to the necessary object.\n \tThe default value for --window is 10 and --depth is 50.\n \n---window-memory=[N]::\n+--window-memory=<n>::\n \tThis option provides an additional limit on top of `--window`;\n \tthe window size will dynamically scale down so as to not take\n-\tup more than N bytes in memory.  This is useful in\n+\tup more than '<n>' bytes in memory.  This is useful in\n \trepositories with a mix of large and small objects to not run\n \tout of memory with a large window, but still be able to take\n \tadvantage of the large window for the smaller objects.  The\n@@ -102,7 +102,7 @@ other objects in that pack they already have locally.\n \t`--window-memory=0` makes memory usage unlimited, which is the\n \tdefault.\n \n---max-pack-size=[N]::\n+--max-pack-size=<n>::\n \tMaximum size of each output pack file. The size can be suffixed with\n \t\"k\", \"m\", or \"g\". The minimum size allowed is limited to 1 MiB.\n \tIf specified,  multiple packfiles may be created.\ndiff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt\nindex 173f3fc..cfb1d21 100644\n--- a/Documentation/git-rev-list.txt\n+++ b/Documentation/git-rev-list.txt\n@@ -9,10 +9,10 @@ git-rev-list - Lists commit objects in reverse chronological order\n SYNOPSIS\n --------\n [verse]\n-'git rev-list' [ \\--max-count=number ]\n-\t     [ \\--skip=number ]\n-\t     [ \\--max-age=timestamp ]\n-\t     [ \\--min-age=timestamp ]\n+'git rev-list' [ \\--max-count=<number> ]\n+\t     [ \\--skip=<number> ]\n+\t     [ \\--max-age=<timestamp> ]\n+\t     [ \\--min-age=<timestamp> ]\n \t     [ \\--sparse ]\n \t     [ \\--merges ]\n \t     [ \\--no-merges ]\n@@ -21,10 +21,10 @@ SYNOPSIS\n \t     [ \\--full-history ]\n \t     [ \\--not ]\n \t     [ \\--all ]\n-\t     [ \\--branches[=pattern] ]\n-\t     [ \\--tags[=pattern] ]\n-\t     [ \\--remotes[=pattern] ]\n-\t     [ \\--glob=glob-pattern ]\n+\t     [ \\--branches[=<pattern>] ]\n+\t     [ \\--tags[=<pattern>] ]\n+\t     [ \\--remotes[=<pattern>] ]\n+\t     [ \\--glob=<glob-pattern> ]\n \t     [ \\--stdin ]\n \t     [ \\--quiet ]\n \t     [ \\--topo-order ]\ndiff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt\nindex e1586c7..51e8e0a 100644\n--- a/Documentation/git-web--browse.txt\n+++ b/Documentation/git-web--browse.txt\n@@ -32,19 +32,19 @@ Custom commands may also be specified.\n \n OPTIONS\n -------\n--b BROWSER::\n---browser=BROWSER::\n-\tUse the specified BROWSER. It must be in the list of supported\n+-b <browser>::\n+--browser=<browser>::\n+\tUse the specified browser. It must be in the list of supported\n \tbrowsers.\n \n--t BROWSER::\n---tool=BROWSER::\n+-t <browser>::\n+--tool=<browser>::\n \tSame as above.\n \n--c CONF.VAR::\n---config=CONF.VAR::\n+-c <conf.var>::\n+--config=<conf.var>::\n \tCONF.VAR is looked up in the git config files. If it's set,\n-\tthen its value specify the browser that should be used.\n+\tthen its value specifies the browser that should be used.\n \n CONFIGURATION VARIABLES\n -----------------------\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex dd57bdc..8de8617 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -9,11 +9,11 @@ git - the stupid content tracker\n SYNOPSIS\n --------\n [verse]\n-'git' [--version] [--exec-path[=GIT_EXEC_PATH]] [--html-path]\n+'git' [--version] [--exec-path[=<path>]] [--html-path]\n     [-p|--paginate|--no-pager] [--no-replace-objects]\n-    [--bare] [--git-dir=GIT_DIR] [--work-tree=GIT_WORK_TREE]\n-    [-c name=value]\n-    [--help] COMMAND [ARGS]\n+    [--bare] [--git-dir=<path>] [--work-tree=<path>]\n+    [-c <name>=<value>]\n+    [--help] <command> [<args>]\n \n DESCRIPTION\n -----------\n@@ -28,7 +28,7 @@ also want to read linkgit:gitcvs-migration[7].  See\n the link:user-manual.html[Git User's Manual] for a more in-depth\n introduction.\n \n-The COMMAND is either a name of a Git command (see below) or an alias\n+The '<command>' is either a name of a Git command (see below) or an alias\n as defined in the configuration file (see linkgit:git-config[1]).\n \n Formatted and hyperlinked version of the latest git\n@@ -252,7 +252,7 @@ help ...`.\n \tThe <name> is expected in the same format as listed by\n \t'git config' (subkeys separated by dots).\n \n---exec-path::\n+--exec-path[=<path>]::\n \tPath to wherever your core git programs are installed.\n \tThis can also be controlled by setting the GIT_EXEC_PATH\n \tenvironment variable. If no path is given, 'git' will print\ndiff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt\nindex 049313d..8676e26 100644\n--- a/Documentation/merge-strategies.txt\n+++ b/Documentation/merge-strategies.txt\n@@ -52,7 +52,7 @@ no-renormalize;;\n \tDisables the `renormalize` option.  This overrides the\n \t`merge.renormalize` configuration variable.\n \n-subtree[=path];;\n+subtree[=<path>];;\n \tThis option is a more advanced form of 'subtree' strategy, where\n \tthe strategy makes a guess on how two trees must be shifted to\n \tmatch with each other when merging.  Instead, the specified path\ndiff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt\nindex ebc0108..1b13c1f 100644\n--- a/Documentation/rev-list-options.txt\n+++ b/Documentation/rev-list-options.txt\n@@ -246,29 +246,29 @@ endif::git-rev-list[]\n \tPretend as if all the refs in `refs/` are listed on the\n \tcommand line as '<commit>'.\n \n---branches[=pattern]::\n+--branches[=<pattern>]::\n \n \tPretend as if all the refs in `refs/heads` are listed\n-\ton the command line as '<commit>'. If `pattern` is given, limit\n+\ton the command line as '<commit>'. If '<pattern>' is given, limit\n \tbranches to ones matching given shell glob. If pattern lacks '?',\n \t'*', or '[', '/*' at the end is implied.\n \n---tags[=pattern]::\n+--tags[=<pattern>]::\n \n \tPretend as if all the refs in `refs/tags` are listed\n-\ton the command line as '<commit>'. If `pattern` is given, limit\n+\ton the command line as '<commit>'. If '<pattern>' is given, limit\n \ttags to ones matching given shell glob. If pattern lacks '?', '*',\n \tor '[', '/*' at the end is implied.\n \n---remotes[=pattern]::\n+--remotes[=<pattern>]::\n \n \tPretend as if all the refs in `refs/remotes` are listed\n-\ton the command line as '<commit>'. If `pattern`is given, limit\n+\ton the command line as '<commit>'. If '<pattern>' is given, limit\n \tremote tracking branches to ones matching given shell glob.\n \tIf pattern lacks '?', '*', or '[', '/*' at the end is implied.\n \n---glob=glob-pattern::\n-\tPretend as if all the refs matching shell glob `glob-pattern`\n+--glob=<glob-pattern>::\n+\tPretend as if all the refs matching shell glob '<glob-pattern>'\n \tare listed on the command line as '<commit>'. Leading 'refs/',\n \tis automatically prepended if missing. If pattern lacks '?', '*',\n \tor '[', '/*' at the end is implied.\ndiff --git a/archive.c b/archive.c\nindex edd6853..f59afda 100644\n--- a/archive.c\n+++ b/archive.c\n@@ -7,9 +7,9 @@\n #include \"unpack-trees.h\"\n \n static char const * const archive_usage[] = {\n-\t\"git archive [options] <tree-ish> [path...]\",\n+\t\"git archive [options] <tree-ish> [<path>...]\",\n \t\"git archive --list\",\n-\t\"git archive --remote <repo> [--exec <cmd>] [options] <tree-ish> [path...]\",\n+\t\"git archive --remote <repo> [--exec <cmd>] [options] <tree-ish> [<path>...]\",\n \t\"git archive --remote <repo> [--exec <cmd>] --list\",\n \tNULL\n };\ndiff --git a/builtin/bundle.c b/builtin/bundle.c\nindex 80649ba..9b87fb9 100644\n--- a/builtin/bundle.c\n+++ b/builtin/bundle.c\n@@ -12,8 +12,8 @@\n static const char builtin_bundle_usage[] =\n   \"git bundle create <file> <git-rev-list args>\\n\"\n   \"   or: git bundle verify <file>\\n\"\n-  \"   or: git bundle list-heads <file> [refname...]\\n\"\n-  \"   or: git bundle unbundle <file> [refname...]\";\n+  \"   or: git bundle list-heads <file> [<refname>...]\\n\"\n+  \"   or: git bundle unbundle <file> [<refname>...]\";\n \n int cmd_bundle(int argc, const char **argv, const char *prefix)\n {\ndiff --git a/builtin/grep.c b/builtin/grep.c\nindex da32f3d..3d5f6ac 100644\n--- a/builtin/grep.c\n+++ b/builtin/grep.c\n@@ -24,7 +24,7 @@\n #endif\n \n static char const * const grep_usage[] = {\n-\t\"git grep [options] [-e] <pattern> [<rev>...] [[--] path...]\",\n+\t\"git grep [options] [-e] <pattern> [<rev>...] [[--] <path>...]\",\n \tNULL\n };\n \ndiff --git a/builtin/ls-tree.c b/builtin/ls-tree.c\nindex a818756..f73e6bd 100644\n--- a/builtin/ls-tree.c\n+++ b/builtin/ls-tree.c\n@@ -24,7 +24,7 @@ static int chomp_prefix;\n static const char *ls_tree_prefix;\n \n static const  char * const ls_tree_usage[] = {\n-\t\"git ls-tree [<options>] <tree-ish> [path...]\",\n+\t\"git ls-tree [<options>] <tree-ish> [<path>...]\",\n \tNULL\n };\n \ndiff --git a/builtin/pack-objects.c b/builtin/pack-objects.c\nindex d5a8db1..1e4c386 100644\n--- a/builtin/pack-objects.c\n+++ b/builtin/pack-objects.c\n@@ -25,10 +25,10 @@\n static const char pack_usage[] =\n   \"git pack-objects [{ -q | --progress | --all-progress }]\\n\"\n   \"        [--all-progress-implied]\\n\"\n-  \"        [--max-pack-size=N] [--local] [--incremental]\\n\"\n-  \"        [--window=N] [--window-memory=N] [--depth=N]\\n\"\n+  \"        [--max-pack-size=<n>] [--local] [--incremental]\\n\"\n+  \"        [--window=<n>] [--window-memory=<n>] [--depth=<n>]\\n\"\n   \"        [--no-reuse-delta] [--no-reuse-object] [--delta-base-offset]\\n\"\n-  \"        [--threads=N] [--non-empty] [--revs [--unpacked | --all]*]\\n\"\n+  \"        [--threads=<n>] [--non-empty] [--revs [--unpacked | --all]]\\n\"\n   \"        [--reflog] [--stdout | base-name] [--include-tag]\\n\"\n   \"        [--keep-unreachable | --unpack-unreachable]\\n\"\n   \"        [<ref-list | <object-list]\";\ndiff --git a/builtin/remote.c b/builtin/remote.c\nindex 48e0a6b..c0198fc 100644\n--- a/builtin/remote.c\n+++ b/builtin/remote.c\n@@ -15,7 +15,7 @@ static const char * const builtin_remote_usage[] = {\n \t\"git remote set-head <name> (-a | -d | <branch>)\",\n \t\"git remote [-v | --verbose] show [-n] <name>\",\n \t\"git remote prune [-n | --dry-run] <name>\",\n-\t\"git remote [-v | --verbose] update [-p | --prune] [group | remote]\",\n+\t\"git remote [-v | --verbose] update [-p | --prune] [<group> | <remote>]\",\n \t\"git remote set-branches <name> [--add] <branch>...\",\n \t\"git remote set-url <name> <newurl> [<oldurl>]\",\n \t\"git remote set-url --add <name> <newurl>\",\ndiff --git a/builtin/rev-list.c b/builtin/rev-list.c\nindex efe9360..158ce11 100644\n--- a/builtin/rev-list.c\n+++ b/builtin/rev-list.c\n@@ -11,9 +11,9 @@\n static const char rev_list_usage[] =\n \"git rev-list [OPTION] <commit-id>... [ -- paths... ]\\n\"\n \"  limiting output:\\n\"\n-\"    --max-count=nr\\n\"\n-\"    --max-age=epoch\\n\"\n-\"    --min-age=epoch\\n\"\n+\"    --max-count=<n>\\n\"\n+\"    --max-age=<epoch>\\n\"\n+\"    --min-age=<epoch>\\n\"\n \"    --sparse\\n\"\n \"    --no-merges\\n\"\n \"    --remove-empty\\n\"\n@@ -33,7 +33,7 @@ static const char rev_list_usage[] =\n \"    --objects | --objects-edge\\n\"\n \"    --unpacked\\n\"\n \"    --header | --pretty\\n\"\n-\"    --abbrev=nr | --no-abbrev\\n\"\n+\"    --abbrev=<n> | --no-abbrev\\n\"\n \"    --abbrev-commit\\n\"\n \"    --left-right\\n\"\n \"  special purpose:\\n\"\ndiff --git a/daemon.c b/daemon.c\nindex e22a2b7..9326d3a 100644\n--- a/daemon.c\n+++ b/daemon.c\n@@ -20,15 +20,15 @@ static int reuseaddr;\n \n static const char daemon_usage[] =\n \"git daemon [--verbose] [--syslog] [--export-all]\\n\"\n-\"           [--timeout=n] [--init-timeout=n] [--max-connections=n]\\n\"\n-\"           [--strict-paths] [--base-path=path] [--base-path-relaxed]\\n\"\n-\"           [--user-path | --user-path=path]\\n\"\n-\"           [--interpolated-path=path]\\n\"\n-\"           [--reuseaddr] [--detach] [--pid-file=file]\\n\"\n-\"           [--[enable|disable|allow-override|forbid-override]=service]\\n\"\n-\"           [--inetd | [--listen=host_or_ipaddr] [--port=n]\\n\"\n-\"                      [--user=user [--group=group]]\\n\"\n-\"           [directory...]\";\n+\"           [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>]\\n\"\n+\"           [--strict-paths] [--base-path=<path>] [--base-path-relaxed]\\n\"\n+\"           [--user-path | --user-path=<path>]\\n\"\n+\"           [--interpolated-path=<path>]\\n\"\n+\"           [--reuseaddr] [--detach] [--pid-file=<file>]\\n\"\n+\"           [--(enable|disable|allow-override|forbid-override)=<service>]\\n\"\n+\"           [--inetd | [--listen=<host_or_ipaddr>] [--port=<n>]\\n\"\n+\"                      [--user=<user> [--group=<group>]]\\n\"\n+\"           [<directory>...]\";\n \n /* List of acceptable pathname prefixes */\n static char **ok_paths;\ndiff --git a/fast-import.c b/fast-import.c\nindex 2317b0f..eab68d5 100644\n--- a/fast-import.c\n+++ b/fast-import.c\n@@ -2884,7 +2884,7 @@ static int git_pack_config(const char *k, const char *v, void *cb)\n }\n \n static const char fast_import_usage[] =\n-\"git fast-import [--date-format=f] [--max-pack-size=n] [--big-file-threshold=n] [--depth=n] [--active-branches=n] [--export-marks=marks.file]\";\n+\"git fast-import [--date-format=<f>] [--max-pack-size=<n>] [--big-file-threshold=<n>] [--depth=<n>] [--active-branches=<n>] [--export-marks=<marks.file>]\";\n \n static void parse_argv(void)\n {\ndiff --git a/git.c b/git.c\nindex 50a1401..0409ac9 100644\n--- a/git.c\n+++ b/git.c\n@@ -6,14 +6,14 @@\n #include \"run-command.h\"\n \n const char git_usage_string[] =\n-\t\"git [--version] [--exec-path[=GIT_EXEC_PATH]] [--html-path]\\n\"\n+\t\"git [--version] [--exec-path[=<path>]] [--html-path]\\n\"\n \t\"           [-p|--paginate|--no-pager] [--no-replace-objects]\\n\"\n-\t\"           [--bare] [--git-dir=GIT_DIR] [--work-tree=GIT_WORK_TREE]\\n\"\n+\t\"           [--bare] [--git-dir=<path>] [--work-tree=<path>]\\n\"\n \t\"           [-c name=value] [--help]\\n\"\n-\t\"           COMMAND [ARGS]\";\n+\t\"           <command> [<args>]\";\n \n const char git_more_info_string[] =\n-\t\"See 'git help COMMAND' for more information on a specific command.\";\n+\t\"See 'git help <command>' for more information on a specific command.\";\n \n static struct startup_info git_startup_info;\n static int use_pager = -1;\ndiff --git a/upload-pack.c b/upload-pack.c\nindex 92f9530..f05e422 100644\n--- a/upload-pack.c\n+++ b/upload-pack.c\n@@ -11,7 +11,7 @@\n #include \"list-objects.h\"\n #include \"run-command.h\"\n \n-static const char upload_pack_usage[] = \"git upload-pack [--strict] [--timeout=nn] <dir>\";\n+static const char upload_pack_usage[] = \"git upload-pack [--strict] [--timeout=<n>] <dir>\";\n \n /* bits #0..7 in revision.h, #8..10 in commit.c */\n #define THEY_HAVE\t(1u << 11)\n-- \n1.7.3.rc2.221.gbf93f.dirty\n"},{"id":"152982","messageId":"1286559080-27257-3-git-send-email-stepnem@gmail.com","threadId":"25387","inReplyTo":"87fwwhszsf.fsf@gmail.com","subject":"[PATCH 2/6] Fix odd markup in --diff-filter documentation","fromName":"Štěpán Němec","fromEmail":"stepan.nemec@gmail.com","sentAt":"2010-10-08T17:31:16Z","receivedAt":"2010-10-08T17:31:16Z","isPatch":true,"sender":{"key":"stepnem@gmail.com","avatar":"https://avatars.githubusercontent.com/u/106838?v=4"},"body":"Use a `<spec>' placeholder instead of the regex-like bracket expression\nto make it more consistent with other similar places.\n\nSigned-off-by: Štěpán Němec <stepnem@gmail.com>\n---\n Documentation/diff-options.txt |    4 ++--\n 1 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex cbf3c92..719f589 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -248,13 +248,13 @@ endif::git-log[]\n \tIf `n` is specified, it has the same meaning as for `-M<n>`.\n \n ifndef::git-format-patch[]\n---diff-filter=[ACDMRTUXB*]::\n+--diff-filter=<spec>::\n+\t'<spec>' can be any combination of the characters `ACDMRTUXB*`.\n \tSelect only files that are Added (`A`), Copied (`C`),\n \tDeleted (`D`), Modified (`M`), Renamed (`R`), have their\n \ttype (i.e. regular file, symlink, submodule, ...) changed (`T`),\n \tare Unmerged (`U`), are\n \tUnknown (`X`), or have had their pairing Broken (`B`).\n-\tAny combination of the filter characters may be used.\n \tWhen `*` (All-or-none) is added to the combination, all\n \tpaths are selected if there is any file that matches\n \tother criteria in the comparison; if there is no file\n-- \n1.7.3.rc2.221.gbf93f.dirty\n"},{"id":"152984","messageId":"1286559080-27257-4-git-send-email-stepnem@gmail.com","threadId":"25387","inReplyTo":"87fwwhszsf.fsf@gmail.com","subject":"[PATCH 3/6] Use parentheses and `...' where appropriate","fromName":"Štěpán Němec","fromEmail":"stepan.nemec@gmail.com","sentAt":"2010-10-08T17:31:17Z","receivedAt":"2010-10-08T17:31:17Z","isPatch":true,"sender":{"key":"stepnem@gmail.com","avatar":"https://avatars.githubusercontent.com/u/106838?v=4"},"body":"Remove some stray usage of other bracket types and asterisks for the\nsame purpose.\n\nSigned-off-by: Štěpán Němec <stepnem@gmail.com>\n---\n Documentation/git-am.txt             |    4 ++--\n Documentation/git-apply.txt          |    2 +-\n Documentation/git-checkout-index.txt |    2 +-\n Documentation/git-commit-tree.txt    |    2 +-\n Documentation/git-fetch.txt          |    2 +-\n Documentation/git-filter-branch.txt  |    2 +-\n Documentation/git-for-each-ref.txt   |    2 +-\n Documentation/git-init.txt           |    2 +-\n Documentation/git-ls-files.txt       |    2 +-\n Documentation/git-mailsplit.txt      |    2 +-\n Documentation/git-mergetool.txt      |    2 +-\n Documentation/git-pack-objects.txt   |    2 +-\n Documentation/git-relink.txt         |    2 +-\n Documentation/git-remote.txt         |    2 +-\n Documentation/git-rev-list.txt       |    2 +-\n Documentation/git-rev-parse.txt      |    2 +-\n Documentation/git-show-branch.txt    |    2 +-\n Documentation/git-svn.txt            |    2 +-\n Documentation/git-update-index.txt   |    4 ++--\n Documentation/rev-list-options.txt   |    2 +-\n Documentation/user-manual.txt        |    2 +-\n builtin/commit-tree.c                |    2 +-\n builtin/fetch.c                      |    2 +-\n builtin/index-pack.c                 |    2 +-\n builtin/ls-files.c                   |    2 +-\n builtin/mailsplit.c                  |    2 +-\n builtin/pack-objects.c               |    2 +-\n builtin/remote.c                     |    2 +-\n builtin/show-branch.c                |    2 +-\n git-am.sh                            |    2 +-\n git-relink.perl                      |    2 +-\n 31 files changed, 33 insertions(+), 33 deletions(-)\n\ndiff --git a/Documentation/git-am.txt b/Documentation/git-am.txt\nindex 9e62f87..51297d0 100644\n--- a/Documentation/git-am.txt\n+++ b/Documentation/git-am.txt\n@@ -14,7 +14,7 @@ SYNOPSIS\n \t [--ignore-date] [--ignore-space-change | --ignore-whitespace]\n \t [--whitespace=<option>] [-C<n>] [-p<n>] [--directory=<dir>]\n \t [--reject] [-q | --quiet] [--scissors | --no-scissors]\n-\t [<mbox> | <Maildir>...]\n+\t [(<mbox> | <Maildir>)...]\n 'git am' (--continue | --skip | --abort)\n \n DESCRIPTION\n@@ -25,7 +25,7 @@ current branch.\n \n OPTIONS\n -------\n-<mbox>|<Maildir>...::\n+(<mbox>|<Maildir>)...::\n \tThe list of mailbox files to read patches from. If you do not\n \tsupply this argument, the command reads from the standard input.\n \tIf you supply directories, they will be treated as Maildirs.\ndiff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt\nindex 08bf6e7..881652f 100644\n--- a/Documentation/git-apply.txt\n+++ b/Documentation/git-apply.txt\n@@ -14,7 +14,7 @@ SYNOPSIS\n \t  [--allow-binary-replacement | --binary] [--reject] [-z]\n \t  [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached]\n \t  [--ignore-space-change | --ignore-whitespace ]\n-\t  [--whitespace=<nowarn|warn|fix|error|error-all>]\n+\t  [--whitespace=(nowarn|warn|fix|error|error-all)]\n \t  [--exclude=<path>] [--include=<path>] [--directory=<root>]\n \t  [--verbose] [<patch>...]\n \ndiff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt\nindex 62f9ab2..0c0a9c1 100644\n--- a/Documentation/git-checkout-index.txt\n+++ b/Documentation/git-checkout-index.txt\n@@ -13,7 +13,7 @@ SYNOPSIS\n \t\t   [--stage=<number>|all]\n \t\t   [--temp]\n \t\t   [-z] [--stdin]\n-\t\t   [--] [<file>]*\n+\t\t   [--] [<file>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt\nindex 349366e..5dcf427 100644\n--- a/Documentation/git-commit-tree.txt\n+++ b/Documentation/git-commit-tree.txt\n@@ -8,7 +8,7 @@ git-commit-tree - Create a new commit object\n \n SYNOPSIS\n --------\n-'git commit-tree' <tree> [-p <parent commit>]* < changelog\n+'git commit-tree' <tree> [(-p <parent commit>)...] < changelog\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt\nindex 400fe7f..d159e88 100644\n--- a/Documentation/git-fetch.txt\n+++ b/Documentation/git-fetch.txt\n@@ -12,7 +12,7 @@ SYNOPSIS\n \n 'git fetch' [<options>] <group>\n \n-'git fetch' --multiple [<options>] [<repository> | <group>]...\n+'git fetch' --multiple [<options>] [(<repository> | <group>)...]\n \n 'git fetch' --all [<options>]\n \ndiff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt\nindex f51860d..796e748 100644\n--- a/Documentation/git-filter-branch.txt\n+++ b/Documentation/git-filter-branch.txt\n@@ -117,7 +117,7 @@ OPTIONS\n \tThis is the filter for performing the commit.\n \tIf this filter is specified, it will be called instead of the\n \t'git commit-tree' command, with arguments of the form\n-\t\"<TREE_ID> [-p <PARENT_COMMIT_ID>]...\" and the log message on\n+\t\"<TREE_ID> [(-p <PARENT_COMMIT_ID>)...]\" and the log message on\n \tstdin.  The commit id is expected on stdout.\n +\n As a special extension, the commit filter may emit multiple\ndiff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt\nindex d66fd9d..fac1cf5 100644\n--- a/Documentation/git-for-each-ref.txt\n+++ b/Documentation/git-for-each-ref.txt\n@@ -9,7 +9,7 @@ SYNOPSIS\n --------\n [verse]\n 'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl]\n-\t\t   [--sort=<key>]* [--format=<format>] [<pattern>...]\n+\t\t   [(--sort=<key>)...] [--format=<format>] [<pattern>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\nindex 246b07e..00d4a12 100644\n--- a/Documentation/git-init.txt\n+++ b/Documentation/git-init.txt\n@@ -31,7 +31,7 @@ current working directory.\n Specify the directory from which templates will be used.  (See the \"TEMPLATE\n DIRECTORY\" section below.)\n \n---shared[={false|true|umask|group|all|world|everybody|0xxx}]::\n+--shared[=(false|true|umask|group|all|world|everybody|0xxx)]::\n \n Specify that the git repository is to be shared amongst several users.  This\n allows users belonging to the same group to push into that\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 347f447..86abd13 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -17,7 +17,7 @@ SYNOPSIS\n \t\t[--exclude-per-directory=<file>]\n \t\t[--exclude-standard]\n \t\t[--error-unmatch] [--with-tree=<tree-ish>]\n-\t\t[--full-name] [--abbrev] [--] [<file>]*\n+\t\t[--full-name] [--abbrev] [--] [<file>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-mailsplit.txt b/Documentation/git-mailsplit.txt\nindex a634485..71912a1 100644\n--- a/Documentation/git-mailsplit.txt\n+++ b/Documentation/git-mailsplit.txt\n@@ -7,7 +7,7 @@ git-mailsplit - Simple UNIX mbox splitter program\n \n SYNOPSIS\n --------\n-'git mailsplit' [-b] [-f<nn>] [-d<prec>] [--keep-cr] -o<directory> [--] [<mbox>|<Maildir>...]\n+'git mailsplit' [-b] [-f<nn>] [-d<prec>] [--keep-cr] -o<directory> [--] [(<mbox>|<Maildir>)...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt\nindex e4ed016..1f75a84 100644\n--- a/Documentation/git-mergetool.txt\n+++ b/Documentation/git-mergetool.txt\n@@ -7,7 +7,7 @@ git-mergetool - Run merge conflict resolution tools to resolve merge conflicts\n \n SYNOPSIS\n --------\n-'git mergetool' [--tool=<tool>] [-y|--no-prompt|--prompt] [<file>]...\n+'git mergetool' [--tool=<tool>] [-y|--no-prompt|--prompt] [<file>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt\nindex a1dd3e9..65eff66 100644\n--- a/Documentation/git-pack-objects.txt\n+++ b/Documentation/git-pack-objects.txt\n@@ -12,7 +12,7 @@ SYNOPSIS\n 'git pack-objects' [-q | --progress | --all-progress] [--all-progress-implied]\n \t[--no-reuse-delta] [--delta-base-offset] [--non-empty]\n \t[--local] [--incremental] [--window=<n>] [--depth=<n>]\n-\t[--revs [--unpacked | --all]*] [--stdout | base-name]\n+\t[--revs [--unpacked | --all]] [--stdout | base-name]\n \t[--keep-true-parents] < object-list\n \n \ndiff --git a/Documentation/git-relink.txt b/Documentation/git-relink.txt\nindex 8a5842b..8fc809f 100644\n--- a/Documentation/git-relink.txt\n+++ b/Documentation/git-relink.txt\n@@ -7,7 +7,7 @@ git-relink - Hardlink common objects in local repositories\n \n SYNOPSIS\n --------\n-'git relink' [--safe] <dir> [<dir>]* <master_dir>\n+'git relink' [--safe] <dir>... <master_dir>\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt\nindex b317086..0d28feb 100644\n--- a/Documentation/git-remote.txt\n+++ b/Documentation/git-remote.txt\n@@ -20,7 +20,7 @@ SYNOPSIS\n 'git remote set-url --delete' [--push] <name> <url>\n 'git remote' [-v | --verbose] 'show' [-n] <name>\n 'git remote prune' [-n | --dry-run] <name>\n-'git remote' [-v | --verbose] 'update' [-p | --prune] [<group> | <remote>]...\n+'git remote' [-v | --verbose] 'update' [-p | --prune] [(<group> | <remote>)...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt\nindex cfb1d21..8e1e329 100644\n--- a/Documentation/git-rev-list.txt\n+++ b/Documentation/git-rev-list.txt\n@@ -37,7 +37,7 @@ SYNOPSIS\n \t     [ \\--regexp-ignore-case | -i ]\n \t     [ \\--extended-regexp | -E ]\n \t     [ \\--fixed-strings | -F ]\n-\t     [ \\--date={local|relative|default|iso|rfc|short} ]\n+\t     [ \\--date=(local|relative|default|iso|rfc|short) ]\n \t     [ [\\--objects | \\--objects-edge] [ \\--unpacked ] ]\n \t     [ \\--pretty | \\--header ]\n \t     [ \\--bisect ]\ndiff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt\nindex 341ca90..4a27643 100644\n--- a/Documentation/git-rev-parse.txt\n+++ b/Documentation/git-rev-parse.txt\n@@ -95,7 +95,7 @@ OPTIONS\n \tunfortunately named tag \"master\"), and show them as full\n \trefnames (e.g. \"refs/heads/master\").\n \n---abbrev-ref[={strict|loose}]::\n+--abbrev-ref[=(strict|loose)]::\n \tA non-ambiguous short name of the objects name.\n \tThe option core.warnAmbiguousRefs is used to select the strict\n \tabbreviation mode.\ndiff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt\nindex 6453263..bd9f886 100644\n--- a/Documentation/git-show-branch.txt\n+++ b/Documentation/git-show-branch.txt\n@@ -12,7 +12,7 @@ SYNOPSIS\n \t\t[--current] [--color[=<when>] | --no-color] [--sparse]\n \t\t[--more=<n> | --list | --independent | --merge-base]\n \t\t[--no-name | --sha1-name] [--topics]\n-\t\t[<rev> | <glob>]...\n+\t\t[(<rev> | <glob>)...]\n \n 'git show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>]\n \ndiff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt\nindex be8a51f..139d314 100644\n--- a/Documentation/git-svn.txt\n+++ b/Documentation/git-svn.txt\n@@ -438,7 +438,7 @@ git rebase --onto remotes/git-svn A^ master\n OPTIONS\n -------\n \n---shared[={false|true|umask|group|all|world|everybody}]::\n+--shared[=(false|true|umask|group|all|world|everybody)]::\n --template=<template_directory>::\n \tOnly used with the 'init' command.\n \tThese are passed directly to 'git init'.\ndiff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt\nindex 74d1d49..a5782a6 100644\n--- a/Documentation/git-update-index.txt\n+++ b/Documentation/git-update-index.txt\n@@ -12,7 +12,7 @@ SYNOPSIS\n 'git update-index'\n \t     [--add] [--remove | --force-remove] [--replace]\n \t     [--refresh] [-q] [--unmerged] [--ignore-missing]\n-\t     [--cacheinfo <mode> <object> <file>]*\n+\t     [(--cacheinfo <mode> <object> <file>)...]\n \t     [--chmod=(+|-)x]\n \t     [--assume-unchanged | --no-assume-unchanged]\n \t     [--skip-worktree | --no-skip-worktree]\n@@ -21,7 +21,7 @@ SYNOPSIS\n \t     [--info-only] [--index-info]\n \t     [-z] [--stdin]\n \t     [--verbose]\n-\t     [--] [<file>]*\n+\t     [--] [<file>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt\nindex 1b13c1f..7a42567 100644\n--- a/Documentation/rev-list-options.txt\n+++ b/Documentation/rev-list-options.txt\n@@ -13,7 +13,7 @@ include::pretty-options.txt[]\n \n \tSynonym for `--date=relative`.\n \n---date={relative,local,default,iso,rfc,short,raw}::\n+--date=(relative|local|default|iso|rfc|short|raw)::\n \n \tOnly takes effect for dates shown in human-readable format, such\n \tas when using \"--pretty\". `log.date` config variable sets a default\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex ce45bfc..cb3b98a 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -3850,7 +3850,7 @@ You create a commit object by giving it the tree that describes the\n state at the time of the commit, and a list of parents:\n \n -------------------------------------------------\n-$ git commit-tree <tree> -p <parent> [-p <parent2> ..]\n+$ git commit-tree <tree> -p <parent> [(-p <parent2>)...]\n -------------------------------------------------\n \n and then giving the reason for the commit on stdin (either through\ndiff --git a/builtin/commit-tree.c b/builtin/commit-tree.c\nindex 87f0591..e065739 100644\n--- a/builtin/commit-tree.c\n+++ b/builtin/commit-tree.c\n@@ -9,7 +9,7 @@\n #include \"builtin.h\"\n #include \"utf8.h\"\n \n-static const char commit_tree_usage[] = \"git commit-tree <sha1> [-p <sha1>]* < changelog\";\n+static const char commit_tree_usage[] = \"git commit-tree <sha1> [(-p <sha1>)...] < changelog\";\n \n static void new_parent(struct commit *parent, struct commit_list **parents_p)\n {\ndiff --git a/builtin/fetch.c b/builtin/fetch.c\nindex 6fc5047..d35f000 100644\n--- a/builtin/fetch.c\n+++ b/builtin/fetch.c\n@@ -16,7 +16,7 @@\n static const char * const builtin_fetch_usage[] = {\n \t\"git fetch [<options>] [<repository> [<refspec>...]]\",\n \t\"git fetch [<options>] <group>\",\n-\t\"git fetch --multiple [<options>] [<repository> | <group>]...\",\n+\t\"git fetch --multiple [<options>] [(<repository> | <group>)...]\",\n \t\"git fetch --all [<options>]\",\n \tNULL\n };\ndiff --git a/builtin/index-pack.c b/builtin/index-pack.c\nindex e243d9d..8dc5c0b 100644\n--- a/builtin/index-pack.c\n+++ b/builtin/index-pack.c\n@@ -11,7 +11,7 @@\n #include \"exec_cmd.h\"\n \n static const char index_pack_usage[] =\n-\"git index-pack [-v] [-o <index-file>] [{ --keep | --keep=<msg> }] [--strict] { <pack-file> | --stdin [--fix-thin] [<pack-file>] }\";\n+\"git index-pack [-v] [-o <index-file>] [ --keep | --keep=<msg> ] [--strict] (<pack-file> | --stdin [--fix-thin] [<pack-file>])\";\n \n struct object_entry\n {\ndiff --git a/builtin/ls-files.c b/builtin/ls-files.c\nindex bb4f612..6a307ab 100644\n--- a/builtin/ls-files.c\n+++ b/builtin/ls-files.c\n@@ -424,7 +424,7 @@ int report_path_error(const char *ps_matched, const char **pathspec, int prefix_\n }\n \n static const char * const ls_files_usage[] = {\n-\t\"git ls-files [options] [<file>]*\",\n+\t\"git ls-files [options] [<file>...]\",\n \tNULL\n };\n \ndiff --git a/builtin/mailsplit.c b/builtin/mailsplit.c\nindex 99654d0..2d43278 100644\n--- a/builtin/mailsplit.c\n+++ b/builtin/mailsplit.c\n@@ -10,7 +10,7 @@\n #include \"strbuf.h\"\n \n static const char git_mailsplit_usage[] =\n-\"git mailsplit [-d<prec>] [-f<n>] [-b] [--keep-cr] -o<directory> [<mbox>|<Maildir>...]\";\n+\"git mailsplit [-d<prec>] [-f<n>] [-b] [--keep-cr] -o<directory> [(<mbox>|<Maildir>)...]\";\n \n static int is_from_line(const char *line, int len)\n {\ndiff --git a/builtin/pack-objects.c b/builtin/pack-objects.c\nindex 1e4c386..26f2304 100644\n--- a/builtin/pack-objects.c\n+++ b/builtin/pack-objects.c\n@@ -23,7 +23,7 @@\n #endif\n \n static const char pack_usage[] =\n-  \"git pack-objects [{ -q | --progress | --all-progress }]\\n\"\n+  \"git pack-objects [ -q | --progress | --all-progress ]\\n\"\n   \"        [--all-progress-implied]\\n\"\n   \"        [--max-pack-size=<n>] [--local] [--incremental]\\n\"\n   \"        [--window=<n>] [--window-memory=<n>] [--depth=<n>]\\n\"\ndiff --git a/builtin/remote.c b/builtin/remote.c\nindex c0198fc..e9a6e09 100644\n--- a/builtin/remote.c\n+++ b/builtin/remote.c\n@@ -15,7 +15,7 @@ static const char * const builtin_remote_usage[] = {\n \t\"git remote set-head <name> (-a | -d | <branch>)\",\n \t\"git remote [-v | --verbose] show [-n] <name>\",\n \t\"git remote prune [-n | --dry-run] <name>\",\n-\t\"git remote [-v | --verbose] update [-p | --prune] [<group> | <remote>]\",\n+\t\"git remote [-v | --verbose] update [-p | --prune] [(<group> | <remote>)...]\",\n \t\"git remote set-branches <name> [--add] <branch>...\",\n \t\"git remote set-url <name> <newurl> [<oldurl>]\",\n \t\"git remote set-url --add <name> <newurl>\",\ndiff --git a/builtin/show-branch.c b/builtin/show-branch.c\nindex e8719aa..8663cca 100644\n--- a/builtin/show-branch.c\n+++ b/builtin/show-branch.c\n@@ -6,7 +6,7 @@\n #include \"parse-options.h\"\n \n static const char* show_branch_usage[] = {\n-    \"git show-branch [-a|--all] [-r|--remotes] [--topo-order | --date-order] [--current] [--color[=<when>] | --no-color] [--sparse] [--more=<n> | --list | --independent | --merge-base] [--no-name | --sha1-name] [--topics] [<rev> | <glob>]...\",\n+    \"git show-branch [-a|--all] [-r|--remotes] [--topo-order | --date-order] [--current] [--color[=<when>] | --no-color] [--sparse] [--more=<n> | --list | --independent | --merge-base] [--no-name | --sha1-name] [--topics] [(<rev> | <glob>)...]\",\n     \"git show-branch (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>]\",\n     NULL\n };\ndiff --git a/git-am.sh b/git-am.sh\nindex 9317b38..763fd20 100755\n--- a/git-am.sh\n+++ b/git-am.sh\n@@ -5,7 +5,7 @@\n SUBDIRECTORY_OK=Yes\n OPTIONS_KEEPDASHDASH=\n OPTIONS_SPEC=\"\\\n-git am [options] [<mbox>|<Maildir>...]\n+git am [options] [(<mbox>|<Maildir>)...]\n git am [options] (--resolved | --skip | --abort)\n --\n i,interactive   run interactively\ndiff --git a/git-relink.perl b/git-relink.perl\nindex 937c69a..c2a0ef8 100755\n--- a/git-relink.perl\n+++ b/git-relink.perl\n@@ -163,7 +163,7 @@ sub link_two_files($$) {\n \n \n sub usage() {\n-\tprint(\"Usage: git relink [--safe] <dir> [<dir> ...] <master_dir> \\n\");\n+\tprint(\"Usage: git relink [--safe] <dir>... <master_dir> \\n\");\n \tprint(\"All directories should contain a .git/objects/ subdirectory.\\n\");\n \tprint(\"Options\\n\");\n \tprint(\"\\t--safe\\t\" .\n-- \n1.7.3.rc2.221.gbf93f.dirty\n"},{"id":"152985","messageId":"1286559080-27257-5-git-send-email-stepnem@gmail.com","threadId":"25387","inReplyTo":"87fwwhszsf.fsf@gmail.com","subject":"[PATCH 4/6] Remove stray quotes in --pretty and --format documentation","fromName":"Štěpán Němec","fromEmail":"stepan.nemec@gmail.com","sentAt":"2010-10-08T17:31:18Z","receivedAt":"2010-10-08T17:31:18Z","isPatch":true,"sender":{"key":"stepnem@gmail.com","avatar":"https://avatars.githubusercontent.com/u/106838?v=4"},"body":"Quotes (for emphasis) are used in option explanations, not the\nheadings.\n\nSigned-off-by: Štěpán Němec <stepnem@gmail.com>\n---\n Documentation/git-shortlog.txt   |    2 +-\n Documentation/pretty-options.txt |    4 ++--\n 2 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt\nindex bc1ac77..5cc3baf 100644\n--- a/Documentation/git-shortlog.txt\n+++ b/Documentation/git-shortlog.txt\n@@ -44,7 +44,7 @@ OPTIONS\n --email::\n \tShow the email address of each author.\n \n---format[='<format>']::\n+--format[=<format>]::\n \tInstead of the commit subject, use some other information to\n \tdescribe each commit.  '<format>' can be any string accepted\n \tby the `--format` option of 'git log', such as '{asterisk} [%h] %s'.\ndiff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt\nindex 9b6f389..50923e2 100644\n--- a/Documentation/pretty-options.txt\n+++ b/Documentation/pretty-options.txt\n@@ -1,5 +1,5 @@\n---pretty[='<format>']::\n---format='<format>'::\n+--pretty[=<format>]::\n+--format=<format>::\n \n \tPretty-print the contents of the commit logs in a given format,\n \twhere '<format>' can be one of 'oneline', 'short', 'medium',\n-- \n1.7.3.rc2.221.gbf93f.dirty\n"},{"id":"152983","messageId":"1286559080-27257-6-git-send-email-stepnem@gmail.com","threadId":"25387","inReplyTo":"87fwwhszsf.fsf@gmail.com","subject":"[PATCH 5/6] Put a space between `<' and argument in pack-objects usage string","fromName":"Štěpán Němec","fromEmail":"stepan.nemec@gmail.com","sentAt":"2010-10-08T17:31:19Z","receivedAt":"2010-10-08T17:31:19Z","isPatch":true,"sender":{"key":"stepnem@gmail.com","avatar":"https://avatars.githubusercontent.com/u/106838?v=4"},"body":"This makes it cosistent with other places (including the\ngit-pack-objects(1) manpage itself) and avoids possible confusion (I,\nfor one, mistook `<object-list' for a `<object-list>' typo at first when\npreparing this series).\n\nSigned-off-by: Štěpán Němec <stepnem@gmail.com>\n---\n builtin/pack-objects.c |    2 +-\n 1 files changed, 1 insertions(+), 1 deletions(-)\n\ndiff --git a/builtin/pack-objects.c b/builtin/pack-objects.c\nindex 26f2304..f8eba53 100644\n--- a/builtin/pack-objects.c\n+++ b/builtin/pack-objects.c\n@@ -31,7 +31,7 @@ static const char pack_usage[] =\n   \"        [--threads=<n>] [--non-empty] [--revs [--unpacked | --all]]\\n\"\n   \"        [--reflog] [--stdout | base-name] [--include-tag]\\n\"\n   \"        [--keep-unreachable | --unpack-unreachable]\\n\"\n-  \"        [<ref-list | <object-list]\";\n+  \"        [< ref-list | < object-list]\";\n \n struct object_entry {\n \tstruct pack_idx_entry idx;\n-- \n1.7.3.rc2.221.gbf93f.dirty\n"},{"id":"152987","messageId":"1286559080-27257-7-git-send-email-stepnem@gmail.com","threadId":"25387","inReplyTo":"87fwwhszsf.fsf@gmail.com","subject":"[PATCH 6/6] Fix {update,checkout}-index usage strings","fromName":"Štěpán Němec","fromEmail":"stepan.nemec@gmail.com","sentAt":"2010-10-08T17:31:20Z","receivedAt":"2010-10-08T17:31:20Z","isPatch":true,"sender":{"key":"stepnem@gmail.com","avatar":"https://avatars.githubusercontent.com/u/106838?v=4"},"body":"The `<file>' argument is optional in both cases (the man pages are\nalready correct).\n\nSigned-off-by: Štěpán Němec <stepnem@gmail.com>\n---\n builtin/checkout-index.c |    2 +-\n builtin/update-index.c   |    2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/builtin/checkout-index.c b/builtin/checkout-index.c\nindex a7a5ee1..65cbee0 100644\n--- a/builtin/checkout-index.c\n+++ b/builtin/checkout-index.c\n@@ -155,7 +155,7 @@ static void checkout_all(const char *prefix, int prefix_length)\n }\n \n static const char * const builtin_checkout_index_usage[] = {\n-\t\"git checkout-index [options] [--] <file>...\",\n+\t\"git checkout-index [options] [--] [<file>...]\",\n \tNULL\n };\n \ndiff --git a/builtin/update-index.c b/builtin/update-index.c\nindex 3ab214d..62d9f3f 100644\n--- a/builtin/update-index.c\n+++ b/builtin/update-index.c\n@@ -398,7 +398,7 @@ static void read_index_info(int line_termination)\n }\n \n static const char update_index_usage[] =\n-\"git update-index [-q] [--add] [--replace] [--remove] [--unmerged] [--refresh] [--really-refresh] [--cacheinfo] [--chmod=(+|-)x] [--assume-unchanged] [--skip-worktree|--no-skip-worktree] [--info-only] [--force-remove] [--stdin] [--index-info] [--unresolve] [--again | -g] [--ignore-missing] [-z] [--verbose] [--] <file>...\";\n+\"git update-index [-q] [--add] [--replace] [--remove] [--unmerged] [--refresh] [--really-refresh] [--cacheinfo] [--chmod=(+|-)x] [--assume-unchanged] [--skip-worktree|--no-skip-worktree] [--info-only] [--force-remove] [--stdin] [--index-info] [--unresolve] [--again | -g] [--ignore-missing] [-z] [--verbose] [--] [<file>...]\";\n \n static unsigned char head_sha1[20];\n static unsigned char merge_head_sha1[20];\n-- \n1.7.3.rc2.221.gbf93f.dirty\n"},{"id":"152988","messageId":"20101008173941.GA13738@burratino","threadId":"25387","inReplyTo":"1286559080-27257-3-git-send-email-stepnem@gmail.com","subject":"Re: [PATCH 2/6] Fix odd markup in --diff-filter documentation","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-08T17:39:41Z","receivedAt":"2010-10-08T17:39:41Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Štěpán Němec wrote:\n\n> --- a/Documentation/diff-options.txt\n> +++ b/Documentation/diff-options.txt\n> @@ -248,13 +248,13 @@ endif::git-log[]\n>  \tIf `n` is specified, it has the same meaning as for `-M<n>`.\n>  \n>  ifndef::git-format-patch[]\n> ---diff-filter=[ACDMRTUXB*]::\n> +--diff-filter=<spec>::\n\nMaybe something like\n\n--diff-filter=((A|C|D|M|R|T|U|X|B)...[*])\n\nto keep the overview while following the conventions you've set out?\n\nStrictly speaking, --diff-filter= (with empty argument) is allowed, too,\nbut I don't know if it's worth fitting that in.\n"},{"id":"152989","messageId":"20101008174457.GB13738@burratino","threadId":"25387","inReplyTo":"1286559080-27257-1-git-send-email-stepnem@gmail.com","subject":"Re: [PATCH 0/6] Unify argument and option notation in the docs","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-08T17:44:57Z","receivedAt":"2010-10-08T17:44:57Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Štěpán Němec wrote:\n\n> [PATCH 1/6] Use angles for placeholders consistently\n> [PATCH 2/6] Fix odd markup in --diff-filter documentation\n> [PATCH 3/6] Use parentheses and `...' where appropriate\n> [PATCH 4/6] Remove stray quotes in --pretty and --format documentation\n> [PATCH 5/6] Put a space between `<' and argument in pack-objects usage string\n> [PATCH 6/6] Fix {update,checkout}-index usage strings\n\nAll these seem like improvements to me.  So:\nAcked-by: Jonathan Nieder <jrnieder@gmail.com>\n\nThanks.\n"},{"id":"152990","messageId":"87bp74tvno.fsf@gmail.com","threadId":"25387","inReplyTo":"20101008173941.GA13738@burratino","subject":"Re: [PATCH 2/6] Fix odd markup in --diff-filter documentation","fromName":"Štěpán Němec","fromEmail":"stepan.nemec@gmail.com","sentAt":"2010-10-08T17:57:15Z","receivedAt":"2010-10-08T17:57:15Z","isPatch":true,"sender":{"key":"stepnem@gmail.com","avatar":"https://avatars.githubusercontent.com/u/106838?v=4"},"body":"Jonathan Nieder <jrnieder@gmail.com> writes:\n\n> Štěpán Němec wrote:\n>\n>> --- a/Documentation/diff-options.txt\n>> +++ b/Documentation/diff-options.txt\n>> @@ -248,13 +248,13 @@ endif::git-log[]\n>>  \tIf `n` is specified, it has the same meaning as for `-M<n>`.\n>>  \n>>  ifndef::git-format-patch[]\n>> ---diff-filter=[ACDMRTUXB*]::\n>> +--diff-filter=<spec>::\n>\n> Maybe something like\n>\n> --diff-filter=((A|C|D|M|R|T|U|X|B)...[*])\n>\n> to keep the overview while following the conventions you've set out?\n\nLooks good to me as well, thanks.\n\n> Strictly speaking, --diff-filter= (with empty argument) is allowed, too,\n> but I don't know if it's worth fitting that in.\n\nIf it provides some kind of useful behaviour (I don't know and you\ndidn't clarify that either), then it should be documented I guess?\n\nŠtěpán\n"},{"id":"152992","messageId":"20101008180327.GA13910@burratino","threadId":"25387","inReplyTo":"87bp74tvno.fsf@gmail.com","subject":"Re: [PATCH 2/6] Fix odd markup in --diff-filter documentation","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-08T18:03:27Z","receivedAt":"2010-10-08T18:03:27Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Štěpán Němec wrote:\n> Jonathan Nieder <jrnieder@gmail.com> writes:\n\n>> Strictly speaking, --diff-filter= (with empty argument) is allowed, too,\n>> but I don't know if it's worth fitting that in.\n>\n> If it provides some kind of useful behaviour (I don't know and you\n> didn't clarify that either), then it should be documented I guess?\n\nJust a special case of the usual behavior: it selects the empty set of\nfiles.  Doesn't sound useful to me, but maybe someone writing a\nfront-end would want to be reassured that --diff-filter will still\nwork if the user unchecks all the boxes.\n\nOf course, one can also just try it...\n\nIf you can find a way to format it nicely (using brackets?), then I\nthink it should be part of the documented syntax, yes.\n"},{"id":"152997","messageId":"877hhsttnj.fsf@gmail.com","threadId":"25387","inReplyTo":"20101008180327.GA13910@burratino","subject":"Re: [PATCH 2/6] Fix odd markup in --diff-filter documentation","fromName":"Štěpán Němec","fromEmail":"stepan.nemec@gmail.com","sentAt":"2010-10-08T18:40:32Z","receivedAt":"2010-10-08T18:40:32Z","isPatch":true,"sender":{"key":"stepnem@gmail.com","avatar":"https://avatars.githubusercontent.com/u/106838?v=4"},"body":"Jonathan Nieder <jrnieder@gmail.com> writes:\n\n> Štěpán Němec wrote:\n>> Jonathan Nieder <jrnieder@gmail.com> writes:\n>\n>>> Strictly speaking, --diff-filter= (with empty argument) is allowed, too,\n>>> but I don't know if it's worth fitting that in.\n>>\n>> If it provides some kind of useful behaviour (I don't know and you\n>> didn't clarify that either), then it should be documented I guess?\n>\n> Just a special case of the usual behavior: it selects the empty set of\n> files.  Doesn't sound useful to me, but maybe someone writing a\n> front-end would want to be reassured that --diff-filter will still\n> work if the user unchecks all the boxes.\n>\n> Of course, one can also just try it...\n>\n> If you can find a way to format it nicely (using brackets?), then I\n> think it should be part of the documented syntax, yes.\n\nWell, in that case simply replacing parens with brackets would do, i.e.\n\n--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]\n\ninstead of \n\n--diff-filter=((A|C|D|M|R|T|U|X|B)...[*])\n\nThat would mean the following instead of the original [2/6]:\n\n--- 8< ---\nSubject: Fix odd markup in --diff-filter documentation\n\nInstead of using the regex-like bracket expression, use grouping to make\nit more consistent with other similar places. The brackets now have the\nsame meaning as in other documentation (i.e., the argument is optional).\n\nSigned-off-by: Štěpán Němec <stepnem@gmail.com>\nMentored-by: Jonathan Nieder <jrnieder@gmail.com>\n---\n Documentation/diff-options.txt |    4 ++--\n 1 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex cbf3c92..e954af0 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -248,13 +248,13 @@ endif::git-log[]\n        If `n` is specified, it has the same meaning as for `-M<n>`.\n\n ifndef::git-format-patch[]\n---diff-filter=[ACDMRTUXB*]::\n+--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]::\n        Select only files that are Added (`A`), Copied (`C`),\n        Deleted (`D`), Modified (`M`), Renamed (`R`), have their\n        type (i.e. regular file, symlink, submodule, ...) changed (`T`),\n        are Unmerged (`U`), are\n        Unknown (`X`), or have had their pairing Broken (`B`).\n-       Any combination of the filter characters may be used.\n+       Any combination of the filter characters (including none) can be used.\n        When `*` (All-or-none) is added to the combination, all\n        paths are selected if there is any file that matches\n        other criteria in the comparison; if there is no file\n--\n"},{"id":"152998","messageId":"20101008185314.GA14277@burratino","threadId":"25387","inReplyTo":"877hhsttnj.fsf@gmail.com","subject":"Re: [PATCH 2/6] Fix odd markup in --diff-filter documentation","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-08T18:53:15Z","receivedAt":"2010-10-08T18:53:15Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Štěpán Němec wrote:\n\n> That would mean the following instead of the original [2/6]:\n\nLooks good, thanks.\n"},{"id":"152999","messageId":"7v1v80wjuw.fsf@alter.siamese.dyndns.org","threadId":"25387","inReplyTo":"1286559080-27257-1-git-send-email-stepnem@gmail.com","subject":"Re: [PATCH 0/6] Unify argument and option notation in the docs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-10-08T19:43:51Z","receivedAt":"2010-10-08T19:43:51Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"I had to fix up the whitespace damage in the rerolled 2/6 but otherwise\nlooked good.\n\nThanks, both.  It might make sense to outline the rules applied somewhere in\nCodingGuidelines to help people who add to our documents.  Something along\nthe lines of...\n\n - A placeholder is spelled inside angle brackets, e.g. <file>, <object>.\n\n - Choosing one from many is written with possible choices separated with\n   a vertical bar and the whole thing enclosed in parentheses, e.g.\n   answer=(yes|no|true|false)\n\n - Repetition of zero or more times of X is spelled as [(X)...], e.g.\n   [(-p <parent>)...]\n"},{"id":"153007","messageId":"8739sgtp8i.fsf@gmail.com","threadId":"25387","inReplyTo":"7v1v80wjuw.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 0/6] Unify argument and option notation in the docs","fromName":"Štěpán Němec","fromEmail":"stepnem@gmail.com","sentAt":"2010-10-08T20:15:57Z","receivedAt":"2010-10-08T20:15:57Z","isPatch":true,"sender":{"key":"stepnem@gmail.com","avatar":"https://avatars.githubusercontent.com/u/106838?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> I had to fix up the whitespace damage in the rerolled 2/6 but otherwise\n> looked good.\n\nYeah, sorry for that. Obviously the tabs got replaced by spaces when I\ncopy-pasted the hunk and I didn't notice.\n\n> Thanks, both.  It might make sense to outline the rules applied somewhere in\n> CodingGuidelines to help people who add to our documents.  Something along\n> the lines of...\n>\n>  - A placeholder is spelled inside angle brackets, e.g. <file>, <object>.\n>\n>  - Choosing one from many is written with possible choices separated with\n>    a vertical bar and the whole thing enclosed in parentheses, e.g.\n>    answer=(yes|no|true|false)\n>\n>  - Repetition of zero or more times of X is spelled as [(X)...], e.g.\n>    [(-p <parent>)...]\n\n:-) I was actually considering just that, so I'm glad you mention it.\n\nI can try to compile an initial version of such a document, based on the\ncommit message of the original single-patch version\n(<http://article.gmane.org/gmane.comp.version-control.git/158467>) and\nincluding some more cases/examples.\n\nWhere do you think would be the most appropriate place for it?\nJust add a section to CodingGuidelines, or a separate\nDocumentation/WritingGuidelines or something?\n\nŠtěpán\n"},{"id":"154038","messageId":"20101021222129.GA13262@burratino","threadId":"25387","inReplyTo":"8739sgtp8i.fsf@gmail.com","subject":"Re: [PATCH 0/6] Unify argument and option notation in the docs","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-21T22:21:29Z","receivedAt":"2010-10-21T22:21:29Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Štěpán Němec wrote:\n\n> :-) I was actually considering just that, so I'm glad you mention it.\n> \n> I can try to compile an initial version of such a document, based on the\n> commit message of the original single-patch version\n> (<http://article.gmane.org/gmane.comp.version-control.git/158467>) and\n> including some more cases/examples.\n> \n> Where do you think would be the most appropriate place for it?\n> Just add a section to CodingGuidelines, or a separate\n> Documentation/WritingGuidelines or something?\n\nSorry for the slow response.  Documentation/CodingGuidelines makes sense\nto me, since it affects the usage strings in code.\n"},{"id":"154338","messageId":"20101024155121.GA9503@headley","threadId":"25387","inReplyTo":"20101021222129.GA13262@burratino","subject":"[PATCH] CodingGuidelines: Add a section on writing documentation","fromName":"Štěpán Němec","fromEmail":"stepnem@gmail.com","sentAt":"2010-10-24T15:51:22Z","receivedAt":"2010-10-24T15:51:22Z","isPatch":true,"sender":{"key":"stepnem@gmail.com","avatar":"https://avatars.githubusercontent.com/u/106838?v=4"},"body":"Provide a few examples on argument and option notation in usage strings\nand command synopses.\n\nSigned-off-by: Štěpán Němec <stepnem@gmail.com>\n---\nJonathan Nieder <jrnieder@gmail.com> writes:\n\n> Štěpán Němec wrote:\n\n[...]\n\n>> I can try to compile an initial version of such a document, based on the\n>> commit message of the original single-patch version\n>> (<http://article.gmane.org/gmane.comp.version-control.git/158467>) and\n>> including some more cases/examples.\n>> \n>> Where do you think would be the most appropriate place for it?\n>> Just add a section to CodingGuidelines, or a separate\n>> Documentation/WritingGuidelines or something?\n>\n> Sorry for the slow response.  Documentation/CodingGuidelines makes sense\n> to me, since it affects the usage strings in code.\n\nThanks, here's a patch.\n\n Documentation/CodingGuidelines |   53 ++++++++++++++++++++++++++++++++++++++++\n 1 files changed, 53 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex 09ffc46..0ac7aac 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -139,3 +139,56 @@ For C programs:\n \n  - When we pass <string, length> pair to functions, we should try to\n    pass them in that order.\n+\n+Writing Documentation:\n+\n+ Every user-visible change should be reflected in the documentation.\n+ The same general rule as for code applies -- imitate the existing\n+ conventions.  A few commented examples follow to provide reference\n+ when writing or modifying command usage strings and synopsis sections\n+ in the manual pages:\n+\n+ Placeholders are enclosed in angle brackets:\n+   <file>\n+   --sort=<key>\n+   --abbrev[=<n>]\n+\n+ Possibility of multiple occurences is indicated by three dots:\n+   <file>...\n+   (One or more of <file>.)\n+\n+ Optional parts are enclosed in square brackets:\n+   [<extra>]\n+   (Zero or one <extra>.)\n+\n+   --exec-path[=<path>]\n+   (Option with an optional argument.  Note that the \"=\" is inside the\n+   brackets.)\n+\n+   [<patch>...]\n+   (Zero or more of <patch>.  Note that the dots are inside, not\n+   outside the brackets.)\n+\n+ Parentheses are used for grouping, often combined with vertical bar\n+ to indicate alternatives:\n+   [(<rev>|<range>)...]\n+   (Any number of either <rev> or <range>.  Parens are needed to make\n+   it clear that \"...\" pertains to both <rev> and <range>.)\n+\n+   [(-p <parent>)...]\n+   (Any number of option -p, each with one <parent> argument.)\n+\n+   git remote set-head <name> (-a | -d | <branch>)\n+   (One and only one of \"-a\", \"-d\" or \"<branch>\" _must_ (no square\n+   brackets) be provided.)\n+\n+ Specific number of occurences is indicated as follows:\n+   <commit>{0,2}\n+   (Up to two <commit>s.)\n+\n+ And a somewhat more contrived example:\n+   --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]\n+   Here \"=\" is outside the brackets, because \"--diff-filter=\" is a\n+   valid usage.  \"*\" has its own pair of brackets, because it can\n+   (optionally) be specified only when one or more of the letters is\n+   also provided.\n-- \n1.7.3.rc2.221.gbf93f.dirty\n"},{"id":"154714","messageId":"AANLkTimpJbuZAPfvVOedstV7=UiLiDMnDaYWQLVNQ+Yc@mail.gmail.com","threadId":"25387","inReplyTo":"20101024155121.GA9503@headley","subject":"Re: [PATCH] CodingGuidelines: Add a section on writing documentation","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-10-29T02:56:14Z","receivedAt":"2010-10-29T02:56:14Z","isPatch":true,"sender":{"key":"lodatom@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58860?v=4"},"body":"On Sun, Oct 24, 2010 at 11:51 AM, Štěpán Němec <stepnem@gmail.com> wrote:\n> Provide a few examples on argument and option notation in usage strings\n> and command synopses.\n\nI think this is a great idea.\n\n> + Specific number of occurences is indicated as follows:\n> +   <commit>{0,2}\n> +   (Up to two <commit>s.)\n\nI suggest removing this notation - it is confusing and is only used by\ngit-diff.txt and git-difftool.txt.  We already have notation to serve\nthis purpose:\n\n    [<commit> [<commit>]]\n\n> + Parentheses are used for grouping, often combined with vertical bar\n> + to indicate alternatives:\n> +   [(<rev>|<range>)...]\n> +   (Any number of either <rev> or <range>.  Parens are needed to make\n> +   it clear that \"...\" pertains to both <rev> and <range>.)\n\nYou could also mention that parentheses are not needed if square\nbrackets will do:\n    [-q | --quiet]\n\nAlso, should there be a standard for spacing and for whether the short\nor the long option comes first?\n\ngit-add.txt:\n    [--patch | -p]\ngit-commit.txt:\n    [-a | --interactive]\ngit-stash.txt:\n    [-q|--quiet]\n\nOtherwise, I think this patch looks good.\n"},{"id":"154781","messageId":"87wrp12p00.fsf@gmail.com","threadId":"25387","inReplyTo":"AANLkTimpJbuZAPfvVOedstV7=UiLiDMnDaYWQLVNQ+Yc@mail.gmail.com","subject":"Re: [PATCH] CodingGuidelines: Add a section on writing documentation","fromName":"Štěpán Němec","fromEmail":"stepnem@gmail.com","sentAt":"2010-10-29T11:54:23Z","receivedAt":"2010-10-29T11:54:23Z","isPatch":true,"sender":{"key":"stepnem@gmail.com","avatar":"https://avatars.githubusercontent.com/u/106838?v=4"},"body":"Mark Lodato <lodatom@gmail.com> writes:\n\n> On Sun, Oct 24, 2010 at 11:51 AM, Štěpán Němec <stepnem@gmail.com> wrote:\n>> + Specific number of occurences is indicated as follows:\n>> +   <commit>{0,2}\n>> +   (Up to two <commit>s.)\n>\n> I suggest removing this notation - it is confusing and is only used by\n> git-diff.txt and git-difftool.txt.  We already have notation to serve\n> this purpose:\n>\n>     [<commit> [<commit>]]\n\nYeah, it's kind of an oddball, although I don't really find it\nconfusing. I guess it might be useful in cases where you have a bigger\nnumber of \"things\", say 4 or more, where the brackets could get\nunwieldy.\n\nBut given that it's only used as {0,2} at the two places right now\n(disregarding occurences of \"0{40}\" in the documentation), I agree it\nmight be better to get rid of it, although I don't feel strongly about\nit. Any other opinions?\n\n>> + Parentheses are used for grouping, often combined with vertical bar\n>> + to indicate alternatives:\n>> +   [(<rev>|<range>)...]\n>> +   (Any number of either <rev> or <range>.  Parens are needed to make\n>> +   it clear that \"...\" pertains to both <rev> and <range>.)\n>\n> You could also mention that parentheses are not needed if square\n> brackets will do:\n>     [-q | --quiet]\n\nGood point, will do.\n\n> Also, should there be a standard for spacing and for whether the short\n> or the long option comes first?\n>\n> git-add.txt:\n>     [--patch | -p]\n> git-commit.txt:\n>     [-a | --interactive]\n> git-stash.txt:\n>     [-q|--quiet]\n\nI thought about this already when preparing the recent unification\nseries, and came to the conclusion \"no, there shouldn't\". :-) As the\nexamples you give show, the current usage is inconsistent, but given\nthat it brings no semantic ambiguity, I don't think it is a problem. You\ncould find more similar cosmetic inconsistencies and I don't think it\nmakes much sense to mandate any rules for such things. (But again, I\ndon't feel _too_ strongly about this either, so if more people think\nit's worth it, I can prepare a patch that unifies them and mention the\npreference in CodingGuidelines.)\n\n> Otherwise, I think this patch looks good.\n\nThank you for the feedback!\n\nŠtěpán\n"},{"id":"154796","messageId":"AANLkTinyPkGmsgbGM9qpXMNcZRzOXvtjDDEkJ-i3nWXz@mail.gmail.com","threadId":"25387","inReplyTo":"87wrp12p00.fsf@gmail.com","subject":"Re: [PATCH] CodingGuidelines: Add a section on writing documentation","fromName":"Sverre Rabbelier","fromEmail":"srabbelier@gmail.com","sentAt":"2010-10-29T17:14:20Z","receivedAt":"2010-10-29T17:14:20Z","isPatch":true,"sender":{"key":"srabbelier@gmail.com","avatar":"https://avatars.githubusercontent.com/u/3098?v=4"},"body":"Heya,\n\nOn Fri, Oct 29, 2010 at 04:54, Štěpán Němec <stepnem@gmail.com> wrote:\n> But given that it's only used as {0,2} at the two places right now\n> (disregarding occurences of \"0{40}\" in the documentation), I agree it\n> might be better to get rid of it, although I don't feel strongly about\n> it. Any other opinions?\n\nLet's get rid of it for now, we can always resurrect it later if we\nhave a need for it.\n\n> I thought about this already when preparing the recent unification\n> series, and came to the conclusion \"no, there shouldn't\". :-) As the\n> examples you give show, the current usage is inconsistent, but given\n> that it brings no semantic ambiguity, I don't think it is a problem. You\n> could find more similar cosmetic inconsistencies and I don't think it\n> makes much sense to mandate any rules for such things. (But again, I\n> don't feel _too_ strongly about this either, so if more people think\n> it's worth it, I can prepare a patch that unifies them and mention the\n> preference in CodingGuidelines.)\n\nPerhaps we can set a standard to do it, but just leave the existing\ncases as is (to prevent unneeded churn)? That way we'll eventually\nconverge on something.\n\n-- \nCheers,\n\nSverre Rabbelier\n"},{"id":"154932","messageId":"87fwvl2d4d.fsf@gmail.com","threadId":"25387","inReplyTo":"AANLkTinyPkGmsgbGM9qpXMNcZRzOXvtjDDEkJ-i3nWXz@mail.gmail.com","subject":"Re: [PATCH] CodingGuidelines: Add a section on writing documentation","fromName":"Štěpán Němec","fromEmail":"stepnem@gmail.com","sentAt":"2010-11-01T17:00:02Z","receivedAt":"2010-11-01T17:00:02Z","isPatch":true,"sender":{"key":"stepnem@gmail.com","avatar":"https://avatars.githubusercontent.com/u/106838?v=4"},"body":"Sverre Rabbelier <srabbelier@gmail.com> writes:\n\n> Heya,\n>\n> On Fri, Oct 29, 2010 at 04:54, Štěpán Němec <stepnem@gmail.com> wrote:\n>> But given that it's only used as {0,2} at the two places right now\n>> (disregarding occurences of \"0{40}\" in the documentation), I agree it\n>> might be better to get rid of it, although I don't feel strongly about\n>> it. Any other opinions?\n>\n> Let's get rid of it for now, we can always resurrect it later if we\n> have a need for it.\n\nOK.\n\n>> I thought about this already when preparing the recent unification\n>> series, and came to the conclusion \"no, there shouldn't\". :-) As the\n>> examples you give show, the current usage is inconsistent, but given\n>> that it brings no semantic ambiguity, I don't think it is a problem. You\n>> could find more similar cosmetic inconsistencies and I don't think it\n>> makes much sense to mandate any rules for such things. (But again, I\n>> don't feel _too_ strongly about this either, so if more people think\n>> it's worth it, I can prepare a patch that unifies them and mention the\n>> preference in CodingGuidelines.)\n>\n> Perhaps we can set a standard to do it, but just leave the existing\n> cases as is (to prevent unneeded churn)? That way we'll eventually\n> converge on something.\n\nHm... that seems like the worst solution to me -- if we do end up\nstandardizing this after all, any occurence of non-standard usage would\nbe a bug that needs fixing (think about it from the POV of a new\ncontributor who reads CodingGuidelines but sees the actual usage being\ndifferent).\n\nI guess it wouldn't be so much of a code churn to unify the spacing, but\nI'm still not convinced we should be enforcing this kind of thing.\n\nŠtěpán\n"},{"id":"155178","messageId":"87lj59gghb.fsf_-_@gmail.com","threadId":"25387","inReplyTo":"87fwvl2d4d.fsf@gmail.com","subject":"[PATCH v2] CodingGuidelines: Add a section on writing documentation","fromName":"Štěpán Němec","fromEmail":"stepnem@gmail.com","sentAt":"2010-11-04T17:12:48Z","receivedAt":"2010-11-04T17:12:48Z","isPatch":true,"sender":{"key":"stepnem@gmail.com","avatar":"https://avatars.githubusercontent.com/u/106838?v=4"},"body":"\nProvide a few examples on argument and option notation in usage strings\nand command synopses.\n\nSigned-off-by: Štěpán Němec <stepnem@gmail.com>\n---\n Changes since the last version:\n\n - add a separate subsection on vertical bar without parentheses (suggested\n   by Mark Lodato)\n\n - do not include the <thing>{M,N} usage for fixed number of occurences\n   (Mark Lodato and Sverre Rabbelier)\n \n Documentation/CodingGuidelines |   52 ++++++++++++++++++++++++++++++++++++++++\n 1 files changed, 52 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex 09ffc46..5aa2d34 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -139,3 +139,55 @@ For C programs:\n \n  - When we pass <string, length> pair to functions, we should try to\n    pass them in that order.\n+\n+Writing Documentation:\n+\n+ Every user-visible change should be reflected in the documentation.\n+ The same general rule as for code applies -- imitate the existing\n+ conventions.  A few commented examples follow to provide reference\n+ when writing or modifying command usage strings and synopsis sections\n+ in the manual pages:\n+\n+ Placeholders are enclosed in angle brackets:\n+   <file>\n+   --sort=<key>\n+   --abbrev[=<n>]\n+\n+ Possibility of multiple occurences is indicated by three dots:\n+   <file>...\n+   (One or more of <file>.)\n+\n+ Optional parts are enclosed in square brackets:\n+   [<extra>]\n+   (Zero or one <extra>.)\n+\n+   --exec-path[=<path>]\n+   (Option with an optional argument.  Note that the \"=\" is inside the\n+   brackets.)\n+\n+   [<patch>...]\n+   (Zero or more of <patch>.  Note that the dots are inside, not\n+   outside the brackets.)\n+\n+ Multiple alternatives are indicated with vertical bar:\n+   [-q | --quiet]\n+   [--utf8 | --no-utf8]\n+\n+ Parentheses are used for grouping:\n+   [(<rev>|<range>)...]\n+   (Any number of either <rev> or <range>.  Parens are needed to make\n+   it clear that \"...\" pertains to both <rev> and <range>.)\n+\n+   [(-p <parent>)...]\n+   (Any number of option -p, each with one <parent> argument.)\n+\n+   git remote set-head <name> (-a | -d | <branch>)\n+   (One and only one of \"-a\", \"-d\" or \"<branch>\" _must_ (no square\n+   brackets) be provided.)\n+\n+ And a somewhat more contrived example:\n+   --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]\n+   Here \"=\" is outside the brackets, because \"--diff-filter=\" is a\n+   valid usage.  \"*\" has its own pair of brackets, because it can\n+   (optionally) be specified only when one or more of the letters is\n+   also provided.\n-- \n1.7.3.rc2.221.gbf93f.dirty\n"},{"id":"155180","messageId":"87hbfxgg86.fsf_-_@gmail.com","threadId":"25387","inReplyTo":"87fwvl2d4d.fsf@gmail.com","subject":"[PATCH] diff,difftool: Don't use the {0,2} notation in usage strings","fromName":"Štěpán Němec","fromEmail":"stepnem@gmail.com","sentAt":"2010-11-04T17:18:17Z","receivedAt":"2010-11-04T17:18:17Z","isPatch":true,"sender":{"key":"stepnem@gmail.com","avatar":"https://avatars.githubusercontent.com/u/106838?v=4"},"body":"This was the only occurence of that usage, and square brackets are\nsufficient and already well-established for that purpose.\n\nSigned-off-by: Štěpán Němec <stepnem@gmail.com>\n---\n\nAs per discussion upthread, this notation is not worth keeping; hence\nnot mentioning it in the v2 of the CodingGuidlines patch and this\nremoval.\n\n Documentation/git-diff.txt     |    2 +-\n Documentation/git-difftool.txt |    2 +-\n builtin/diff.c                 |    2 +-\n 3 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex dd1fb32..61728f6 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -8,7 +8,7 @@ git-diff - Show changes between commits, commit and working tree, etc\n \n SYNOPSIS\n --------\n-'git diff' [<common diff options>] <commit>{0,2} [--] [<path>...]\n+'git diff' [<common diff options>] [<commit> [<commit>]] [--] [<path>...]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt\nindex 8250bad..a02e3b5 100644\n--- a/Documentation/git-difftool.txt\n+++ b/Documentation/git-difftool.txt\n@@ -7,7 +7,7 @@ git-difftool - Show changes using common diff tools\n \n SYNOPSIS\n --------\n-'git difftool' [<options>] <commit>{0,2} [--] [<path>...]\n+'git difftool' [<options>] [<commit> [<commit>]] [--] [<path>...]\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/diff.c b/builtin/diff.c\nindex a43d326..945e758 100644\n--- a/builtin/diff.c\n+++ b/builtin/diff.c\n@@ -22,7 +22,7 @@ struct blobinfo {\n };\n \n static const char builtin_diff_usage[] =\n-\"git diff <options> <rev>{0,2} -- <path>*\";\n+\"git diff [<options>] [<commit> [<commit>]] [--] [<path>...]\";\n \n static void stuff_change(struct diff_options *opt,\n \t\t\t unsigned old_mode, unsigned new_mode,\n-- \n1.7.3.rc2.221.gbf93f.dirty\n"},{"id":"155182","messageId":"AANLkTi=mhbxQZEZYn6cCu_O2xaE87U9OU=TQiX2CKSar@mail.gmail.com","threadId":"25387","inReplyTo":"87hbfxgg86.fsf_-_@gmail.com","subject":"Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings","fromName":"Sverre Rabbelier","fromEmail":"srabbelier@gmail.com","sentAt":"2010-11-04T17:22:38Z","receivedAt":"2010-11-04T17:22:38Z","isPatch":true,"sender":{"key":"srabbelier@gmail.com","avatar":"https://avatars.githubusercontent.com/u/3098?v=4"},"body":"Heya,\n\n2010/11/4 Štěpán Němec <stepnem@gmail.com>:\n> This was the only occurence of that usage, and square brackets are\n> sufficient and already well-established for that purpose.\n>\n> Signed-off-by: Štěpán Němec <stepnem@gmail.com>\n\nNot sure if it's appropriate for Documentation patches, but fwiw:\n\nAcked by: Sverre Rabbelier <srabbelier@gmail.com>\n\n-- \nCheers,\n\nSverre Rabbelier\n"},{"id":"155185","messageId":"20101104174917.GA30628@sigill.intra.peff.net","threadId":"25387","inReplyTo":"87hbfxgg86.fsf_-_@gmail.com","subject":"Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-11-04T17:49:17Z","receivedAt":"2010-11-04T17:49:17Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Nov 04, 2010 at 06:18:17PM +0100, Štěpán Němec wrote:\n\n> This was the only occurence of that usage, and square brackets are\n> sufficient and already well-established for that purpose.\n> \n> Signed-off-by: Štěpán Němec <stepnem@gmail.com>\n> ---\n> \n> As per discussion upthread, this notation is not worth keeping; hence\n> not mentioning it in the v2 of the CodingGuidlines patch and this\n> removal.\n\nI agree the notation is kind of odd. But the intent of the original is\nto point out that diff has several modes of operation, depending on the\nnumber of arguments it is given. Your change seems to make that even\nmore subtle. I would be more in favor of showing the major modes of\noperation, one per line, which is what we do in other places. E.g., see\ngit-branch(1).\n\nNow in the case of diff, as soon as the \"description\" section starts, we\ndo start talking about those modes (and there are a lot of them). But I\nthink it may make sense to cover them with a short comment in the\nsynopsis. Something like:\n\n\n  # diff between index and working tree\n  git diff [options] [--] [<path>...]\n\n  # diff between HEAD and index\n  git diff --cached [options] [--] [<path>...]\n\n  # diff between commit and working tree\n  git diff [options] <commit> [--] [<path>...]\n\n  # diff between commit and index\n  git diff --cached [options] <commit> [--] [<path>...]\n\n  # diff between commits\n  git diff [options] <commit> <commit> [--] [<path>...]\n\n  # diff two paths\n  git diff [options] [--] <path> <path>\n\nwhich obviously is way more verbose, but I think it improves in two\nways:\n\n  1. New users will immediately see what diff is for: it is the\n     all-purpose diffing tool in git, and it has several modes of\n     operation.\n\n  2. People who know what diff does but need a quick reference on which\n     mode they are looking for can quickly scan the list.\n\nIf it's too verbose, we could collapse a few cases (e.g., \"HEAD and\nindex\" and \"commit and index\" could come in one line).\n\n-Peff\n"},{"id":"155186","messageId":"20101104180242.GA16431@burratino","threadId":"25387","inReplyTo":"20101104174917.GA30628@sigill.intra.peff.net","subject":"Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-11-04T18:02:42Z","receivedAt":"2010-11-04T18:02:42Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Jeff King wrote:\n\n>   # diff between index and working tree\n>   git diff [options] [--] [<path>...]\n> \n>   # diff between HEAD and index\n>   git diff --cached [options] [--] [<path>...]\n> \n>   # diff between commit and working tree\n>   git diff [options] <commit> [--] [<path>...]\n> \n>   # diff between commit and index\n>   git diff --cached [options] <commit> [--] [<path>...]\n> \n>   # diff between commits\n>   git diff [options] <commit> <commit> [--] [<path>...]\n> \n>   # diff two paths\n>   git diff [options] [--] <path> <path>\n> \n> which obviously is way more verbose\n\nYes, that's way more verbose than a typical manpage synopsis.\nFor example, from printf(3):\n\nSYNOPSIS\n       #include <stdio.h>\n\n       int printf(const char *format, ...);\n       int fprintf(FILE *stream, const char *format, ...);\n       int sprintf(char *str, const char *format, ...);\n       int snprintf(char *str, size_t size, const char *format, ...);\n\n       #include <stdarg.h>\n\n       int vprintf(const char *format, va_list ap);\n       int vfprintf(FILE *stream, const char *format, va_list ap);\n       int vsprintf(char *str, const char *format, va_list ap);\n       int vsnprintf(char *str, size_t size, const char *format, va_list ap);\n\n   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):\n\n       snprintf(), vsnprintf(): _BSD_SOURCE || _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE; or cc -std=c99\n\nwhich would suggest that for git-diff(!) we should say something like:\n\nSYNOPSIS\n\n\tgit diff [options] [--] [<path>...]\n\tgit diff [options] --cached [--] [<path>...]\n\tgit diff [options] <commit> [--] [<path>...]\n\tgit diff [options] --cached <commit> [--] [<path>...]\n\tgit diff [options] <commit> <commit> [--] [<path>...]\n\tgit diff [options] --no-index [--] <path> <path>\n\nI would rather treat --cached as one of the options (\"instead of\ncomparing the worktree, compare its cached content in the index to the\nspecified commit\"), and if I were running the world, I'd leave off the\n[options]. :)\n\nSYNOPSIS\n\n\tgit diff [--] [<path>...]\n\tgit diff <commit> [--] [<path>...]\n\tgit diff <commit> <commit> [--] [<path>...]\n\tgit diff --no-index [--] <path> <path>\n\nperhaps with some kind of reminder about --cached:\n\n\tThe first two forms accept a --cached option to compare\n\tto staged content in the index instead of the work tree.\n"},{"id":"155188","messageId":"20101104181357.GA31016@sigill.intra.peff.net","threadId":"25387","inReplyTo":"20101104180242.GA16431@burratino","subject":"Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-11-04T18:13:57Z","receivedAt":"2010-11-04T18:13:57Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Nov 04, 2010 at 01:02:42PM -0500, Jonathan Nieder wrote:\n\n> Yes, that's way more verbose than a typical manpage synopsis.\n\nWell, yes, but...\n\n> For example, from printf(3):\n> \n> SYNOPSIS\n>        #include <stdio.h>\n> \n>        int printf(const char *format, ...);\n>        int fprintf(FILE *stream, const char *format, ...);\n>        int sprintf(char *str, const char *format, ...);\n>        int snprintf(char *str, size_t size, const char *format, ...);\n> \n>        #include <stdarg.h>\n> \n>        int vprintf(const char *format, va_list ap);\n>        int vfprintf(FILE *stream, const char *format, va_list ap);\n>        int vsprintf(char *str, const char *format, va_list ap);\n>        int vsnprintf(char *str, size_t size, const char *format, va_list ap);\n> \n>    Feature Test Macro Requirements for glibc (see feature_test_macros(7)):\n> \n>        snprintf(), vsnprintf(): _BSD_SOURCE || _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE; or cc -std=c99\n\nThat's a little unfair as a comparison, as it's from a different\nsection. Try \"man IO::Handle\", or most other perl modules, for example.\nThey are quite a bit more verbose.\n\nBut yes, in general it is more verbose than other commands in section 1.\n\n> which would suggest that for git-diff(!) we should say something like:\n> \n> SYNOPSIS\n> \n> \tgit diff [options] [--] [<path>...]\n> \tgit diff [options] --cached [--] [<path>...]\n> \tgit diff [options] <commit> [--] [<path>...]\n> \tgit diff [options] --cached <commit> [--] [<path>...]\n> \tgit diff [options] <commit> <commit> [--] [<path>...]\n> \tgit diff [options] --no-index [--] <path> <path>\n\nI would be OK with that; my comment lines were an attempt to make it a\nbit more clear to the user. But reading your revised versions, they seem\npretty clear to me. I think your example there can actually be collapsed\ndown to:\n\n\tgit diff [options] [<commit>] [--] [<path>...]\n\tgit diff [options] --cached [<commit>] [--] [<path>...]\n\tgit diff [options] <commit> <commit> [--] [<path>...]\n\tgit diff [options] [--no-index] [--] <path> <path>\n\nwhich covers the four major modes.\n\n> I would rather treat --cached as one of the options (\"instead of\n> comparing the worktree, compare its cached content in the index to the\n> specified commit\"),\n\nExcept it is not quite that. For the first two that I listed above,\n--cached makes that distinction. But --cached doesn't make sense at all\nin the third or fourth ones. So I think in practice it ends up defining\na mode of operation more than simply an option.\n\nBut I do recognize that such a distinction is largely in the mental\nmodel of the user. On the other hand, this is documentation, so we are\ntrying to promote healthy mental models for users. :)\n\n> and if I were running the world, I'd leave off the [options]. :)\n\nI have no strong opinion on that. There are pretty few unix programs\nthat don't take [options] at the beginning, so it really is kind of\nsuperfluous. But it's also pretty standard, and clues the user in that\nwe are a normal program.\n\n-Peff\n"},{"id":"155191","messageId":"20101104183851.GA16865@burratino","threadId":"25387","inReplyTo":"20101104181357.GA31016@sigill.intra.peff.net","subject":"Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-11-04T18:38:51Z","receivedAt":"2010-11-04T18:38:51Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Jeff King wrote:\n\n> \tgit diff [options] [<commit>] [--] [<path>...]\n> \tgit diff [options] --cached [<commit>] [--] [<path>...]\n> \tgit diff [options] <commit> <commit> [--] [<path>...]\n> \tgit diff [options] [--no-index] [--] <path> <path>\n> \n> which covers the four major modes.\n\nMakes sense.  There is just one particularity of\n\n\tgit diff --cached [<commit>]\n\nI am worried about.  Namely: according to a recent patch,\n\n\tgit diff --cached\n\nshould not be considered as\n\n\tgit diff --cached HEAD\n\nwith the \"HEAD\" implicit, but a distinct operation meaning\n\"show me what changes git commit would store\".\n\n> On Thu, Nov 04, 2010 at 01:02:42PM -0500, Jonathan Nieder wrote:\n\n>> I would rather treat --cached as one of the options (\"instead of\n>> comparing the worktree, compare its cached content in the index to the\n>> specified commit\"),\n>\n> Except it is not quite that. For the first two that I listed above,\n> --cached makes that distinction. But --cached doesn't make sense at all\n> in the third or fourth ones. So I think in practice it ends up defining\n> a mode of operation more than simply an option.\n\nNot sure I understand your logic.  Is your point that --cached in\nthose cases does not print\n\n\tfatal: --cached does not make sense in this operation mode\n\nbut\n\n\tusage: git diff <options> <rev>{0,2} -- <path>*\n\nthat implies the operation mode is not known?\n\n>                                   There are pretty few unix programs\n> that don't take [options] at the beginning, so it really is kind of\n> superfluous. But it's also pretty standard, and clues the user in that\n> we are a normal program.\n\nYes, sorry about the tangent.\n"},{"id":"155193","messageId":"20101104185545.GB31016@sigill.intra.peff.net","threadId":"25387","inReplyTo":"20101104183851.GA16865@burratino","subject":"Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-11-04T18:55:45Z","receivedAt":"2010-11-04T18:55:45Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Nov 04, 2010 at 01:38:51PM -0500, Jonathan Nieder wrote:\n\n> Makes sense.  There is just one particularity of\n> \n> \tgit diff --cached [<commit>]\n> \n> I am worried about.  Namely: according to a recent patch,\n> \n> \tgit diff --cached\n> \n> should not be considered as\n> \n> \tgit diff --cached HEAD\n> \n> with the \"HEAD\" implicit, but a distinct operation meaning\n> \"show me what changes git commit would store\".\n\nYeah, I'm not sure I agree with that change, for the reason that it\nmakes \"git diff\" more conceptually complex. Generally we think of \"no\ncommit\" as \"behave as if HEAD was given\". But now it's not, but only in\nthis one particular place.\n\nI guess I should go complain in that thread, though...\n\n> >> I would rather treat --cached as one of the options (\"instead of\n> >> comparing the worktree, compare its cached content in the index to the\n> >> specified commit\"),\n> >\n> > Except it is not quite that. For the first two that I listed above,\n> > --cached makes that distinction. But --cached doesn't make sense at all\n> > in the third or fourth ones. So I think in practice it ends up defining\n> > a mode of operation more than simply an option.\n> \n> Not sure I understand your logic.  Is your point that --cached in\n> those cases does not print\n> \n> \tfatal: --cached does not make sense in this operation mode\n> \n> but\n> \n> \tusage: git diff <options> <rev>{0,2} -- <path>*\n> \n> that implies the operation mode is not known?\n\nNo, I am fine with what it actually prints[1]. But my point is that\n\"--cached\" is not simply an option that should go in [options] in each\nsynopsis line. Even though it _looks_ like an option (because it starts\nwith --, and can go anywhere in the options list) it changes the syntax\nof the rest of the command line (in particular, you can provide 0 or 1\ncommits, not 2, and you cannot use --no-index)[2].\n\nRemoving it from the synopsis and just listing it as an option does not\ncapture that aspect.\n\nAnd yes, it's obviously a gray area. There are other mutually exclusive\noptions that are really just normal options. I just happen to think that\nthe action of \"--cached\" changes the operation significantly enough to\nbe considered a separate mode.  Just as we do with \"-m\" and \"-d\" for\ngit-branch.\n\n-Peff\n\n[1] If we are on a quest to remove <rev>{0,2}, this is one other spot to\n    do it.\n\n[2] This ties in with an idea mentioned in years past (but never\n    actually implemented) to have some symbolic name for referring to\n    the working tree and index, like:\n\n       git diff HEAD INDEX\n\n    which makes it quite obvious what is going on, and that diff really\n    only has one syntactic mode: diff thing A and thing B. The details\n    of that depend on what thing A and thing B actually resolve to. But\n    in theory that is identical to \"git diff --cached HEAD\".\n"},{"id":"155200","messageId":"87d3qkhm3d.fsf@gmail.com","threadId":"25387","inReplyTo":"20101104185545.GB31016@sigill.intra.peff.net","subject":"Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings","fromName":"Štěpán Němec","fromEmail":"stepnem@gmail.com","sentAt":"2010-11-04T20:26:14Z","receivedAt":"2010-11-04T20:26:14Z","isPatch":true,"sender":{"key":"stepnem@gmail.com","avatar":"https://avatars.githubusercontent.com/u/106838?v=4"},"body":"Jeff King <peff@peff.net> writes:\n\n[...]\n\n>> \tusage: git diff <options> <rev>{0,2} -- <path>*\n\n[...]\n\n> [1] If we are on a quest to remove <rev>{0,2}, this is one other spot to\n>     do it.\n\nThat's already included in the patch.\n\nI think this thread already has nothing to do with the purpose of the\npatch, though. I find your suggestion that <commit>{0,2} better conveys\nsome information about git-diff's operation modes than [<commit>\n[<commit>]] does (which seems to have been your starting point) rather\nfar-fetched.\n\nNote that I do not feel strongly about removing the {M,N} notation (I\nexpressed my opinion in the thread already[1]), but I see the notation\nproblem as orthogonal to the issues you are discussing here.\n\nSo AIUI the patch can still be applied and we/you can then work on\nimproving the usage string in other ways -- providing that we agree that\nthe {M,N} notation should go, of course, which we apparently still\ndon't?\n\nIn any case this seems to be less and less my itch to scratch, so I'm\nnot sure I'm going to be of much help in this discussion. The thing I\nneed to know for the CodingGuidelines patch is whether we're going to\npreserve and encourage the {M,N} usage or not (so please let's arrive to\nsome conclusion on that matter -- I waited for several days before\nsending the updated version and nobody chimed in, so I assumed nobody\nother than Mark and Sverre really cared). Although, that's actually\nsomewhat orthogonal, too -- we can always re-add the {M,N} subsection\nlater.\n\nThanks,\n\n  Štěpán\n\n[1]\nhttp://thread.gmane.org/gmane.comp.version-control.git/158467/focus=160330\n"},{"id":"155207","messageId":"20101104204304.GA4641@sigill.intra.peff.net","threadId":"25387","inReplyTo":"87d3qkhm3d.fsf@gmail.com","subject":"Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-11-04T20:43:04Z","receivedAt":"2010-11-04T20:43:04Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Nov 04, 2010 at 09:26:14PM +0100, Štěpán Němec wrote:\n\n> > [1] If we are on a quest to remove <rev>{0,2}, this is one other spot to\n> >     do it.\n> \n> That's already included in the patch.\n\nAh, sorry, I missed that hunk.\n\n> I think this thread already has nothing to do with the purpose of the\n> patch, though. I find your suggestion that <commit>{0,2} better conveys\n> some information about git-diff's operation modes than [<commit>\n> [<commit>]] does (which seems to have been your starting point) rather\n> far-fetched.\n\nI find your version slightly harder to read than the original, which is\nwhy I complained. However, I find both way worse than what Jonathan and\nI ended up with.\n\n> So AIUI the patch can still be applied and we/you can then work on\n> improving the usage string in other ways -- providing that we agree that\n> the {M,N} notation should go, of course, which we apparently still\n> don't?\n\nMy main argument against that would be that if we are planning on\nchanging it to something totally different right now anyway, your patch\nwill just end up making textual conflicts for Junio to resolve. :)\n\n> In any case this seems to be less and less my itch to scratch, so I'm\n> not sure I'm going to be of much help in this discussion. The thing I\n> need to know for the CodingGuidelines patch is whether we're going to\n> preserve and encourage the {M,N} usage or not (so please let's arrive to\n> some conclusion on that matter -- I waited for several days before\n> sending the updated version and nobody chimed in, so I assumed nobody\n> other than Mark and Sverre really cared). Although, that's actually\n> somewhat orthogonal, too -- we can always re-add the {M,N} subsection\n> later.\n\nYeah, sorry to come in late to the discussion. I missed the other thread\nentirely. I think getting rid of {M,N} is fine. In general, your\nproposed replacement is better. It's just that in this case it seemed to\nbe obfuscating a subtle point that the original syntax (as ugly and\nincomprehensible as it was) called out.\n\nSo yes, go ahead with your coding guidelines patch. I'll summarize what\nJonathan and I discussed with a new patch.\n\n-Peff\n"},{"id":"155215","messageId":"20101104211729.GA5551@sigill.intra.peff.net","threadId":"25387","inReplyTo":"20101104204304.GA4641@sigill.intra.peff.net","subject":"[PATCH] docs: clarify git diff modes of operation","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-11-04T21:17:29Z","receivedAt":"2010-11-04T21:17:29Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"It is an oversimplification to say that we can take\n\"[<commit> [<commit>]]\", as it really depends on what\noptions have been given. Instead, let's list the major modes\nof operation separately, as we do in other manpages.\n\nThis patch also adjusts the text immediately after the\nsynopsis to match the lines given in the synopsis.\n\nFor git-difftool, which has the same issue, let's refer the\nuser to the git-diff manpage rather than spelling it all out\nagain.\n\nSigned-off-by: Jeff King <peff@peff.net>\n---\nOn Thu, Nov 04, 2010 at 04:43:04PM -0400, Jeff King wrote:\n\n> > So AIUI the patch can still be applied and we/you can then work on\n> > improving the usage string in other ways -- providing that we agree that\n> > the {M,N} notation should go, of course, which we apparently still\n> > don't?\n> \n> My main argument against that would be that if we are planning on\n> changing it to something totally different right now anyway, your patch\n> will just end up making textual conflicts for Junio to resolve. :)\n\nI had intially thought I would tweak all three sites that you did, but\nafter thinking about it, I really just want to change the one in\nDocumentation/git-diff.txt. Which turned my patch into a mix of two\ndifferent changes, and means it probably should just go on top of yours.\n\nSo here is my patch, which should apply on top of yours.\n\nNote that in all versions (the original, yours, and mine) we gloss over\nthe fact that <commit> can actually be any two objects (as long as they\nare bother either tree-ishs or blobs). I'm not sure if it is worth\ndocumenting that subtlety here (at least the tree-ish thing gets\nmentioned later in the description; I'm not sure we ever document \"git\ndiff HEAD:Makefile HEAD^:Makefile\" anywhere).\n\nJonathan, does this look ok based on our earlier discussion?\n\n Documentation/git-diff.txt     |   11 ++++++++---\n Documentation/git-difftool.txt |    3 ++-\n 2 files changed, 10 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex 61728f6..f6ac847 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -8,12 +8,17 @@ git-diff - Show changes between commits, commit and working tree, etc\n \n SYNOPSIS\n --------\n-'git diff' [<common diff options>] [<commit> [<commit>]] [--] [<path>...]\n+[verse]\n+'git diff' [options] [<commit>] [--] [<path>...]\n+'git diff' [options] --cached [<commit>] [--] [<path>...]\n+'git diff' [options] <commit> <commit> [--] [<path>...]\n+'git diff' [options] [--no-index] [--] <path> <path>\n \n DESCRIPTION\n -----------\n-Show changes between two trees, a tree and the working tree, a\n-tree and the index file, or the index file and the working tree.\n+Show changes between the working tree and the index or a tree, changes\n+between the index and a tree, changes between two trees, or changes\n+between two files on disk.\n \n 'git diff' [--options] [--] [<path>...]::\n \ndiff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt\nindex a02e3b5..6fffbc7 100644\n--- a/Documentation/git-difftool.txt\n+++ b/Documentation/git-difftool.txt\n@@ -13,7 +13,8 @@ DESCRIPTION\n -----------\n 'git difftool' is a git command that allows you to compare and edit files\n between revisions using common diff tools.  'git difftool' is a frontend\n-to 'git diff' and accepts the same options and arguments.\n+to 'git diff' and accepts the same options and arguments. See\n+linkgit:git-diff[1].\n \n OPTIONS\n -------\n-- \n1.7.3.2.218.g4ee9d\n"},{"id":"155217","messageId":"878w18hj3y.fsf@gmail.com","threadId":"25387","inReplyTo":"20101104204304.GA4641@sigill.intra.peff.net","subject":"Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings","fromName":"Štěpán Němec","fromEmail":"stepnem@gmail.com","sentAt":"2010-11-04T21:30:41Z","receivedAt":"2010-11-04T21:30:41Z","isPatch":true,"sender":{"key":"stepnem@gmail.com","avatar":"https://avatars.githubusercontent.com/u/106838?v=4"},"body":"Jeff King <peff@peff.net> writes:\n\n> My main argument against that would be that if we are planning on\n> changing it to something totally different right now anyway, your patch\n> will just end up making textual conflicts for Junio to resolve. :)\n\nRight. I hoped you'd come up with a patch yourself, which now happend,\nso, thank you. :-)\n\n> Yeah, sorry to come in late to the discussion. I missed the other thread\n> entirely. I think getting rid of {M,N} is fine. In general, your\n> proposed replacement is better. It's just that in this case it seemed to\n> be obfuscating a subtle point that the original syntax (as ugly and\n> incomprehensible as it was) called out.\n>\n> So yes, go ahead with your coding guidelines patch. I'll summarize what\n> Jonathan and I discussed with a new patch.\n\nIn that case the v2 [1] is still a valid review target, thanks.\n\nŠtěpán\n\n[1] Earlier in the thread and here for anyone interested:\nhttp://article.gmane.org/gmane.comp.version-control.git/160733\n"},{"id":"155223","messageId":"20101104215056.GA18475@burratino","threadId":"25387","inReplyTo":"20101104211729.GA5551@sigill.intra.peff.net","subject":"Re: [PATCH] docs: clarify git diff modes of operation","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-11-04T21:50:56Z","receivedAt":"2010-11-04T21:50:56Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Jeff King wrote:\n\n> Jonathan, does this look ok based on our earlier discussion?\n\nYep, it's way better than the current state.\n\nThe list of operation modes still seems wrong: in addition to\nthe meaning of\n\n\tgit diff --cached\n\nfrom an unborn branch not fitting the model of implicit HEAD\nas mentioned before, there is also\n\n\tgit diff\n\nnot meaning the same thing as\n\n\tgit diff HEAD\n\n.  So I guess technically the separate operation modes are\n\n\tgit diff [--cached]\n\tgit diff [--cached] <tree>\n\tgit diff <tree> <tree>\n\tgit diff --no-index <path> <path>\n\tgit diff <blob> <blob>\n\nwhere --cached means \"use the version of the work tree stored\nin the index in place of the real thing\".\n"},{"id":"155224","messageId":"871v70hi4k.fsf@gmail.com","threadId":"25387","inReplyTo":"20101104211729.GA5551@sigill.intra.peff.net","subject":"Re: [PATCH] docs: clarify git diff modes of operation","fromName":"Štěpán Němec","fromEmail":"stepnem@gmail.com","sentAt":"2010-11-04T21:51:55Z","receivedAt":"2010-11-04T21:51:55Z","isPatch":true,"sender":{"key":"stepnem@gmail.com","avatar":"https://avatars.githubusercontent.com/u/106838?v=4"},"body":"Jeff King <peff@peff.net> writes:\n\n> Note that in all versions (the original, yours, and mine) we gloss over\n> the fact that <commit> can actually be any two objects (as long as they\n> are bother either tree-ishs or blobs).\n\nYeah, I thought about that, too. I think it would be nice to use more\nprecise placeholders like <tree-ish> or <object> (which do already\noccur in other places), but I suspect it might be needed/useful at more\nplaces and would better be done as a separate patch (preferably by someone\nwho is more familiar with the internals than me).\n\n> I'm not sure if it is worth documenting that subtlety here (at least\n> the tree-ish thing gets mentioned later in the description; I'm not\n> sure we ever document \"git diff HEAD:Makefile HEAD^:Makefile\"\n> anywhere).\n\nThere's gitrevisions(7) (also pointed to from the git-diff manpage)\nwhich describes those in some detail.\n\n  Štěpán\n"},{"id":"155241","messageId":"AANLkTimqA=2+fG10mP=zmXHksHvr6iVZQHRE85ab-aMV@mail.gmail.com","threadId":"25387","inReplyTo":"20101104215056.GA18475@burratino","subject":"Re: [PATCH] docs: clarify git diff modes of operation","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-11-05T01:57:16Z","receivedAt":"2010-11-05T01:57:16Z","isPatch":true,"sender":{"key":"lodatom@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58860?v=4"},"body":"On Thu, Nov 4, 2010 at 5:50 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:\n> .  So I guess technically the separate operation modes are\n>\n>        git diff [--cached]\n>        git diff [--cached] <tree>\n>        git diff <tree> <tree>\n>        git diff --no-index <path> <path>\n>        git diff <blob> <blob>\n>\n> where --cached means \"use the version of the work tree stored\n> in the index in place of the real thing\".\n\nI prefer this above the other proposals.  This breakdown makes the\nmost sense to me, and I see no reason to use <commit> when we really\nmean <tree>.  One minor thing: should the \"<blob> <blob>\" form be\nmoved above \"<path> <path>\" so that all the git object forms are\ntogether?\n\nOn a related note, I find it a bit confusing that <path> is used to\nmean two very different things.  For \"<path> <path>\", it means a file\nthat must exist on disk.  For \"[<path>...]\", it means a pattern on\nwhich to filter the output of the command.  Since we already have a\nname for the latter, perhaps we should use the term \"[<pathspec>...]\".\n"}]}