* [PATCH/RFC] Unify argument and option notation in the docs
@ 2010-10-08 0:52 Štěpán Němec
2010-10-08 7:43 ` Jonathan Nieder
0 siblings, 1 reply; 43+ messages in thread
From: Štěpán Němec @ 2010-10-08 0:52 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git, Jonathan Nieder
In general, the current usage is already pretty consistent, so it is
not too hard to induce the guidelines and correct the rest based on
them.
Some examples of what this patch is based on (i.e., the current
prevalent usage) follow (all coming from existing documentation):
Placeholders are enclosed in angle brackets:
<file>
--sort=<key>
--abbrev[=<n>]
Possibility of multiple occurences is indicated by three dots:
<file>...
(One or more of <file>.)
Optional parts are enclosed in square brackets:
git-archive:
[<extra>]
(Zero or one <extra>.)
git-apply:
[<patch>...]
(Any number of <patch>. Note that the dots are inside, not outside
the brackets.)
Parentheses are used for grouping:
git-bisect:
[(<rev>|<range>)...]
(Any number of either <rev> or <range>. Parens are needed to make it
clear that `...' pertains to both <rev> and <range>.)
git-remote:
git remote set-head <name> (-a | -d | <branch>)
(One and only one of `-a', `-d' or `<branch>' _must_ (no square
brackets) be provided.)
Limited number of occurences is indicated as follows:
git-diff:
<commit>{0,2}
(Up to two <commit>s.)
---
[It is conceivable I could submit this as a series of smaller patches,
but the problems this is solving didn't seem diverse enough to me to
warrant that.
As for the "methodology" used -- I grepped for places similar to what I
wanted to fix (cf.
<http://article.gmane.org/gmane.comp.version-control.git/158445>, then I
noticed other related problems and grepped for them etc. All the edits
are manual, though.]
Two questions:
1. Is `[--refs [--unpacked | --all]]' in `git-pack-object' documentation
correct? From my reading of builtin/pack-objects.c, `--unpacked' and
`--all' do the same thing and both imply --refs, so perhaps [--refs |
--unpacked | --all] would make more sense? (I also noticed that the
--reflog option is shown in the usage string but undocumented.)
2. I left in one special case, namely the GIT_* variables in `git(1)'
synopsis section as values for the `--exec-path' and other options.
Further in the text the usual <path> placeholders are used and I believe
those should be used in the synopsis as well, but whoever used the GIT_*
variables obviously did it to point out that they provide an alternative
way to set those options, so I figured I'd leave them in for now and ask
for opinions first.
Documentation/diff-options.txt | 14 +++++-----
Documentation/git-am.txt | 4 +-
Documentation/git-apply.txt | 6 ++--
Documentation/git-archive.txt | 4 +-
Documentation/git-bundle.txt | 6 ++--
Documentation/git-checkout-index.txt | 2 +-
Documentation/git-commit-tree.txt | 2 +-
Documentation/git-daemon.txt | 48 +++++++++++++++++-----------------
Documentation/git-fast-export.txt | 2 +-
Documentation/git-fetch.txt | 2 +-
Documentation/git-filter-branch.txt | 2 +-
Documentation/git-for-each-ref.txt | 2 +-
Documentation/git-index-pack.txt | 4 +-
Documentation/git-init.txt | 2 +-
Documentation/git-ls-files.txt | 2 +-
Documentation/git-ls-tree.txt | 10 +++---
Documentation/git-mailsplit.txt | 2 +-
Documentation/git-mergetool.txt | 2 +-
Documentation/git-pack-objects.txt | 16 +++++-----
Documentation/git-relink.txt | 2 +-
Documentation/git-remote.txt | 2 +-
Documentation/git-repack.txt | 12 ++++----
Documentation/git-rev-list.txt | 18 ++++++------
Documentation/git-rev-parse.txt | 2 +-
Documentation/git-shortlog.txt | 2 +-
Documentation/git-show-branch.txt | 2 +-
Documentation/git-svn.txt | 2 +-
Documentation/git-update-index.txt | 4 +-
Documentation/git-web--browse.txt | 16 +++++-----
Documentation/git.txt | 6 ++--
Documentation/merge-strategies.txt | 2 +-
Documentation/pretty-options.txt | 4 +-
Documentation/rev-list-options.txt | 18 ++++++------
Documentation/user-manual.txt | 2 +-
archive.c | 4 +-
builtin/bundle.c | 4 +-
builtin/checkout-index.c | 2 +-
builtin/commit-tree.c | 2 +-
builtin/fetch.c | 2 +-
builtin/grep.c | 2 +-
builtin/index-pack.c | 2 +-
builtin/ls-files.c | 2 +-
builtin/ls-tree.c | 2 +-
builtin/mailsplit.c | 2 +-
builtin/pack-objects.c | 10 +++---
builtin/remote.c | 2 +-
builtin/rev-list.c | 8 +++---
builtin/show-branch.c | 2 +-
builtin/update-index.c | 2 +-
daemon.c | 18 ++++++------
fast-import.c | 2 +-
git-am.sh | 2 +-
git-relink.perl | 2 +-
git.c | 4 +-
upload-pack.c | 2 +-
55 files changed, 152 insertions(+), 152 deletions(-)
diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index f77a0f8..719f589 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -48,9 +48,9 @@ endif::git-format-patch[]
--patience::
Generate a diff using the "patience diff" algorithm.
---stat[=width[,name-width]]::
+--stat[=<width>[,<name-width>]]::
Generate a diffstat. You can override the default
- output width for 80-column terminal by `--stat=width`.
+ output width for 80-column terminal by `--stat=<width>`.
The width of the filename part can be controlled by
giving another width to it separated by a comma.
@@ -66,14 +66,14 @@ endif::git-format-patch[]
number of modified files, as well as number of added and deleted
lines.
---dirstat[=limit]::
+--dirstat[=<limit>]::
Output the distribution of relative amount of changes (number of lines added or
removed) for each sub-directory. Directories with changes below
a cut-off percent (3% by default) are not shown. The cut-off percent
- can be set with `--dirstat=limit`. Changes in a child directory is not
+ can be set with `--dirstat=<limit>`. Changes in a child directory are not
counted for the parent directory, unless `--cumulative` is used.
---dirstat-by-file[=limit]::
+--dirstat-by-file[=<limit>]::
Same as `--dirstat`, but counts changed files instead of lines.
--summary::
@@ -248,13 +248,13 @@ endif::git-log[]
If `n` is specified, it has the same meaning as for `-M<n>`.
ifndef::git-format-patch[]
---diff-filter=[ACDMRTUXB*]::
+--diff-filter=<spec>::
+ '<spec>' can be any combination of the characters `ACDMRTUXB*`.
Select only files that are Added (`A`), Copied (`C`),
Deleted (`D`), Modified (`M`), Renamed (`R`), have their
type (i.e. regular file, symlink, submodule, ...) changed (`T`),
are Unmerged (`U`), are
Unknown (`X`), or have had their pairing Broken (`B`).
- Any combination of the filter characters may be used.
When `*` (All-or-none) is added to the combination, all
paths are selected if there is any file that matches
other criteria in the comparison; if there is no file
diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index 9e62f87..51297d0 100644
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt
@@ -14,7 +14,7 @@ SYNOPSIS
[--ignore-date] [--ignore-space-change | --ignore-whitespace]
[--whitespace=<option>] [-C<n>] [-p<n>] [--directory=<dir>]
[--reject] [-q | --quiet] [--scissors | --no-scissors]
- [<mbox> | <Maildir>...]
+ [(<mbox> | <Maildir>)...]
'git am' (--continue | --skip | --abort)
DESCRIPTION
@@ -25,7 +25,7 @@ current branch.
OPTIONS
-------
-<mbox>|<Maildir>...::
+(<mbox>|<Maildir>)...::
The list of mailbox files to read patches from. If you do not
supply this argument, the command reads from the standard input.
If you supply directories, they will be treated as Maildirs.
diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
index 4a74b23..881652f 100644
--- a/Documentation/git-apply.txt
+++ b/Documentation/git-apply.txt
@@ -12,10 +12,10 @@ SYNOPSIS
'git apply' [--stat] [--numstat] [--summary] [--check] [--index]
[--apply] [--no-add] [--build-fake-ancestor=<file>] [-R | --reverse]
[--allow-binary-replacement | --binary] [--reject] [-z]
- [-pNUM] [-CNUM] [--inaccurate-eof] [--recount] [--cached]
+ [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached]
[--ignore-space-change | --ignore-whitespace ]
- [--whitespace=<nowarn|warn|fix|error|error-all>]
- [--exclude=PATH] [--include=PATH] [--directory=<root>]
+ [--whitespace=(nowarn|warn|fix|error|error-all)]
+ [--exclude=<path>] [--include=<path>] [--directory=<root>]
[--verbose] [<patch>...]
DESCRIPTION
diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt
index 8d3e666..4163a1b 100644
--- a/Documentation/git-archive.txt
+++ b/Documentation/git-archive.txt
@@ -12,7 +12,7 @@ SYNOPSIS
'git archive' [--format=<fmt>] [--list] [--prefix=<prefix>/] [<extra>]
[-o | --output=<file>] [--worktree-attributes]
[--remote=<repo> [--exec=<git-upload-archive>]] <tree-ish>
- [path...]
+ [<path>...]
DESCRIPTION
-----------
@@ -73,7 +73,7 @@ OPTIONS
<tree-ish>::
The tree or commit to produce an archive for.
-path::
+<path>::
Without an optional path parameter, all files and subdirectories
of the current working directory are included in the archive.
If one or more paths are specified, only these are included.
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 38e59af..6266a3a 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -11,8 +11,8 @@ SYNOPSIS
[verse]
'git bundle' create <file> <git-rev-list-args>
'git bundle' verify <file>
-'git bundle' list-heads <file> [refname...]
-'git bundle' unbundle <file> [refname...]
+'git bundle' list-heads <file> [<refname>...]
+'git bundle' unbundle <file> [<refname>...]
DESCRIPTION
-----------
@@ -68,7 +68,7 @@ unbundle <file>::
packaged.
-[refname...]::
+[<refname>...]::
A list of references used to limit the references reported as
available. This is principally of use to 'git fetch', which
expects to receive only those references asked for and not
diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt
index 62f9ab2..0c0a9c1 100644
--- a/Documentation/git-checkout-index.txt
+++ b/Documentation/git-checkout-index.txt
@@ -13,7 +13,7 @@ SYNOPSIS
[--stage=<number>|all]
[--temp]
[-z] [--stdin]
- [--] [<file>]*
+ [--] [<file>...]
DESCRIPTION
-----------
diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt
index 349366e..5dcf427 100644
--- a/Documentation/git-commit-tree.txt
+++ b/Documentation/git-commit-tree.txt
@@ -8,7 +8,7 @@ git-commit-tree - Create a new commit object
SYNOPSIS
--------
-'git commit-tree' <tree> [-p <parent commit>]* < changelog
+'git commit-tree' <tree> [(-p <parent commit>)...] < changelog
DESCRIPTION
-----------
diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt
index 01c9f8e..2f0ddf6 100644
--- a/Documentation/git-daemon.txt
+++ b/Documentation/git-daemon.txt
@@ -9,15 +9,15 @@ SYNOPSIS
--------
[verse]
'git daemon' [--verbose] [--syslog] [--export-all]
- [--timeout=n] [--init-timeout=n] [--max-connections=n]
- [--strict-paths] [--base-path=path] [--base-path-relaxed]
- [--user-path | --user-path=path]
- [--interpolated-path=pathtemplate]
- [--reuseaddr] [--detach] [--pid-file=file]
- [--enable=service] [--disable=service]
- [--allow-override=service] [--forbid-override=service]
- [--inetd | [--listen=host_or_ipaddr] [--port=n] [--user=user [--group=group]]
- [directory...]
+ [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>]
+ [--strict-paths] [--base-path=<path>] [--base-path-relaxed]
+ [--user-path | --user-path=<path>]
+ [--interpolated-path=<pathtemplate>]
+ [--reuseaddr] [--detach] [--pid-file=<file>]
+ [--enable=<service>] [--disable=<service>]
+ [--allow-override=<service>] [--forbid-override=<service>]
+ [--inetd | [--listen=<host_or_ipaddr>] [--port=<n>] [--user=<user> [--group=<group>]]
+ [<directory>...]
DESCRIPTION
-----------
@@ -48,7 +48,7 @@ OPTIONS
'git daemon' will refuse to start when this option is enabled and no
whitelist is specified.
---base-path=path::
+--base-path=<path>::
Remap all the path requests as relative to the given path.
This is sort of "GIT root" - if you run 'git daemon' with
'--base-path=/srv/git' on example.com, then if you later try to pull
@@ -61,7 +61,7 @@ OPTIONS
This is useful for switching to --base-path usage, while still
allowing the old paths.
---interpolated-path=pathtemplate::
+--interpolated-path=<pathtemplate>::
To support virtual hosting, an interpolated path template can be
used to dynamically construct alternate paths. The template
supports %H for the target hostname as supplied by the client but
@@ -80,27 +80,27 @@ OPTIONS
Have the server run as an inetd service. Implies --syslog.
Incompatible with --port, --listen, --user and --group options.
---listen=host_or_ipaddr::
+--listen=<host_or_ipaddr>::
Listen on a specific IP address or hostname. IP addresses can
be either an IPv4 address or an IPv6 address if supported. If IPv6
is not supported, then --listen=hostname is also not supported and
--listen must be given an IPv4 address.
Incompatible with '--inetd' option.
---port=n::
+--port=<n>::
Listen on an alternative port. Incompatible with '--inetd' option.
---init-timeout=n::
+--init-timeout=<n>::
Timeout between the moment the connection is established and the
client request is received (typically a rather low value, since
that should be basically immediate).
---timeout=n::
+--timeout=<n>::
Timeout for specific client sub-requests. This includes the time
it takes for the server to process the sub-request and the time spent
waiting for the next client's request.
---max-connections=n::
+--max-connections=<n>::
Maximum number of concurrent clients, defaults to 32. Set it to
zero for no limit.
@@ -109,7 +109,7 @@ OPTIONS
--verbose, thus by default only error conditions will be logged.
--user-path::
---user-path=path::
+--user-path=<path>::
Allow {tilde}user notation to be used in requests. When
specified with no parameter, requests to
git://host/{tilde}alice/foo is taken as a request to access
@@ -129,12 +129,12 @@ OPTIONS
--detach::
Detach from the shell. Implies --syslog.
---pid-file=file::
+--pid-file=<file>::
Save the process id in 'file'. Ignored when the daemon
is run under `--inetd`.
---user=user::
---group=group::
+--user=<user>::
+--group=<group>::
Change daemon's uid and gid before entering the service loop.
When only `--user` is given without `--group`, the
primary group ID for the user is used. The values of
@@ -145,16 +145,16 @@ Giving these options is an error when used with `--inetd`; use
the facility of inet daemon to achieve the same before spawning
'git daemon' if needed.
---enable=service::
---disable=service::
+--enable=<service>::
+--disable=<service>::
Enable/disable the service site-wide per default. Note
that a service disabled site-wide can still be enabled
per repository if it is marked overridable and the
repository enables the service with a configuration
item.
---allow-override=service::
---forbid-override=service::
+--allow-override=<service>::
+--forbid-override=<service>::
Allow/forbid overriding the site-wide default with per
repository configuration. By default, all the services
are overridable.
diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt
index fcad113..e05b686 100644
--- a/Documentation/git-fast-export.txt
+++ b/Documentation/git-fast-export.txt
@@ -96,7 +96,7 @@ marks the same across runs.
in the commit (as opposed to just listing the files which are
different from the commit's first parent).
-[git-rev-list-args...]::
+[<git-rev-list-args>...]::
A list of arguments, acceptable to 'git rev-parse' and
'git rev-list', that specifies the specific objects and references
to export. For example, `master{tilde}10..master` causes the
diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt
index 400fe7f..d159e88 100644
--- a/Documentation/git-fetch.txt
+++ b/Documentation/git-fetch.txt
@@ -12,7 +12,7 @@ SYNOPSIS
'git fetch' [<options>] <group>
-'git fetch' --multiple [<options>] [<repository> | <group>]...
+'git fetch' --multiple [<options>] [(<repository> | <group>)...]
'git fetch' --all [<options>]
diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
index f51860d..796e748 100644
--- a/Documentation/git-filter-branch.txt
+++ b/Documentation/git-filter-branch.txt
@@ -117,7 +117,7 @@ OPTIONS
This is the filter for performing the commit.
If this filter is specified, it will be called instead of the
'git commit-tree' command, with arguments of the form
- "<TREE_ID> [-p <PARENT_COMMIT_ID>]..." and the log message on
+ "<TREE_ID> [(-p <PARENT_COMMIT_ID>)...]" and the log message on
stdin. The commit id is expected on stdout.
+
As a special extension, the commit filter may emit multiple
diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index d66fd9d..fac1cf5 100644
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -9,7 +9,7 @@ SYNOPSIS
--------
[verse]
'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl]
- [--sort=<key>]* [--format=<format>] [<pattern>...]
+ [(--sort=<key>)...] [--format=<format>] [<pattern>...]
DESCRIPTION
-----------
diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt
index f3ccc72..c2bb810 100644
--- a/Documentation/git-index-pack.txt
+++ b/Documentation/git-index-pack.txt
@@ -59,10 +59,10 @@ OPTIONS
the newly constructed pack and index before refs can be
updated to use objects contained in the pack.
---keep='why'::
+--keep=<msg>::
Like --keep create a .keep file before moving the index into
its final destination, but rather than creating an empty file
- place 'why' followed by an LF into the .keep file. The 'why'
+ place '<msg>' followed by an LF into the .keep file. The '<msg>'
message can later be searched for within all .keep files to
locate any which have outlived their usefulness.
diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index 246b07e..00d4a12 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -31,7 +31,7 @@ current working directory.
Specify the directory from which templates will be used. (See the "TEMPLATE
DIRECTORY" section below.)
---shared[={false|true|umask|group|all|world|everybody|0xxx}]::
+--shared[=(false|true|umask|group|all|world|everybody|0xxx)]::
Specify that the git repository is to be shared amongst several users. This
allows users belonging to the same group to push into that
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 347f447..86abd13 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -17,7 +17,7 @@ SYNOPSIS
[--exclude-per-directory=<file>]
[--exclude-standard]
[--error-unmatch] [--with-tree=<tree-ish>]
- [--full-name] [--abbrev] [--] [<file>]*
+ [--full-name] [--abbrev] [--] [<file>...]
DESCRIPTION
-----------
diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
index 1f89d36..76ed625 100644
--- a/Documentation/git-ls-tree.txt
+++ b/Documentation/git-ls-tree.txt
@@ -10,8 +10,8 @@ SYNOPSIS
--------
[verse]
'git ls-tree' [-d] [-r] [-t] [-l] [-z]
- [--name-only] [--name-status] [--full-name] [--full-tree] [--abbrev=[<n>]]
- <tree-ish> [paths...]
+ [--name-only] [--name-status] [--full-name] [--full-tree] [--abbrev[=<n>]]
+ <tree-ish> [<path>...]
DESCRIPTION
-----------
@@ -19,11 +19,11 @@ Lists the contents of a given tree object, like what "/bin/ls -a" does
in the current working directory. Note that:
- the behaviour is slightly different from that of "/bin/ls" in that the
- 'paths' denote just a list of patterns to match, e.g. so specifying
+ '<path>' denotes just a list of patterns to match, e.g. so specifying
directory name (without '-r') will behave differently, and order of the
arguments does not matter.
- - the behaviour is similar to that of "/bin/ls" in that the 'paths' is
+ - the behaviour is similar to that of "/bin/ls" in that the '<path>' is
taken as relative to the current working directory. E.g. when you are
in a directory 'sub' that has a directory 'dir', you can run 'git
ls-tree -r HEAD dir' to list the contents of the tree (that is
@@ -72,7 +72,7 @@ OPTIONS
Do not limit the listing to the current working directory.
Implies --full-name.
-paths::
+[<path>...]::
When paths are given, show them (note that this isn't really raw
pathnames, but rather a list of patterns to match). Otherwise
implicitly uses the root level of the tree as the sole path argument.
diff --git a/Documentation/git-mailsplit.txt b/Documentation/git-mailsplit.txt
index a634485..71912a1 100644
--- a/Documentation/git-mailsplit.txt
+++ b/Documentation/git-mailsplit.txt
@@ -7,7 +7,7 @@ git-mailsplit - Simple UNIX mbox splitter program
SYNOPSIS
--------
-'git mailsplit' [-b] [-f<nn>] [-d<prec>] [--keep-cr] -o<directory> [--] [<mbox>|<Maildir>...]
+'git mailsplit' [-b] [-f<nn>] [-d<prec>] [--keep-cr] -o<directory> [--] [(<mbox>|<Maildir>)...]
DESCRIPTION
-----------
diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt
index e4ed016..1f75a84 100644
--- a/Documentation/git-mergetool.txt
+++ b/Documentation/git-mergetool.txt
@@ -7,7 +7,7 @@ git-mergetool - Run merge conflict resolution tools to resolve merge conflicts
SYNOPSIS
--------
-'git mergetool' [--tool=<tool>] [-y|--no-prompt|--prompt] [<file>]...
+'git mergetool' [--tool=<tool>] [-y|--no-prompt|--prompt] [<file>...]
DESCRIPTION
-----------
diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
index 8ed09c0..65eff66 100644
--- a/Documentation/git-pack-objects.txt
+++ b/Documentation/git-pack-objects.txt
@@ -11,8 +11,8 @@ SYNOPSIS
[verse]
'git pack-objects' [-q | --progress | --all-progress] [--all-progress-implied]
[--no-reuse-delta] [--delta-base-offset] [--non-empty]
- [--local] [--incremental] [--window=N] [--depth=N]
- [--revs [--unpacked | --all]*] [--stdout | base-name]
+ [--local] [--incremental] [--window=<n>] [--depth=<n>]
+ [--revs [--unpacked | --all]] [--stdout | base-name]
[--keep-true-parents] < object-list
@@ -82,8 +82,8 @@ base-name::
reference was included in the resulting packfile. This
can be useful to send new tags to native git clients.
---window=[N]::
---depth=[N]::
+--window=<n>::
+--depth=<n>::
These two options affect how the objects contained in
the pack are stored using delta compression. The
objects are first internally sorted by type, size and
@@ -95,10 +95,10 @@ base-name::
times to get to the necessary object.
The default value for --window is 10 and --depth is 50.
---window-memory=[N]::
+--window-memory=<n>::
This option provides an additional limit on top of `--window`;
the window size will dynamically scale down so as to not take
- up more than N bytes in memory. This is useful in
+ up more than '<n>' bytes in memory. This is useful in
repositories with a mix of large and small objects to not run
out of memory with a large window, but still be able to take
advantage of the large window for the smaller objects. The
@@ -106,7 +106,7 @@ base-name::
`--window-memory=0` makes memory usage unlimited, which is the
default.
---max-pack-size=[N]::
+--max-pack-size=<n>::
Maximum size of each output pack file. The size can be suffixed with
"k", "m", or "g". The minimum size allowed is limited to 1 MiB.
If specified, multiple packfiles may be created.
@@ -171,7 +171,7 @@ base-name::
wholesale enforcement of a different compression level on the
packed data is desired.
---compression=[N]::
+--compression=<n>::
Specifies compression level for newly-compressed data in the
generated pack. If not specified, pack compression level is
determined first by pack.compression, then by core.compression,
diff --git a/Documentation/git-relink.txt b/Documentation/git-relink.txt
index 8a5842b..8fc809f 100644
--- a/Documentation/git-relink.txt
+++ b/Documentation/git-relink.txt
@@ -7,7 +7,7 @@ git-relink - Hardlink common objects in local repositories
SYNOPSIS
--------
-'git relink' [--safe] <dir> [<dir>]* <master_dir>
+'git relink' [--safe] <dir>... <master_dir>
DESCRIPTION
-----------
diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt
index aa021b0..0d28feb 100644
--- a/Documentation/git-remote.txt
+++ b/Documentation/git-remote.txt
@@ -20,7 +20,7 @@ SYNOPSIS
'git remote set-url --delete' [--push] <name> <url>
'git remote' [-v | --verbose] 'show' [-n] <name>
'git remote prune' [-n | --dry-run] <name>
-'git remote' [-v | --verbose] 'update' [-p | --prune] [group | remote]...
+'git remote' [-v | --verbose] 'update' [-p | --prune] [(<group> | <remote>)...]
DESCRIPTION
-----------
diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt
index 9566727..27f7865 100644
--- a/Documentation/git-repack.txt
+++ b/Documentation/git-repack.txt
@@ -8,7 +8,7 @@ git-repack - Pack unpacked objects in a repository
SYNOPSIS
--------
-'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [--window=N] [--depth=N]
+'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [--window=<n>] [--depth=<n>]
DESCRIPTION
-----------
@@ -80,8 +80,8 @@ other objects in that pack they already have locally.
this repository (or a direct copy of it)
over HTTP or FTP. See linkgit:git-update-server-info[1].
---window=[N]::
---depth=[N]::
+--window=<n>::
+--depth=<n>::
These two options affect how the objects contained in the pack are
stored using delta compression. The objects are first internally
sorted by type, size and optionally names and compared against the
@@ -91,10 +91,10 @@ other objects in that pack they already have locally.
to be applied that many times to get to the necessary object.
The default value for --window is 10 and --depth is 50.
---window-memory=[N]::
+--window-memory=<n>::
This option provides an additional limit on top of `--window`;
the window size will dynamically scale down so as to not take
- up more than N bytes in memory. This is useful in
+ up more than '<n>' bytes in memory. This is useful in
repositories with a mix of large and small objects to not run
out of memory with a large window, but still be able to take
advantage of the large window for the smaller objects. The
@@ -102,7 +102,7 @@ other objects in that pack they already have locally.
`--window-memory=0` makes memory usage unlimited, which is the
default.
---max-pack-size=[N]::
+--max-pack-size=<n>::
Maximum size of each output pack file. The size can be suffixed with
"k", "m", or "g". The minimum size allowed is limited to 1 MiB.
If specified, multiple packfiles may be created.
diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
index 173f3fc..8e1e329 100644
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.txt
@@ -9,10 +9,10 @@ git-rev-list - Lists commit objects in reverse chronological order
SYNOPSIS
--------
[verse]
-'git rev-list' [ \--max-count=number ]
- [ \--skip=number ]
- [ \--max-age=timestamp ]
- [ \--min-age=timestamp ]
+'git rev-list' [ \--max-count=<number> ]
+ [ \--skip=<number> ]
+ [ \--max-age=<timestamp> ]
+ [ \--min-age=<timestamp> ]
[ \--sparse ]
[ \--merges ]
[ \--no-merges ]
@@ -21,10 +21,10 @@ SYNOPSIS
[ \--full-history ]
[ \--not ]
[ \--all ]
- [ \--branches[=pattern] ]
- [ \--tags[=pattern] ]
- [ \--remotes[=pattern] ]
- [ \--glob=glob-pattern ]
+ [ \--branches[=<pattern>] ]
+ [ \--tags[=<pattern>] ]
+ [ \--remotes[=<pattern>] ]
+ [ \--glob=<glob-pattern> ]
[ \--stdin ]
[ \--quiet ]
[ \--topo-order ]
@@ -37,7 +37,7 @@ SYNOPSIS
[ \--regexp-ignore-case | -i ]
[ \--extended-regexp | -E ]
[ \--fixed-strings | -F ]
- [ \--date={local|relative|default|iso|rfc|short} ]
+ [ \--date=(local|relative|default|iso|rfc|short) ]
[ [\--objects | \--objects-edge] [ \--unpacked ] ]
[ \--pretty | \--header ]
[ \--bisect ]
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 341ca90..4a27643 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -95,7 +95,7 @@ OPTIONS
unfortunately named tag "master"), and show them as full
refnames (e.g. "refs/heads/master").
---abbrev-ref[={strict|loose}]::
+--abbrev-ref[=(strict|loose)]::
A non-ambiguous short name of the objects name.
The option core.warnAmbiguousRefs is used to select the strict
abbreviation mode.
diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt
index bc1ac77..5cc3baf 100644
--- a/Documentation/git-shortlog.txt
+++ b/Documentation/git-shortlog.txt
@@ -44,7 +44,7 @@ OPTIONS
--email::
Show the email address of each author.
---format[='<format>']::
+--format[=<format>]::
Instead of the commit subject, use some other information to
describe each commit. '<format>' can be any string accepted
by the `--format` option of 'git log', such as '{asterisk} [%h] %s'.
diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt
index 6453263..bd9f886 100644
--- a/Documentation/git-show-branch.txt
+++ b/Documentation/git-show-branch.txt
@@ -12,7 +12,7 @@ SYNOPSIS
[--current] [--color[=<when>] | --no-color] [--sparse]
[--more=<n> | --list | --independent | --merge-base]
[--no-name | --sha1-name] [--topics]
- [<rev> | <glob>]...
+ [(<rev> | <glob>)...]
'git show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>]
diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index be8a51f..139d314 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -438,7 +438,7 @@ git rebase --onto remotes/git-svn A^ master
OPTIONS
-------
---shared[={false|true|umask|group|all|world|everybody}]::
+--shared[=(false|true|umask|group|all|world|everybody)]::
--template=<template_directory>::
Only used with the 'init' command.
These are passed directly to 'git init'.
diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index 74d1d49..a5782a6 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -12,7 +12,7 @@ SYNOPSIS
'git update-index'
[--add] [--remove | --force-remove] [--replace]
[--refresh] [-q] [--unmerged] [--ignore-missing]
- [--cacheinfo <mode> <object> <file>]*
+ [(--cacheinfo <mode> <object> <file>)...]
[--chmod=(+|-)x]
[--assume-unchanged | --no-assume-unchanged]
[--skip-worktree | --no-skip-worktree]
@@ -21,7 +21,7 @@ SYNOPSIS
[--info-only] [--index-info]
[-z] [--stdin]
[--verbose]
- [--] [<file>]*
+ [--] [<file>...]
DESCRIPTION
-----------
diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt
index e1586c7..51e8e0a 100644
--- a/Documentation/git-web--browse.txt
+++ b/Documentation/git-web--browse.txt
@@ -32,19 +32,19 @@ Custom commands may also be specified.
OPTIONS
-------
--b BROWSER::
---browser=BROWSER::
- Use the specified BROWSER. It must be in the list of supported
+-b <browser>::
+--browser=<browser>::
+ Use the specified browser. It must be in the list of supported
browsers.
--t BROWSER::
---tool=BROWSER::
+-t <browser>::
+--tool=<browser>::
Same as above.
--c CONF.VAR::
---config=CONF.VAR::
+-c <conf.var>::
+--config=<conf.var>::
CONF.VAR is looked up in the git config files. If it's set,
- then its value specify the browser that should be used.
+ then its value specifies the browser that should be used.
CONFIGURATION VARIABLES
-----------------------
diff --git a/Documentation/git.txt b/Documentation/git.txt
index dd57bdc..2e1b2c0 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -12,8 +12,8 @@ SYNOPSIS
'git' [--version] [--exec-path[=GIT_EXEC_PATH]] [--html-path]
[-p|--paginate|--no-pager] [--no-replace-objects]
[--bare] [--git-dir=GIT_DIR] [--work-tree=GIT_WORK_TREE]
- [-c name=value]
- [--help] COMMAND [ARGS]
+ [-c <name>=<value>]
+ [--help] <command> [<args>]
DESCRIPTION
-----------
@@ -28,7 +28,7 @@ also want to read linkgit:gitcvs-migration[7]. See
the link:user-manual.html[Git User's Manual] for a more in-depth
introduction.
-The COMMAND is either a name of a Git command (see below) or an alias
+The '<command>' is either a name of a Git command (see below) or an alias
as defined in the configuration file (see linkgit:git-config[1]).
Formatted and hyperlinked version of the latest git
diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt
index 049313d..8676e26 100644
--- a/Documentation/merge-strategies.txt
+++ b/Documentation/merge-strategies.txt
@@ -52,7 +52,7 @@ no-renormalize;;
Disables the `renormalize` option. This overrides the
`merge.renormalize` configuration variable.
-subtree[=path];;
+subtree[=<path>];;
This option is a more advanced form of 'subtree' strategy, where
the strategy makes a guess on how two trees must be shifted to
match with each other when merging. Instead, the specified path
diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt
index 9b6f389..50923e2 100644
--- a/Documentation/pretty-options.txt
+++ b/Documentation/pretty-options.txt
@@ -1,5 +1,5 @@
---pretty[='<format>']::
---format='<format>'::
+--pretty[=<format>]::
+--format=<format>::
Pretty-print the contents of the commit logs in a given format,
where '<format>' can be one of 'oneline', 'short', 'medium',
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index ebc0108..7a42567 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -13,7 +13,7 @@ include::pretty-options.txt[]
Synonym for `--date=relative`.
---date={relative,local,default,iso,rfc,short,raw}::
+--date=(relative|local|default|iso|rfc|short|raw)::
Only takes effect for dates shown in human-readable format, such
as when using "--pretty". `log.date` config variable sets a default
@@ -246,29 +246,29 @@ endif::git-rev-list[]
Pretend as if all the refs in `refs/` are listed on the
command line as '<commit>'.
---branches[=pattern]::
+--branches[=<pattern>]::
Pretend as if all the refs in `refs/heads` are listed
- on the command line as '<commit>'. If `pattern` is given, limit
+ on the command line as '<commit>'. If '<pattern>' is given, limit
branches to ones matching given shell glob. If pattern lacks '?',
'*', or '[', '/*' at the end is implied.
---tags[=pattern]::
+--tags[=<pattern>]::
Pretend as if all the refs in `refs/tags` are listed
- on the command line as '<commit>'. If `pattern` is given, limit
+ on the command line as '<commit>'. If '<pattern>' is given, limit
tags to ones matching given shell glob. If pattern lacks '?', '*',
or '[', '/*' at the end is implied.
---remotes[=pattern]::
+--remotes[=<pattern>]::
Pretend as if all the refs in `refs/remotes` are listed
- on the command line as '<commit>'. If `pattern`is given, limit
+ on the command line as '<commit>'. If '<pattern>' is given, limit
remote tracking branches to ones matching given shell glob.
If pattern lacks '?', '*', or '[', '/*' at the end is implied.
---glob=glob-pattern::
- Pretend as if all the refs matching shell glob `glob-pattern`
+--glob=<glob-pattern>::
+ Pretend as if all the refs matching shell glob '<glob-pattern>'
are listed on the command line as '<commit>'. Leading 'refs/',
is automatically prepended if missing. If pattern lacks '?', '*',
or '[', '/*' at the end is implied.
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index ce45bfc..cb3b98a 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -3850,7 +3850,7 @@ You create a commit object by giving it the tree that describes the
state at the time of the commit, and a list of parents:
-------------------------------------------------
-$ git commit-tree <tree> -p <parent> [-p <parent2> ..]
+$ git commit-tree <tree> -p <parent> [(-p <parent2>)...]
-------------------------------------------------
and then giving the reason for the commit on stdin (either through
diff --git a/archive.c b/archive.c
index edd6853..f59afda 100644
--- a/archive.c
+++ b/archive.c
@@ -7,9 +7,9 @@
#include "unpack-trees.h"
static char const * const archive_usage[] = {
- "git archive [options] <tree-ish> [path...]",
+ "git archive [options] <tree-ish> [<path>...]",
"git archive --list",
- "git archive --remote <repo> [--exec <cmd>] [options] <tree-ish> [path...]",
+ "git archive --remote <repo> [--exec <cmd>] [options] <tree-ish> [<path>...]",
"git archive --remote <repo> [--exec <cmd>] --list",
NULL
};
diff --git a/builtin/bundle.c b/builtin/bundle.c
index 80649ba..9b87fb9 100644
--- a/builtin/bundle.c
+++ b/builtin/bundle.c
@@ -12,8 +12,8 @@
static const char builtin_bundle_usage[] =
"git bundle create <file> <git-rev-list args>\n"
" or: git bundle verify <file>\n"
- " or: git bundle list-heads <file> [refname...]\n"
- " or: git bundle unbundle <file> [refname...]";
+ " or: git bundle list-heads <file> [<refname>...]\n"
+ " or: git bundle unbundle <file> [<refname>...]";
int cmd_bundle(int argc, const char **argv, const char *prefix)
{
diff --git a/builtin/checkout-index.c b/builtin/checkout-index.c
index a7a5ee1..65cbee0 100644
--- a/builtin/checkout-index.c
+++ b/builtin/checkout-index.c
@@ -155,7 +155,7 @@ static void checkout_all(const char *prefix, int prefix_length)
}
static const char * const builtin_checkout_index_usage[] = {
- "git checkout-index [options] [--] <file>...",
+ "git checkout-index [options] [--] [<file>...]",
NULL
};
diff --git a/builtin/commit-tree.c b/builtin/commit-tree.c
index 87f0591..e065739 100644
--- a/builtin/commit-tree.c
+++ b/builtin/commit-tree.c
@@ -9,7 +9,7 @@
#include "builtin.h"
#include "utf8.h"
-static const char commit_tree_usage[] = "git commit-tree <sha1> [-p <sha1>]* < changelog";
+static const char commit_tree_usage[] = "git commit-tree <sha1> [(-p <sha1>)...] < changelog";
static void new_parent(struct commit *parent, struct commit_list **parents_p)
{
diff --git a/builtin/fetch.c b/builtin/fetch.c
index 6fc5047..d35f000 100644
--- a/builtin/fetch.c
+++ b/builtin/fetch.c
@@ -16,7 +16,7 @@
static const char * const builtin_fetch_usage[] = {
"git fetch [<options>] [<repository> [<refspec>...]]",
"git fetch [<options>] <group>",
- "git fetch --multiple [<options>] [<repository> | <group>]...",
+ "git fetch --multiple [<options>] [(<repository> | <group>)...]",
"git fetch --all [<options>]",
NULL
};
diff --git a/builtin/grep.c b/builtin/grep.c
index da32f3d..3d5f6ac 100644
--- a/builtin/grep.c
+++ b/builtin/grep.c
@@ -24,7 +24,7 @@
#endif
static char const * const grep_usage[] = {
- "git grep [options] [-e] <pattern> [<rev>...] [[--] path...]",
+ "git grep [options] [-e] <pattern> [<rev>...] [[--] <path>...]",
NULL
};
diff --git a/builtin/index-pack.c b/builtin/index-pack.c
index e243d9d..8dc5c0b 100644
--- a/builtin/index-pack.c
+++ b/builtin/index-pack.c
@@ -11,7 +11,7 @@
#include "exec_cmd.h"
static const char index_pack_usage[] =
-"git index-pack [-v] [-o <index-file>] [{ --keep | --keep=<msg> }] [--strict] { <pack-file> | --stdin [--fix-thin] [<pack-file>] }";
+"git index-pack [-v] [-o <index-file>] [ --keep | --keep=<msg> ] [--strict] (<pack-file> | --stdin [--fix-thin] [<pack-file>])";
struct object_entry
{
diff --git a/builtin/ls-files.c b/builtin/ls-files.c
index bb4f612..6a307ab 100644
--- a/builtin/ls-files.c
+++ b/builtin/ls-files.c
@@ -424,7 +424,7 @@ int report_path_error(const char *ps_matched, const char **pathspec, int prefix_
}
static const char * const ls_files_usage[] = {
- "git ls-files [options] [<file>]*",
+ "git ls-files [options] [<file>...]",
NULL
};
diff --git a/builtin/ls-tree.c b/builtin/ls-tree.c
index a818756..f73e6bd 100644
--- a/builtin/ls-tree.c
+++ b/builtin/ls-tree.c
@@ -24,7 +24,7 @@ static int chomp_prefix;
static const char *ls_tree_prefix;
static const char * const ls_tree_usage[] = {
- "git ls-tree [<options>] <tree-ish> [path...]",
+ "git ls-tree [<options>] <tree-ish> [<path>...]",
NULL
};
diff --git a/builtin/mailsplit.c b/builtin/mailsplit.c
index 99654d0..2d43278 100644
--- a/builtin/mailsplit.c
+++ b/builtin/mailsplit.c
@@ -10,7 +10,7 @@
#include "strbuf.h"
static const char git_mailsplit_usage[] =
-"git mailsplit [-d<prec>] [-f<n>] [-b] [--keep-cr] -o<directory> [<mbox>|<Maildir>...]";
+"git mailsplit [-d<prec>] [-f<n>] [-b] [--keep-cr] -o<directory> [(<mbox>|<Maildir>)...]";
static int is_from_line(const char *line, int len)
{
diff --git a/builtin/pack-objects.c b/builtin/pack-objects.c
index d5a8db1..f8eba53 100644
--- a/builtin/pack-objects.c
+++ b/builtin/pack-objects.c
@@ -23,15 +23,15 @@
#endif
static const char pack_usage[] =
- "git pack-objects [{ -q | --progress | --all-progress }]\n"
+ "git pack-objects [ -q | --progress | --all-progress ]\n"
" [--all-progress-implied]\n"
- " [--max-pack-size=N] [--local] [--incremental]\n"
- " [--window=N] [--window-memory=N] [--depth=N]\n"
+ " [--max-pack-size=<n>] [--local] [--incremental]\n"
+ " [--window=<n>] [--window-memory=<n>] [--depth=<n>]\n"
" [--no-reuse-delta] [--no-reuse-object] [--delta-base-offset]\n"
- " [--threads=N] [--non-empty] [--revs [--unpacked | --all]*]\n"
+ " [--threads=<n>] [--non-empty] [--revs [--unpacked | --all]]\n"
" [--reflog] [--stdout | base-name] [--include-tag]\n"
" [--keep-unreachable | --unpack-unreachable]\n"
- " [<ref-list | <object-list]";
+ " [< ref-list | < object-list]";
struct object_entry {
struct pack_idx_entry idx;
diff --git a/builtin/remote.c b/builtin/remote.c
index 48e0a6b..e9a6e09 100644
--- a/builtin/remote.c
+++ b/builtin/remote.c
@@ -15,7 +15,7 @@ static const char * const builtin_remote_usage[] = {
"git remote set-head <name> (-a | -d | <branch>)",
"git remote [-v | --verbose] show [-n] <name>",
"git remote prune [-n | --dry-run] <name>",
- "git remote [-v | --verbose] update [-p | --prune] [group | remote]",
+ "git remote [-v | --verbose] update [-p | --prune] [(<group> | <remote>)...]",
"git remote set-branches <name> [--add] <branch>...",
"git remote set-url <name> <newurl> [<oldurl>]",
"git remote set-url --add <name> <newurl>",
diff --git a/builtin/rev-list.c b/builtin/rev-list.c
index efe9360..158ce11 100644
--- a/builtin/rev-list.c
+++ b/builtin/rev-list.c
@@ -11,9 +11,9 @@
static const char rev_list_usage[] =
"git rev-list [OPTION] <commit-id>... [ -- paths... ]\n"
" limiting output:\n"
-" --max-count=nr\n"
-" --max-age=epoch\n"
-" --min-age=epoch\n"
+" --max-count=<n>\n"
+" --max-age=<epoch>\n"
+" --min-age=<epoch>\n"
" --sparse\n"
" --no-merges\n"
" --remove-empty\n"
@@ -33,7 +33,7 @@ static const char rev_list_usage[] =
" --objects | --objects-edge\n"
" --unpacked\n"
" --header | --pretty\n"
-" --abbrev=nr | --no-abbrev\n"
+" --abbrev=<n> | --no-abbrev\n"
" --abbrev-commit\n"
" --left-right\n"
" special purpose:\n"
diff --git a/builtin/show-branch.c b/builtin/show-branch.c
index e8719aa..8663cca 100644
--- a/builtin/show-branch.c
+++ b/builtin/show-branch.c
@@ -6,7 +6,7 @@
#include "parse-options.h"
static const char* show_branch_usage[] = {
- "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>]...",
+ "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>)...]",
"git show-branch (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>]",
NULL
};
diff --git a/builtin/update-index.c b/builtin/update-index.c
index 3ab214d..62d9f3f 100644
--- a/builtin/update-index.c
+++ b/builtin/update-index.c
@@ -398,7 +398,7 @@ static void read_index_info(int line_termination)
}
static const char update_index_usage[] =
-"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>...";
+"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>...]";
static unsigned char head_sha1[20];
static unsigned char merge_head_sha1[20];
diff --git a/daemon.c b/daemon.c
index e22a2b7..9326d3a 100644
--- a/daemon.c
+++ b/daemon.c
@@ -20,15 +20,15 @@ static int reuseaddr;
static const char daemon_usage[] =
"git daemon [--verbose] [--syslog] [--export-all]\n"
-" [--timeout=n] [--init-timeout=n] [--max-connections=n]\n"
-" [--strict-paths] [--base-path=path] [--base-path-relaxed]\n"
-" [--user-path | --user-path=path]\n"
-" [--interpolated-path=path]\n"
-" [--reuseaddr] [--detach] [--pid-file=file]\n"
-" [--[enable|disable|allow-override|forbid-override]=service]\n"
-" [--inetd | [--listen=host_or_ipaddr] [--port=n]\n"
-" [--user=user [--group=group]]\n"
-" [directory...]";
+" [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>]\n"
+" [--strict-paths] [--base-path=<path>] [--base-path-relaxed]\n"
+" [--user-path | --user-path=<path>]\n"
+" [--interpolated-path=<path>]\n"
+" [--reuseaddr] [--detach] [--pid-file=<file>]\n"
+" [--(enable|disable|allow-override|forbid-override)=<service>]\n"
+" [--inetd | [--listen=<host_or_ipaddr>] [--port=<n>]\n"
+" [--user=<user> [--group=<group>]]\n"
+" [<directory>...]";
/* List of acceptable pathname prefixes */
static char **ok_paths;
diff --git a/fast-import.c b/fast-import.c
index 2317b0f..eab68d5 100644
--- a/fast-import.c
+++ b/fast-import.c
@@ -2884,7 +2884,7 @@ static int git_pack_config(const char *k, const char *v, void *cb)
}
static const char fast_import_usage[] =
-"git fast-import [--date-format=f] [--max-pack-size=n] [--big-file-threshold=n] [--depth=n] [--active-branches=n] [--export-marks=marks.file]";
+"git fast-import [--date-format=<f>] [--max-pack-size=<n>] [--big-file-threshold=<n>] [--depth=<n>] [--active-branches=<n>] [--export-marks=<marks.file>]";
static void parse_argv(void)
{
diff --git a/git-am.sh b/git-am.sh
index 9317b38..763fd20 100755
--- a/git-am.sh
+++ b/git-am.sh
@@ -5,7 +5,7 @@
SUBDIRECTORY_OK=Yes
OPTIONS_KEEPDASHDASH=
OPTIONS_SPEC="\
-git am [options] [<mbox>|<Maildir>...]
+git am [options] [(<mbox>|<Maildir>)...]
git am [options] (--resolved | --skip | --abort)
--
i,interactive run interactively
diff --git a/git-relink.perl b/git-relink.perl
index 937c69a..c2a0ef8 100755
--- a/git-relink.perl
+++ b/git-relink.perl
@@ -163,7 +163,7 @@ sub link_two_files($$) {
sub usage() {
- print("Usage: git relink [--safe] <dir> [<dir> ...] <master_dir> \n");
+ print("Usage: git relink [--safe] <dir>... <master_dir> \n");
print("All directories should contain a .git/objects/ subdirectory.\n");
print("Options\n");
print("\t--safe\t" .
diff --git a/git.c b/git.c
index 50a1401..09855d5 100644
--- a/git.c
+++ b/git.c
@@ -10,10 +10,10 @@ const char git_usage_string[] =
" [-p|--paginate|--no-pager] [--no-replace-objects]\n"
" [--bare] [--git-dir=GIT_DIR] [--work-tree=GIT_WORK_TREE]\n"
" [-c name=value] [--help]\n"
- " COMMAND [ARGS]";
+ " <command> [<args>]";
const char git_more_info_string[] =
- "See 'git help COMMAND' for more information on a specific command.";
+ "See 'git help <command>' for more information on a specific command.";
static struct startup_info git_startup_info;
static int use_pager = -1;
diff --git a/upload-pack.c b/upload-pack.c
index 92f9530..f05e422 100644
--- a/upload-pack.c
+++ b/upload-pack.c
@@ -11,7 +11,7 @@
#include "list-objects.h"
#include "run-command.h"
-static const char upload_pack_usage[] = "git upload-pack [--strict] [--timeout=nn] <dir>";
+static const char upload_pack_usage[] = "git upload-pack [--strict] [--timeout=<n>] <dir>";
/* bits #0..7 in revision.h, #8..10 in commit.c */
#define THEY_HAVE (1u << 11)
--
1.7.3.rc2.221.gbf93f.dirty
^ permalink raw reply related [flat|nested] 43+ messages in thread
* Re: [PATCH/RFC] Unify argument and option notation in the docs
2010-10-08 0:52 [PATCH/RFC] Unify argument and option notation in the docs Štěpán Němec
@ 2010-10-08 7:43 ` Jonathan Nieder
2010-10-08 11:13 ` Štěpán Němec
2010-10-08 16:45 ` [PATCH 0/2] pack-objects: use ALLOC_GROW in place of manual growth Jonathan Nieder
0 siblings, 2 replies; 43+ messages in thread
From: Jonathan Nieder @ 2010-10-08 7:43 UTC (permalink / raw)
To: git; +Cc: Junio C Hamano
Štěpán Němec wrote:
> Some examples of what this patch is based on (i.e., the current
> prevalent usage) follow (all coming from existing documentation):
>
> Placeholders are enclosed in angle brackets:
> <file>
> --sort=<key>
> --abbrev[=<n>]
[etc]
All sane.
> [It is conceivable I could submit this as a series of smaller patches,
> but the problems this is solving didn't seem diverse enough to me to
> warrant that.
Since the documentation processor is known to be, um, picky, could you
do that? That way after bisecting a formatting problem, one has a
diff addressing a single issue to look at.
On the other hand, I am happy enough to comment on a single, monolithic
patch on list if you publish the smaller patches making it up in a git
repository somewhere.
> 1. Is `[--refs [--unpacked | --all]]' in `git-pack-object' documentation
> correct? From my reading of builtin/pack-objects.c, `--unpacked' and
> `--all' do the same thing and both imply --refs, so perhaps [--refs |
> --unpacked | --all] would make more sense?
Doesn't the OPTIONS section explain what --revs, --unpacked, and --all
mean?
I suspect
[--revs] [--unpacked] [--all]
would be clearer, but
[--revs [(--unpacked|--all)...]]
seems fine, too.
By the way, shouldn't that code path use ALLOC_GROW? [1]
> (I also noticed that the
> --reflog option is shown in the usage string but undocumented.)
Looks like someone forgot to add it to the man page.
> 2. I left in one special case, namely the GIT_* variables in `git(1)'
> synopsis section as values for the `--exec-path' and other options.
Hmm, --exec-path=GIT_EXEC_PATH currently serves as a reminder of the
name of the corresponding environment variable, but I don't think
that's very important. --exec-path[=<path>] should be fine.
[1]
-- 8< --
Subject: pack-objects: use ALLOC_GROW
Invoke ALLOC_GROW from cache.h instead of recaping its definition
verbatim. When this code was first written, the ALLOC_GROW macro
didn't exist yet; now that the macro does exist, it can make the
source a little shorter and more readable.
No functional change intended.
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
builtin/pack-objects.c | 16 ++++------------
1 files changed, 4 insertions(+), 12 deletions(-)
diff --git a/builtin/pack-objects.c b/builtin/pack-objects.c
index 3756cf3..6ab2878 100644
--- a/builtin/pack-objects.c
+++ b/builtin/pack-objects.c
@@ -896,13 +896,9 @@ static int check_pbase_path(unsigned hash)
if (0 <= pos)
return 1;
pos = -pos - 1;
- if (done_pbase_paths_alloc <= done_pbase_paths_num) {
- done_pbase_paths_alloc = alloc_nr(done_pbase_paths_alloc);
- done_pbase_paths = xrealloc(done_pbase_paths,
- done_pbase_paths_alloc *
- sizeof(unsigned));
- }
- done_pbase_paths_num++;
+ ALLOC_GROW(done_pbase_paths,
+ ++done_pbase_paths_num,
+ done_pbase_paths_alloc);
if (pos < done_pbase_paths_num)
memmove(done_pbase_paths + pos + 1,
done_pbase_paths + pos,
@@ -2248,11 +2244,7 @@ int cmd_pack_objects(int argc, const char **argv, const char *prefix)
!strcmp("--reflog", arg) ||
!strcmp("--all", arg)) {
use_internal_rev_list = 1;
- if (rp_ac >= rp_ac_alloc - 1) {
- rp_ac_alloc = alloc_nr(rp_ac_alloc);
- rp_av = xrealloc(rp_av,
- rp_ac_alloc * sizeof(*rp_av));
- }
+ ALLOC_GROW(rp_av, rp_ac + 2, rp_ac_alloc);
rp_av[rp_ac++] = arg;
continue;
}
--
1.7.2.3
^ permalink raw reply related [flat|nested] 43+ messages in thread
* Re: [PATCH/RFC] Unify argument and option notation in the docs
2010-10-08 7:43 ` Jonathan Nieder
@ 2010-10-08 11:13 ` Štěpán Němec
2010-10-08 17:31 ` [PATCH 0/6] " Štěpán Němec
` (6 more replies)
2010-10-08 16:45 ` [PATCH 0/2] pack-objects: use ALLOC_GROW in place of manual growth Jonathan Nieder
1 sibling, 7 replies; 43+ messages in thread
From: Štěpán Němec @ 2010-10-08 11:13 UTC (permalink / raw)
To: Jonathan Nieder; +Cc: git, Junio C Hamano
Jonathan Nieder <jrnieder@gmail.com> writes:
> Štěpán Němec wrote:
>> [It is conceivable I could submit this as a series of smaller patches,
>> but the problems this is solving didn't seem diverse enough to me to
>> warrant that.
>
> Since the documentation processor is known to be, um, picky, could you
> do that? That way after bisecting a formatting problem, one has a
> diff addressing a single issue to look at.
OK. Another reason I didn't do that is that my patch actually does not
introduce any mark-up not already present in the sources, so it
shouldn't introduce any new breakage AFAICT.
> On the other hand, I am happy enough to comment on a single, monolithic
> patch on list if you publish the smaller patches making it up in a git
> repository somewhere.
>
>> 1. Is `[--refs [--unpacked | --all]]' in `git-pack-object' documentation
>> correct? From my reading of builtin/pack-objects.c, `--unpacked' and
>> `--all' do the same thing and both imply --refs, so perhaps [--refs |
>> --unpacked | --all] would make more sense?
>
> Doesn't the OPTIONS section explain what --revs, --unpacked, and --all
> mean?
It does, but IMO it contradicts the synopsis. Doesn't the fact that
--unpacked and --all _imply_ --rev mean that you don't need to supply
the latter if you already gave one of the former two? That's also what I
understood from looking at pack-objects.c. So neither [--revs
[(--unpacked|--all)...]] nor [--revs [--unpacked|--all]] seem correct to
me.
I also don't see why you would want to supply --unpacked or --all
multiple times, so `...' would be definitely wrong, no?
>> (I also noticed that the
>> --reflog option is shown in the usage string but undocumented.)
>
> Looks like someone forgot to add it to the man page.
OK. I'll leave that to someone who knows what the option is supposed to
do; it's a matter for a separate patch anyway.
>> 2. I left in one special case, namely the GIT_* variables in `git(1)'
>> synopsis section as values for the `--exec-path' and other options.
>
> Hmm, --exec-path=GIT_EXEC_PATH currently serves as a reminder of the
> name of the corresponding environment variable, but I don't think
> that's very important. --exec-path[=<path>] should be fine.
Yes, that's my opinion as well, thanks for confirmation. I'll include it
in the next round.
Štěpán
^ permalink raw reply [flat|nested] 43+ messages in thread
* [PATCH 0/2] pack-objects: use ALLOC_GROW in place of manual growth
2010-10-08 7:43 ` Jonathan Nieder
2010-10-08 11:13 ` Štěpán Němec
@ 2010-10-08 16:45 ` Jonathan Nieder
2010-10-08 16:46 ` [PATCH 1/2] Documentation: No argument of ALLOC_GROW should have side-effects Jonathan Nieder
` (2 more replies)
1 sibling, 3 replies; 43+ messages in thread
From: Jonathan Nieder @ 2010-10-08 16:45 UTC (permalink / raw)
To: git; +Cc: Junio C Hamano
Jonathan Nieder wrote:
> - done_pbase_paths_num++;
> + ALLOC_GROW(done_pbase_paths,
> + ++done_pbase_paths_num,
> + done_pbase_paths_alloc);
Junio noticed that this makes done_pbase_paths_num grow by 3
rather than by 1 as intended. Sorry.
Patch 1 corrects some documentation that could lead one
astray. Patch 2 is a corrected patch that uses ALLOC_GROW
correctly (I hope).
Jonathan Nieder (2):
Documentation: No argument of ALLOC_GROW cannot have side-effects
pack-objects: use ALLOC_GROW
builtin/pack-objects.c | 15 ++++-----------
cache.h | 2 +-
2 files changed, 5 insertions(+), 12 deletions(-)
--
1.7.2.3
^ permalink raw reply [flat|nested] 43+ messages in thread
* [PATCH 1/2] Documentation: No argument of ALLOC_GROW should have side-effects
2010-10-08 16:45 ` [PATCH 0/2] pack-objects: use ALLOC_GROW in place of manual growth Jonathan Nieder
@ 2010-10-08 16:46 ` Jonathan Nieder
2010-10-08 16:47 ` [PATCH 2/2] pack-objects: use ALLOC_GROW Jonathan Nieder
2010-10-08 17:02 ` [PATCH 3/2] Allow side-effects in second argument to ALLOC_GROW Jonathan Nieder
2 siblings, 0 replies; 43+ messages in thread
From: Jonathan Nieder @ 2010-10-08 16:46 UTC (permalink / raw)
To: git; +Cc: Junio C Hamano
The explanatory comment before the definition of ALLOC_GROW carefully
lists arguments that will be used more than once and thus cannot have
side-effects; a lazy reader might conclude that the arguments not
listed are used only once and side effects safe.
Correct it to list all three arguments, avoiding this confusion.
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
cache.h | 2 +-
1 files changed, 1 insertions(+), 1 deletions(-)
diff --git a/cache.h b/cache.h
index 2ef2fa3..23d6d45 100644
--- a/cache.h
+++ b/cache.h
@@ -438,7 +438,7 @@ extern int init_db(const char *template_dir, unsigned int flags);
* at least 'nr' entries; the number of entries currently allocated
* is 'alloc', using the standard growing factor alloc_nr() macro.
*
- * DO NOT USE any expression with side-effect for 'x' or 'alloc'.
+ * DO NOT USE any expression with side-effect for 'x', 'nr', or 'alloc'.
*/
#define ALLOC_GROW(x, nr, alloc) \
do { \
--
1.7.2.3
^ permalink raw reply related [flat|nested] 43+ messages in thread
* [PATCH 2/2] pack-objects: use ALLOC_GROW
2010-10-08 16:45 ` [PATCH 0/2] pack-objects: use ALLOC_GROW in place of manual growth Jonathan Nieder
2010-10-08 16:46 ` [PATCH 1/2] Documentation: No argument of ALLOC_GROW should have side-effects Jonathan Nieder
@ 2010-10-08 16:47 ` Jonathan Nieder
2010-10-08 17:02 ` [PATCH 3/2] Allow side-effects in second argument to ALLOC_GROW Jonathan Nieder
2 siblings, 0 replies; 43+ messages in thread
From: Jonathan Nieder @ 2010-10-08 16:47 UTC (permalink / raw)
To: git; +Cc: Junio C Hamano
Invoke ALLOC_GROW from cache.h instead of recaping its definition
verbatim. When this code was first written, the ALLOC_GROW macro
didn't exist yet; now that the macro does exist, it can make the
source a little shorter and more readable.
No functional change intended.
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
builtin/pack-objects.c | 15 ++++-----------
1 files changed, 4 insertions(+), 11 deletions(-)
diff --git a/builtin/pack-objects.c b/builtin/pack-objects.c
index 3756cf3..60b792d 100644
--- a/builtin/pack-objects.c
+++ b/builtin/pack-objects.c
@@ -896,12 +896,9 @@ static int check_pbase_path(unsigned hash)
if (0 <= pos)
return 1;
pos = -pos - 1;
- if (done_pbase_paths_alloc <= done_pbase_paths_num) {
- done_pbase_paths_alloc = alloc_nr(done_pbase_paths_alloc);
- done_pbase_paths = xrealloc(done_pbase_paths,
- done_pbase_paths_alloc *
- sizeof(unsigned));
- }
+ ALLOC_GROW(done_pbase_paths,
+ done_pbase_paths_num + 1,
+ done_pbase_paths_alloc);
done_pbase_paths_num++;
if (pos < done_pbase_paths_num)
memmove(done_pbase_paths + pos + 1,
@@ -2248,11 +2245,7 @@ int cmd_pack_objects(int argc, const char **argv, const char *prefix)
!strcmp("--reflog", arg) ||
!strcmp("--all", arg)) {
use_internal_rev_list = 1;
- if (rp_ac >= rp_ac_alloc - 1) {
- rp_ac_alloc = alloc_nr(rp_ac_alloc);
- rp_av = xrealloc(rp_av,
- rp_ac_alloc * sizeof(*rp_av));
- }
+ ALLOC_GROW(rp_av, rp_ac + 2, rp_ac_alloc);
rp_av[rp_ac++] = arg;
continue;
}
--
1.7.2.3
^ permalink raw reply related [flat|nested] 43+ messages in thread
* [PATCH 3/2] Allow side-effects in second argument to ALLOC_GROW
2010-10-08 16:45 ` [PATCH 0/2] pack-objects: use ALLOC_GROW in place of manual growth Jonathan Nieder
2010-10-08 16:46 ` [PATCH 1/2] Documentation: No argument of ALLOC_GROW should have side-effects Jonathan Nieder
2010-10-08 16:47 ` [PATCH 2/2] pack-objects: use ALLOC_GROW Jonathan Nieder
@ 2010-10-08 17:02 ` Jonathan Nieder
2 siblings, 0 replies; 43+ messages in thread
From: Jonathan Nieder @ 2010-10-08 17:02 UTC (permalink / raw)
To: git; +Cc: Junio C Hamano
One might be tempted to try
ALLOC_GROW(ary, ++nr, alloc);
to increase the size of an array by one, and if one tries, the
compiler will happily accept it. Unfortunately ALLOC_GROW evaluates
its argument at least twice, so the results are generally not what the
caller wanted.
Luckily, it is simple enough to do what the caller meant by storing
the value of the second argument in a temporary.
The first and third arguments still need to be side-effect-free. The
name of the temporary is nr_ to avoid conflicting with variables the
caller might use in the expansion of ary, nr, or alloc.
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
cache.h | 9 +++++----
1 files changed, 5 insertions(+), 4 deletions(-)
diff --git a/cache.h b/cache.h
index 23d6d45..5c9e338 100644
--- a/cache.h
+++ b/cache.h
@@ -438,13 +438,14 @@ extern int init_db(const char *template_dir, unsigned int flags);
* at least 'nr' entries; the number of entries currently allocated
* is 'alloc', using the standard growing factor alloc_nr() macro.
*
- * DO NOT USE any expression with side-effect for 'x', 'nr', or 'alloc'.
+ * DO NOT USE any expression with side-effect for 'x' or 'alloc'.
*/
#define ALLOC_GROW(x, nr, alloc) \
do { \
- if ((nr) > alloc) { \
- if (alloc_nr(alloc) < (nr)) \
- alloc = (nr); \
+ const size_t nr_ = (nr); \
+ if (nr_ > (alloc)) { \
+ if (alloc_nr(alloc) < nr_) \
+ alloc = nr_; \
else \
alloc = alloc_nr(alloc); \
x = xrealloc((x), alloc * sizeof(*(x))); \
--
1.7.2.3
^ permalink raw reply related [flat|nested] 43+ messages in thread
* [PATCH 0/6] Unify argument and option notation in the docs
2010-10-08 11:13 ` Štěpán Němec
@ 2010-10-08 17:31 ` Štěpán Němec
2010-10-08 17:44 ` Jonathan Nieder
2010-10-08 19:43 ` Junio C Hamano
2010-10-08 17:31 ` [PATCH 1/6] Use angles for placeholders consistently Štěpán Němec
` (5 subsequent siblings)
6 siblings, 2 replies; 43+ messages in thread
From: Štěpán Němec @ 2010-10-08 17:31 UTC (permalink / raw)
To: git; +Cc: jrnieder, gitster
Other than splitting up the patch, the only change since the RFC version is
having got rid of the GIT_* special cases in `git(1)' synopsis.
[PATCH 1/6] Use angles for placeholders consistently
[PATCH 2/6] Fix odd markup in --diff-filter documentation
[PATCH 3/6] Use parentheses and `...' where appropriate
[PATCH 4/6] Remove stray quotes in --pretty and --format documentation
[PATCH 5/6] Put a space between `<' and argument in pack-objects usage string
[PATCH 6/6] Fix {update,checkout}-index usage strings
^ permalink raw reply [flat|nested] 43+ messages in thread
* [PATCH 1/6] Use angles for placeholders consistently
2010-10-08 11:13 ` Štěpán Němec
2010-10-08 17:31 ` [PATCH 0/6] " Štěpán Němec
@ 2010-10-08 17:31 ` Štěpán Němec
2010-10-08 17:31 ` [PATCH 2/6] Fix odd markup in --diff-filter documentation Štěpán Němec
` (4 subsequent siblings)
6 siblings, 0 replies; 43+ messages in thread
From: Štěpán Němec @ 2010-10-08 17:31 UTC (permalink / raw)
To: git; +Cc: jrnieder, gitster
Signed-off-by: Štěpán Němec <stepnem@gmail.com>
---
Documentation/diff-options.txt | 10 +++---
Documentation/git-apply.txt | 4 +-
Documentation/git-archive.txt | 4 +-
Documentation/git-bundle.txt | 6 ++--
Documentation/git-daemon.txt | 48 ++++++++++++++++++------------------
Documentation/git-fast-export.txt | 2 +-
Documentation/git-index-pack.txt | 4 +-
Documentation/git-ls-tree.txt | 10 +++---
Documentation/git-pack-objects.txt | 14 +++++-----
Documentation/git-remote.txt | 2 +-
Documentation/git-repack.txt | 12 ++++----
Documentation/git-rev-list.txt | 16 ++++++------
Documentation/git-web--browse.txt | 16 ++++++------
Documentation/git.txt | 12 ++++----
Documentation/merge-strategies.txt | 2 +-
Documentation/rev-list-options.txt | 16 ++++++------
archive.c | 4 +-
builtin/bundle.c | 4 +-
builtin/grep.c | 2 +-
builtin/ls-tree.c | 2 +-
builtin/pack-objects.c | 6 ++--
builtin/remote.c | 2 +-
builtin/rev-list.c | 8 +++---
daemon.c | 18 ++++++------
fast-import.c | 2 +-
git.c | 8 +++---
upload-pack.c | 2 +-
27 files changed, 118 insertions(+), 118 deletions(-)
diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index f77a0f8..cbf3c92 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -48,9 +48,9 @@ endif::git-format-patch[]
--patience::
Generate a diff using the "patience diff" algorithm.
---stat[=width[,name-width]]::
+--stat[=<width>[,<name-width>]]::
Generate a diffstat. You can override the default
- output width for 80-column terminal by `--stat=width`.
+ output width for 80-column terminal by `--stat=<width>`.
The width of the filename part can be controlled by
giving another width to it separated by a comma.
@@ -66,14 +66,14 @@ endif::git-format-patch[]
number of modified files, as well as number of added and deleted
lines.
---dirstat[=limit]::
+--dirstat[=<limit>]::
Output the distribution of relative amount of changes (number of lines added or
removed) for each sub-directory. Directories with changes below
a cut-off percent (3% by default) are not shown. The cut-off percent
- can be set with `--dirstat=limit`. Changes in a child directory is not
+ can be set with `--dirstat=<limit>`. Changes in a child directory are not
counted for the parent directory, unless `--cumulative` is used.
---dirstat-by-file[=limit]::
+--dirstat-by-file[=<limit>]::
Same as `--dirstat`, but counts changed files instead of lines.
--summary::
diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
index 4a74b23..08bf6e7 100644
--- a/Documentation/git-apply.txt
+++ b/Documentation/git-apply.txt
@@ -12,10 +12,10 @@ SYNOPSIS
'git apply' [--stat] [--numstat] [--summary] [--check] [--index]
[--apply] [--no-add] [--build-fake-ancestor=<file>] [-R | --reverse]
[--allow-binary-replacement | --binary] [--reject] [-z]
- [-pNUM] [-CNUM] [--inaccurate-eof] [--recount] [--cached]
+ [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached]
[--ignore-space-change | --ignore-whitespace ]
[--whitespace=<nowarn|warn|fix|error|error-all>]
- [--exclude=PATH] [--include=PATH] [--directory=<root>]
+ [--exclude=<path>] [--include=<path>] [--directory=<root>]
[--verbose] [<patch>...]
DESCRIPTION
diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt
index 8d3e666..4163a1b 100644
--- a/Documentation/git-archive.txt
+++ b/Documentation/git-archive.txt
@@ -12,7 +12,7 @@ SYNOPSIS
'git archive' [--format=<fmt>] [--list] [--prefix=<prefix>/] [<extra>]
[-o | --output=<file>] [--worktree-attributes]
[--remote=<repo> [--exec=<git-upload-archive>]] <tree-ish>
- [path...]
+ [<path>...]
DESCRIPTION
-----------
@@ -73,7 +73,7 @@ OPTIONS
<tree-ish>::
The tree or commit to produce an archive for.
-path::
+<path>::
Without an optional path parameter, all files and subdirectories
of the current working directory are included in the archive.
If one or more paths are specified, only these are included.
diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt
index 38e59af..6266a3a 100644
--- a/Documentation/git-bundle.txt
+++ b/Documentation/git-bundle.txt
@@ -11,8 +11,8 @@ SYNOPSIS
[verse]
'git bundle' create <file> <git-rev-list-args>
'git bundle' verify <file>
-'git bundle' list-heads <file> [refname...]
-'git bundle' unbundle <file> [refname...]
+'git bundle' list-heads <file> [<refname>...]
+'git bundle' unbundle <file> [<refname>...]
DESCRIPTION
-----------
@@ -68,7 +68,7 @@ unbundle <file>::
packaged.
-[refname...]::
+[<refname>...]::
A list of references used to limit the references reported as
available. This is principally of use to 'git fetch', which
expects to receive only those references asked for and not
diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt
index 01c9f8e..2f0ddf6 100644
--- a/Documentation/git-daemon.txt
+++ b/Documentation/git-daemon.txt
@@ -9,15 +9,15 @@ SYNOPSIS
--------
[verse]
'git daemon' [--verbose] [--syslog] [--export-all]
- [--timeout=n] [--init-timeout=n] [--max-connections=n]
- [--strict-paths] [--base-path=path] [--base-path-relaxed]
- [--user-path | --user-path=path]
- [--interpolated-path=pathtemplate]
- [--reuseaddr] [--detach] [--pid-file=file]
- [--enable=service] [--disable=service]
- [--allow-override=service] [--forbid-override=service]
- [--inetd | [--listen=host_or_ipaddr] [--port=n] [--user=user [--group=group]]
- [directory...]
+ [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>]
+ [--strict-paths] [--base-path=<path>] [--base-path-relaxed]
+ [--user-path | --user-path=<path>]
+ [--interpolated-path=<pathtemplate>]
+ [--reuseaddr] [--detach] [--pid-file=<file>]
+ [--enable=<service>] [--disable=<service>]
+ [--allow-override=<service>] [--forbid-override=<service>]
+ [--inetd | [--listen=<host_or_ipaddr>] [--port=<n>] [--user=<user> [--group=<group>]]
+ [<directory>...]
DESCRIPTION
-----------
@@ -48,7 +48,7 @@ OPTIONS
'git daemon' will refuse to start when this option is enabled and no
whitelist is specified.
---base-path=path::
+--base-path=<path>::
Remap all the path requests as relative to the given path.
This is sort of "GIT root" - if you run 'git daemon' with
'--base-path=/srv/git' on example.com, then if you later try to pull
@@ -61,7 +61,7 @@ OPTIONS
This is useful for switching to --base-path usage, while still
allowing the old paths.
---interpolated-path=pathtemplate::
+--interpolated-path=<pathtemplate>::
To support virtual hosting, an interpolated path template can be
used to dynamically construct alternate paths. The template
supports %H for the target hostname as supplied by the client but
@@ -80,27 +80,27 @@ OPTIONS
Have the server run as an inetd service. Implies --syslog.
Incompatible with --port, --listen, --user and --group options.
---listen=host_or_ipaddr::
+--listen=<host_or_ipaddr>::
Listen on a specific IP address or hostname. IP addresses can
be either an IPv4 address or an IPv6 address if supported. If IPv6
is not supported, then --listen=hostname is also not supported and
--listen must be given an IPv4 address.
Incompatible with '--inetd' option.
---port=n::
+--port=<n>::
Listen on an alternative port. Incompatible with '--inetd' option.
---init-timeout=n::
+--init-timeout=<n>::
Timeout between the moment the connection is established and the
client request is received (typically a rather low value, since
that should be basically immediate).
---timeout=n::
+--timeout=<n>::
Timeout for specific client sub-requests. This includes the time
it takes for the server to process the sub-request and the time spent
waiting for the next client's request.
---max-connections=n::
+--max-connections=<n>::
Maximum number of concurrent clients, defaults to 32. Set it to
zero for no limit.
@@ -109,7 +109,7 @@ OPTIONS
--verbose, thus by default only error conditions will be logged.
--user-path::
---user-path=path::
+--user-path=<path>::
Allow {tilde}user notation to be used in requests. When
specified with no parameter, requests to
git://host/{tilde}alice/foo is taken as a request to access
@@ -129,12 +129,12 @@ OPTIONS
--detach::
Detach from the shell. Implies --syslog.
---pid-file=file::
+--pid-file=<file>::
Save the process id in 'file'. Ignored when the daemon
is run under `--inetd`.
---user=user::
---group=group::
+--user=<user>::
+--group=<group>::
Change daemon's uid and gid before entering the service loop.
When only `--user` is given without `--group`, the
primary group ID for the user is used. The values of
@@ -145,16 +145,16 @@ Giving these options is an error when used with `--inetd`; use
the facility of inet daemon to achieve the same before spawning
'git daemon' if needed.
---enable=service::
---disable=service::
+--enable=<service>::
+--disable=<service>::
Enable/disable the service site-wide per default. Note
that a service disabled site-wide can still be enabled
per repository if it is marked overridable and the
repository enables the service with a configuration
item.
---allow-override=service::
---forbid-override=service::
+--allow-override=<service>::
+--forbid-override=<service>::
Allow/forbid overriding the site-wide default with per
repository configuration. By default, all the services
are overridable.
diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt
index fcad113..e05b686 100644
--- a/Documentation/git-fast-export.txt
+++ b/Documentation/git-fast-export.txt
@@ -96,7 +96,7 @@ marks the same across runs.
in the commit (as opposed to just listing the files which are
different from the commit's first parent).
-[git-rev-list-args...]::
+[<git-rev-list-args>...]::
A list of arguments, acceptable to 'git rev-parse' and
'git rev-list', that specifies the specific objects and references
to export. For example, `master{tilde}10..master` causes the
diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt
index f3ccc72..c2bb810 100644
--- a/Documentation/git-index-pack.txt
+++ b/Documentation/git-index-pack.txt
@@ -59,10 +59,10 @@ OPTIONS
the newly constructed pack and index before refs can be
updated to use objects contained in the pack.
---keep='why'::
+--keep=<msg>::
Like --keep create a .keep file before moving the index into
its final destination, but rather than creating an empty file
- place 'why' followed by an LF into the .keep file. The 'why'
+ place '<msg>' followed by an LF into the .keep file. The '<msg>'
message can later be searched for within all .keep files to
locate any which have outlived their usefulness.
diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
index 1f89d36..76ed625 100644
--- a/Documentation/git-ls-tree.txt
+++ b/Documentation/git-ls-tree.txt
@@ -10,8 +10,8 @@ SYNOPSIS
--------
[verse]
'git ls-tree' [-d] [-r] [-t] [-l] [-z]
- [--name-only] [--name-status] [--full-name] [--full-tree] [--abbrev=[<n>]]
- <tree-ish> [paths...]
+ [--name-only] [--name-status] [--full-name] [--full-tree] [--abbrev[=<n>]]
+ <tree-ish> [<path>...]
DESCRIPTION
-----------
@@ -19,11 +19,11 @@ Lists the contents of a given tree object, like what "/bin/ls -a" does
in the current working directory. Note that:
- the behaviour is slightly different from that of "/bin/ls" in that the
- 'paths' denote just a list of patterns to match, e.g. so specifying
+ '<path>' denotes just a list of patterns to match, e.g. so specifying
directory name (without '-r') will behave differently, and order of the
arguments does not matter.
- - the behaviour is similar to that of "/bin/ls" in that the 'paths' is
+ - the behaviour is similar to that of "/bin/ls" in that the '<path>' is
taken as relative to the current working directory. E.g. when you are
in a directory 'sub' that has a directory 'dir', you can run 'git
ls-tree -r HEAD dir' to list the contents of the tree (that is
@@ -72,7 +72,7 @@ OPTIONS
Do not limit the listing to the current working directory.
Implies --full-name.
-paths::
+[<path>...]::
When paths are given, show them (note that this isn't really raw
pathnames, but rather a list of patterns to match). Otherwise
implicitly uses the root level of the tree as the sole path argument.
diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
index 8ed09c0..a1dd3e9 100644
--- a/Documentation/git-pack-objects.txt
+++ b/Documentation/git-pack-objects.txt
@@ -11,7 +11,7 @@ SYNOPSIS
[verse]
'git pack-objects' [-q | --progress | --all-progress] [--all-progress-implied]
[--no-reuse-delta] [--delta-base-offset] [--non-empty]
- [--local] [--incremental] [--window=N] [--depth=N]
+ [--local] [--incremental] [--window=<n>] [--depth=<n>]
[--revs [--unpacked | --all]*] [--stdout | base-name]
[--keep-true-parents] < object-list
@@ -82,8 +82,8 @@ base-name::
reference was included in the resulting packfile. This
can be useful to send new tags to native git clients.
---window=[N]::
---depth=[N]::
+--window=<n>::
+--depth=<n>::
These two options affect how the objects contained in
the pack are stored using delta compression. The
objects are first internally sorted by type, size and
@@ -95,10 +95,10 @@ base-name::
times to get to the necessary object.
The default value for --window is 10 and --depth is 50.
---window-memory=[N]::
+--window-memory=<n>::
This option provides an additional limit on top of `--window`;
the window size will dynamically scale down so as to not take
- up more than N bytes in memory. This is useful in
+ up more than '<n>' bytes in memory. This is useful in
repositories with a mix of large and small objects to not run
out of memory with a large window, but still be able to take
advantage of the large window for the smaller objects. The
@@ -106,7 +106,7 @@ base-name::
`--window-memory=0` makes memory usage unlimited, which is the
default.
---max-pack-size=[N]::
+--max-pack-size=<n>::
Maximum size of each output pack file. The size can be suffixed with
"k", "m", or "g". The minimum size allowed is limited to 1 MiB.
If specified, multiple packfiles may be created.
@@ -171,7 +171,7 @@ base-name::
wholesale enforcement of a different compression level on the
packed data is desired.
---compression=[N]::
+--compression=<n>::
Specifies compression level for newly-compressed data in the
generated pack. If not specified, pack compression level is
determined first by pack.compression, then by core.compression,
diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt
index aa021b0..b317086 100644
--- a/Documentation/git-remote.txt
+++ b/Documentation/git-remote.txt
@@ -20,7 +20,7 @@ SYNOPSIS
'git remote set-url --delete' [--push] <name> <url>
'git remote' [-v | --verbose] 'show' [-n] <name>
'git remote prune' [-n | --dry-run] <name>
-'git remote' [-v | --verbose] 'update' [-p | --prune] [group | remote]...
+'git remote' [-v | --verbose] 'update' [-p | --prune] [<group> | <remote>]...
DESCRIPTION
-----------
diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt
index 9566727..27f7865 100644
--- a/Documentation/git-repack.txt
+++ b/Documentation/git-repack.txt
@@ -8,7 +8,7 @@ git-repack - Pack unpacked objects in a repository
SYNOPSIS
--------
-'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [--window=N] [--depth=N]
+'git repack' [-a] [-A] [-d] [-f] [-F] [-l] [-n] [-q] [--window=<n>] [--depth=<n>]
DESCRIPTION
-----------
@@ -80,8 +80,8 @@ other objects in that pack they already have locally.
this repository (or a direct copy of it)
over HTTP or FTP. See linkgit:git-update-server-info[1].
---window=[N]::
---depth=[N]::
+--window=<n>::
+--depth=<n>::
These two options affect how the objects contained in the pack are
stored using delta compression. The objects are first internally
sorted by type, size and optionally names and compared against the
@@ -91,10 +91,10 @@ other objects in that pack they already have locally.
to be applied that many times to get to the necessary object.
The default value for --window is 10 and --depth is 50.
---window-memory=[N]::
+--window-memory=<n>::
This option provides an additional limit on top of `--window`;
the window size will dynamically scale down so as to not take
- up more than N bytes in memory. This is useful in
+ up more than '<n>' bytes in memory. This is useful in
repositories with a mix of large and small objects to not run
out of memory with a large window, but still be able to take
advantage of the large window for the smaller objects. The
@@ -102,7 +102,7 @@ other objects in that pack they already have locally.
`--window-memory=0` makes memory usage unlimited, which is the
default.
---max-pack-size=[N]::
+--max-pack-size=<n>::
Maximum size of each output pack file. The size can be suffixed with
"k", "m", or "g". The minimum size allowed is limited to 1 MiB.
If specified, multiple packfiles may be created.
diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
index 173f3fc..cfb1d21 100644
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.txt
@@ -9,10 +9,10 @@ git-rev-list - Lists commit objects in reverse chronological order
SYNOPSIS
--------
[verse]
-'git rev-list' [ \--max-count=number ]
- [ \--skip=number ]
- [ \--max-age=timestamp ]
- [ \--min-age=timestamp ]
+'git rev-list' [ \--max-count=<number> ]
+ [ \--skip=<number> ]
+ [ \--max-age=<timestamp> ]
+ [ \--min-age=<timestamp> ]
[ \--sparse ]
[ \--merges ]
[ \--no-merges ]
@@ -21,10 +21,10 @@ SYNOPSIS
[ \--full-history ]
[ \--not ]
[ \--all ]
- [ \--branches[=pattern] ]
- [ \--tags[=pattern] ]
- [ \--remotes[=pattern] ]
- [ \--glob=glob-pattern ]
+ [ \--branches[=<pattern>] ]
+ [ \--tags[=<pattern>] ]
+ [ \--remotes[=<pattern>] ]
+ [ \--glob=<glob-pattern> ]
[ \--stdin ]
[ \--quiet ]
[ \--topo-order ]
diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt
index e1586c7..51e8e0a 100644
--- a/Documentation/git-web--browse.txt
+++ b/Documentation/git-web--browse.txt
@@ -32,19 +32,19 @@ Custom commands may also be specified.
OPTIONS
-------
--b BROWSER::
---browser=BROWSER::
- Use the specified BROWSER. It must be in the list of supported
+-b <browser>::
+--browser=<browser>::
+ Use the specified browser. It must be in the list of supported
browsers.
--t BROWSER::
---tool=BROWSER::
+-t <browser>::
+--tool=<browser>::
Same as above.
--c CONF.VAR::
---config=CONF.VAR::
+-c <conf.var>::
+--config=<conf.var>::
CONF.VAR is looked up in the git config files. If it's set,
- then its value specify the browser that should be used.
+ then its value specifies the browser that should be used.
CONFIGURATION VARIABLES
-----------------------
diff --git a/Documentation/git.txt b/Documentation/git.txt
index dd57bdc..8de8617 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -9,11 +9,11 @@ git - the stupid content tracker
SYNOPSIS
--------
[verse]
-'git' [--version] [--exec-path[=GIT_EXEC_PATH]] [--html-path]
+'git' [--version] [--exec-path[=<path>]] [--html-path]
[-p|--paginate|--no-pager] [--no-replace-objects]
- [--bare] [--git-dir=GIT_DIR] [--work-tree=GIT_WORK_TREE]
- [-c name=value]
- [--help] COMMAND [ARGS]
+ [--bare] [--git-dir=<path>] [--work-tree=<path>]
+ [-c <name>=<value>]
+ [--help] <command> [<args>]
DESCRIPTION
-----------
@@ -28,7 +28,7 @@ also want to read linkgit:gitcvs-migration[7]. See
the link:user-manual.html[Git User's Manual] for a more in-depth
introduction.
-The COMMAND is either a name of a Git command (see below) or an alias
+The '<command>' is either a name of a Git command (see below) or an alias
as defined in the configuration file (see linkgit:git-config[1]).
Formatted and hyperlinked version of the latest git
@@ -252,7 +252,7 @@ help ...`.
The <name> is expected in the same format as listed by
'git config' (subkeys separated by dots).
---exec-path::
+--exec-path[=<path>]::
Path to wherever your core git programs are installed.
This can also be controlled by setting the GIT_EXEC_PATH
environment variable. If no path is given, 'git' will print
diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt
index 049313d..8676e26 100644
--- a/Documentation/merge-strategies.txt
+++ b/Documentation/merge-strategies.txt
@@ -52,7 +52,7 @@ no-renormalize;;
Disables the `renormalize` option. This overrides the
`merge.renormalize` configuration variable.
-subtree[=path];;
+subtree[=<path>];;
This option is a more advanced form of 'subtree' strategy, where
the strategy makes a guess on how two trees must be shifted to
match with each other when merging. Instead, the specified path
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index ebc0108..1b13c1f 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -246,29 +246,29 @@ endif::git-rev-list[]
Pretend as if all the refs in `refs/` are listed on the
command line as '<commit>'.
---branches[=pattern]::
+--branches[=<pattern>]::
Pretend as if all the refs in `refs/heads` are listed
- on the command line as '<commit>'. If `pattern` is given, limit
+ on the command line as '<commit>'. If '<pattern>' is given, limit
branches to ones matching given shell glob. If pattern lacks '?',
'*', or '[', '/*' at the end is implied.
---tags[=pattern]::
+--tags[=<pattern>]::
Pretend as if all the refs in `refs/tags` are listed
- on the command line as '<commit>'. If `pattern` is given, limit
+ on the command line as '<commit>'. If '<pattern>' is given, limit
tags to ones matching given shell glob. If pattern lacks '?', '*',
or '[', '/*' at the end is implied.
---remotes[=pattern]::
+--remotes[=<pattern>]::
Pretend as if all the refs in `refs/remotes` are listed
- on the command line as '<commit>'. If `pattern`is given, limit
+ on the command line as '<commit>'. If '<pattern>' is given, limit
remote tracking branches to ones matching given shell glob.
If pattern lacks '?', '*', or '[', '/*' at the end is implied.
---glob=glob-pattern::
- Pretend as if all the refs matching shell glob `glob-pattern`
+--glob=<glob-pattern>::
+ Pretend as if all the refs matching shell glob '<glob-pattern>'
are listed on the command line as '<commit>'. Leading 'refs/',
is automatically prepended if missing. If pattern lacks '?', '*',
or '[', '/*' at the end is implied.
diff --git a/archive.c b/archive.c
index edd6853..f59afda 100644
--- a/archive.c
+++ b/archive.c
@@ -7,9 +7,9 @@
#include "unpack-trees.h"
static char const * const archive_usage[] = {
- "git archive [options] <tree-ish> [path...]",
+ "git archive [options] <tree-ish> [<path>...]",
"git archive --list",
- "git archive --remote <repo> [--exec <cmd>] [options] <tree-ish> [path...]",
+ "git archive --remote <repo> [--exec <cmd>] [options] <tree-ish> [<path>...]",
"git archive --remote <repo> [--exec <cmd>] --list",
NULL
};
diff --git a/builtin/bundle.c b/builtin/bundle.c
index 80649ba..9b87fb9 100644
--- a/builtin/bundle.c
+++ b/builtin/bundle.c
@@ -12,8 +12,8 @@
static const char builtin_bundle_usage[] =
"git bundle create <file> <git-rev-list args>\n"
" or: git bundle verify <file>\n"
- " or: git bundle list-heads <file> [refname...]\n"
- " or: git bundle unbundle <file> [refname...]";
+ " or: git bundle list-heads <file> [<refname>...]\n"
+ " or: git bundle unbundle <file> [<refname>...]";
int cmd_bundle(int argc, const char **argv, const char *prefix)
{
diff --git a/builtin/grep.c b/builtin/grep.c
index da32f3d..3d5f6ac 100644
--- a/builtin/grep.c
+++ b/builtin/grep.c
@@ -24,7 +24,7 @@
#endif
static char const * const grep_usage[] = {
- "git grep [options] [-e] <pattern> [<rev>...] [[--] path...]",
+ "git grep [options] [-e] <pattern> [<rev>...] [[--] <path>...]",
NULL
};
diff --git a/builtin/ls-tree.c b/builtin/ls-tree.c
index a818756..f73e6bd 100644
--- a/builtin/ls-tree.c
+++ b/builtin/ls-tree.c
@@ -24,7 +24,7 @@ static int chomp_prefix;
static const char *ls_tree_prefix;
static const char * const ls_tree_usage[] = {
- "git ls-tree [<options>] <tree-ish> [path...]",
+ "git ls-tree [<options>] <tree-ish> [<path>...]",
NULL
};
diff --git a/builtin/pack-objects.c b/builtin/pack-objects.c
index d5a8db1..1e4c386 100644
--- a/builtin/pack-objects.c
+++ b/builtin/pack-objects.c
@@ -25,10 +25,10 @@
static const char pack_usage[] =
"git pack-objects [{ -q | --progress | --all-progress }]\n"
" [--all-progress-implied]\n"
- " [--max-pack-size=N] [--local] [--incremental]\n"
- " [--window=N] [--window-memory=N] [--depth=N]\n"
+ " [--max-pack-size=<n>] [--local] [--incremental]\n"
+ " [--window=<n>] [--window-memory=<n>] [--depth=<n>]\n"
" [--no-reuse-delta] [--no-reuse-object] [--delta-base-offset]\n"
- " [--threads=N] [--non-empty] [--revs [--unpacked | --all]*]\n"
+ " [--threads=<n>] [--non-empty] [--revs [--unpacked | --all]]\n"
" [--reflog] [--stdout | base-name] [--include-tag]\n"
" [--keep-unreachable | --unpack-unreachable]\n"
" [<ref-list | <object-list]";
diff --git a/builtin/remote.c b/builtin/remote.c
index 48e0a6b..c0198fc 100644
--- a/builtin/remote.c
+++ b/builtin/remote.c
@@ -15,7 +15,7 @@ static const char * const builtin_remote_usage[] = {
"git remote set-head <name> (-a | -d | <branch>)",
"git remote [-v | --verbose] show [-n] <name>",
"git remote prune [-n | --dry-run] <name>",
- "git remote [-v | --verbose] update [-p | --prune] [group | remote]",
+ "git remote [-v | --verbose] update [-p | --prune] [<group> | <remote>]",
"git remote set-branches <name> [--add] <branch>...",
"git remote set-url <name> <newurl> [<oldurl>]",
"git remote set-url --add <name> <newurl>",
diff --git a/builtin/rev-list.c b/builtin/rev-list.c
index efe9360..158ce11 100644
--- a/builtin/rev-list.c
+++ b/builtin/rev-list.c
@@ -11,9 +11,9 @@
static const char rev_list_usage[] =
"git rev-list [OPTION] <commit-id>... [ -- paths... ]\n"
" limiting output:\n"
-" --max-count=nr\n"
-" --max-age=epoch\n"
-" --min-age=epoch\n"
+" --max-count=<n>\n"
+" --max-age=<epoch>\n"
+" --min-age=<epoch>\n"
" --sparse\n"
" --no-merges\n"
" --remove-empty\n"
@@ -33,7 +33,7 @@ static const char rev_list_usage[] =
" --objects | --objects-edge\n"
" --unpacked\n"
" --header | --pretty\n"
-" --abbrev=nr | --no-abbrev\n"
+" --abbrev=<n> | --no-abbrev\n"
" --abbrev-commit\n"
" --left-right\n"
" special purpose:\n"
diff --git a/daemon.c b/daemon.c
index e22a2b7..9326d3a 100644
--- a/daemon.c
+++ b/daemon.c
@@ -20,15 +20,15 @@ static int reuseaddr;
static const char daemon_usage[] =
"git daemon [--verbose] [--syslog] [--export-all]\n"
-" [--timeout=n] [--init-timeout=n] [--max-connections=n]\n"
-" [--strict-paths] [--base-path=path] [--base-path-relaxed]\n"
-" [--user-path | --user-path=path]\n"
-" [--interpolated-path=path]\n"
-" [--reuseaddr] [--detach] [--pid-file=file]\n"
-" [--[enable|disable|allow-override|forbid-override]=service]\n"
-" [--inetd | [--listen=host_or_ipaddr] [--port=n]\n"
-" [--user=user [--group=group]]\n"
-" [directory...]";
+" [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>]\n"
+" [--strict-paths] [--base-path=<path>] [--base-path-relaxed]\n"
+" [--user-path | --user-path=<path>]\n"
+" [--interpolated-path=<path>]\n"
+" [--reuseaddr] [--detach] [--pid-file=<file>]\n"
+" [--(enable|disable|allow-override|forbid-override)=<service>]\n"
+" [--inetd | [--listen=<host_or_ipaddr>] [--port=<n>]\n"
+" [--user=<user> [--group=<group>]]\n"
+" [<directory>...]";
/* List of acceptable pathname prefixes */
static char **ok_paths;
diff --git a/fast-import.c b/fast-import.c
index 2317b0f..eab68d5 100644
--- a/fast-import.c
+++ b/fast-import.c
@@ -2884,7 +2884,7 @@ static int git_pack_config(const char *k, const char *v, void *cb)
}
static const char fast_import_usage[] =
-"git fast-import [--date-format=f] [--max-pack-size=n] [--big-file-threshold=n] [--depth=n] [--active-branches=n] [--export-marks=marks.file]";
+"git fast-import [--date-format=<f>] [--max-pack-size=<n>] [--big-file-threshold=<n>] [--depth=<n>] [--active-branches=<n>] [--export-marks=<marks.file>]";
static void parse_argv(void)
{
diff --git a/git.c b/git.c
index 50a1401..0409ac9 100644
--- a/git.c
+++ b/git.c
@@ -6,14 +6,14 @@
#include "run-command.h"
const char git_usage_string[] =
- "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"
+ " [--bare] [--git-dir=<path>] [--work-tree=<path>]\n"
" [-c name=value] [--help]\n"
- " COMMAND [ARGS]";
+ " <command> [<args>]";
const char git_more_info_string[] =
- "See 'git help COMMAND' for more information on a specific command.";
+ "See 'git help <command>' for more information on a specific command.";
static struct startup_info git_startup_info;
static int use_pager = -1;
diff --git a/upload-pack.c b/upload-pack.c
index 92f9530..f05e422 100644
--- a/upload-pack.c
+++ b/upload-pack.c
@@ -11,7 +11,7 @@
#include "list-objects.h"
#include "run-command.h"
-static const char upload_pack_usage[] = "git upload-pack [--strict] [--timeout=nn] <dir>";
+static const char upload_pack_usage[] = "git upload-pack [--strict] [--timeout=<n>] <dir>";
/* bits #0..7 in revision.h, #8..10 in commit.c */
#define THEY_HAVE (1u << 11)
--
1.7.3.rc2.221.gbf93f.dirty
^ permalink raw reply related [flat|nested] 43+ messages in thread
* [PATCH 2/6] Fix odd markup in --diff-filter documentation
2010-10-08 11:13 ` Štěpán Němec
2010-10-08 17:31 ` [PATCH 0/6] " Štěpán Němec
2010-10-08 17:31 ` [PATCH 1/6] Use angles for placeholders consistently Štěpán Němec
@ 2010-10-08 17:31 ` Štěpán Němec
2010-10-08 17:39 ` Jonathan Nieder
2010-10-08 17:31 ` [PATCH 3/6] Use parentheses and `...' where appropriate Štěpán Němec
` (3 subsequent siblings)
6 siblings, 1 reply; 43+ messages in thread
From: Štěpán Němec @ 2010-10-08 17:31 UTC (permalink / raw)
To: git; +Cc: jrnieder, gitster
Use a `<spec>' placeholder instead of the regex-like bracket expression
to make it more consistent with other similar places.
Signed-off-by: Štěpán Němec <stepnem@gmail.com>
---
Documentation/diff-options.txt | 4 ++--
1 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index cbf3c92..719f589 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -248,13 +248,13 @@ endif::git-log[]
If `n` is specified, it has the same meaning as for `-M<n>`.
ifndef::git-format-patch[]
---diff-filter=[ACDMRTUXB*]::
+--diff-filter=<spec>::
+ '<spec>' can be any combination of the characters `ACDMRTUXB*`.
Select only files that are Added (`A`), Copied (`C`),
Deleted (`D`), Modified (`M`), Renamed (`R`), have their
type (i.e. regular file, symlink, submodule, ...) changed (`T`),
are Unmerged (`U`), are
Unknown (`X`), or have had their pairing Broken (`B`).
- Any combination of the filter characters may be used.
When `*` (All-or-none) is added to the combination, all
paths are selected if there is any file that matches
other criteria in the comparison; if there is no file
--
1.7.3.rc2.221.gbf93f.dirty
^ permalink raw reply related [flat|nested] 43+ messages in thread
* [PATCH 3/6] Use parentheses and `...' where appropriate
2010-10-08 11:13 ` Štěpán Němec
` (2 preceding siblings ...)
2010-10-08 17:31 ` [PATCH 2/6] Fix odd markup in --diff-filter documentation Štěpán Němec
@ 2010-10-08 17:31 ` Štěpán Němec
2010-10-08 17:31 ` [PATCH 4/6] Remove stray quotes in --pretty and --format documentation Štěpán Němec
` (2 subsequent siblings)
6 siblings, 0 replies; 43+ messages in thread
From: Štěpán Němec @ 2010-10-08 17:31 UTC (permalink / raw)
To: git; +Cc: jrnieder, gitster
Remove some stray usage of other bracket types and asterisks for the
same purpose.
Signed-off-by: Štěpán Němec <stepnem@gmail.com>
---
Documentation/git-am.txt | 4 ++--
Documentation/git-apply.txt | 2 +-
Documentation/git-checkout-index.txt | 2 +-
Documentation/git-commit-tree.txt | 2 +-
Documentation/git-fetch.txt | 2 +-
Documentation/git-filter-branch.txt | 2 +-
Documentation/git-for-each-ref.txt | 2 +-
Documentation/git-init.txt | 2 +-
Documentation/git-ls-files.txt | 2 +-
Documentation/git-mailsplit.txt | 2 +-
Documentation/git-mergetool.txt | 2 +-
Documentation/git-pack-objects.txt | 2 +-
Documentation/git-relink.txt | 2 +-
Documentation/git-remote.txt | 2 +-
Documentation/git-rev-list.txt | 2 +-
Documentation/git-rev-parse.txt | 2 +-
Documentation/git-show-branch.txt | 2 +-
Documentation/git-svn.txt | 2 +-
Documentation/git-update-index.txt | 4 ++--
Documentation/rev-list-options.txt | 2 +-
Documentation/user-manual.txt | 2 +-
builtin/commit-tree.c | 2 +-
builtin/fetch.c | 2 +-
builtin/index-pack.c | 2 +-
builtin/ls-files.c | 2 +-
builtin/mailsplit.c | 2 +-
builtin/pack-objects.c | 2 +-
builtin/remote.c | 2 +-
builtin/show-branch.c | 2 +-
git-am.sh | 2 +-
git-relink.perl | 2 +-
31 files changed, 33 insertions(+), 33 deletions(-)
diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index 9e62f87..51297d0 100644
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt
@@ -14,7 +14,7 @@ SYNOPSIS
[--ignore-date] [--ignore-space-change | --ignore-whitespace]
[--whitespace=<option>] [-C<n>] [-p<n>] [--directory=<dir>]
[--reject] [-q | --quiet] [--scissors | --no-scissors]
- [<mbox> | <Maildir>...]
+ [(<mbox> | <Maildir>)...]
'git am' (--continue | --skip | --abort)
DESCRIPTION
@@ -25,7 +25,7 @@ current branch.
OPTIONS
-------
-<mbox>|<Maildir>...::
+(<mbox>|<Maildir>)...::
The list of mailbox files to read patches from. If you do not
supply this argument, the command reads from the standard input.
If you supply directories, they will be treated as Maildirs.
diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
index 08bf6e7..881652f 100644
--- a/Documentation/git-apply.txt
+++ b/Documentation/git-apply.txt
@@ -14,7 +14,7 @@ SYNOPSIS
[--allow-binary-replacement | --binary] [--reject] [-z]
[-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached]
[--ignore-space-change | --ignore-whitespace ]
- [--whitespace=<nowarn|warn|fix|error|error-all>]
+ [--whitespace=(nowarn|warn|fix|error|error-all)]
[--exclude=<path>] [--include=<path>] [--directory=<root>]
[--verbose] [<patch>...]
diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt
index 62f9ab2..0c0a9c1 100644
--- a/Documentation/git-checkout-index.txt
+++ b/Documentation/git-checkout-index.txt
@@ -13,7 +13,7 @@ SYNOPSIS
[--stage=<number>|all]
[--temp]
[-z] [--stdin]
- [--] [<file>]*
+ [--] [<file>...]
DESCRIPTION
-----------
diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt
index 349366e..5dcf427 100644
--- a/Documentation/git-commit-tree.txt
+++ b/Documentation/git-commit-tree.txt
@@ -8,7 +8,7 @@ git-commit-tree - Create a new commit object
SYNOPSIS
--------
-'git commit-tree' <tree> [-p <parent commit>]* < changelog
+'git commit-tree' <tree> [(-p <parent commit>)...] < changelog
DESCRIPTION
-----------
diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt
index 400fe7f..d159e88 100644
--- a/Documentation/git-fetch.txt
+++ b/Documentation/git-fetch.txt
@@ -12,7 +12,7 @@ SYNOPSIS
'git fetch' [<options>] <group>
-'git fetch' --multiple [<options>] [<repository> | <group>]...
+'git fetch' --multiple [<options>] [(<repository> | <group>)...]
'git fetch' --all [<options>]
diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
index f51860d..796e748 100644
--- a/Documentation/git-filter-branch.txt
+++ b/Documentation/git-filter-branch.txt
@@ -117,7 +117,7 @@ OPTIONS
This is the filter for performing the commit.
If this filter is specified, it will be called instead of the
'git commit-tree' command, with arguments of the form
- "<TREE_ID> [-p <PARENT_COMMIT_ID>]..." and the log message on
+ "<TREE_ID> [(-p <PARENT_COMMIT_ID>)...]" and the log message on
stdin. The commit id is expected on stdout.
+
As a special extension, the commit filter may emit multiple
diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index d66fd9d..fac1cf5 100644
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -9,7 +9,7 @@ SYNOPSIS
--------
[verse]
'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl]
- [--sort=<key>]* [--format=<format>] [<pattern>...]
+ [(--sort=<key>)...] [--format=<format>] [<pattern>...]
DESCRIPTION
-----------
diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index 246b07e..00d4a12 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -31,7 +31,7 @@ current working directory.
Specify the directory from which templates will be used. (See the "TEMPLATE
DIRECTORY" section below.)
---shared[={false|true|umask|group|all|world|everybody|0xxx}]::
+--shared[=(false|true|umask|group|all|world|everybody|0xxx)]::
Specify that the git repository is to be shared amongst several users. This
allows users belonging to the same group to push into that
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 347f447..86abd13 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -17,7 +17,7 @@ SYNOPSIS
[--exclude-per-directory=<file>]
[--exclude-standard]
[--error-unmatch] [--with-tree=<tree-ish>]
- [--full-name] [--abbrev] [--] [<file>]*
+ [--full-name] [--abbrev] [--] [<file>...]
DESCRIPTION
-----------
diff --git a/Documentation/git-mailsplit.txt b/Documentation/git-mailsplit.txt
index a634485..71912a1 100644
--- a/Documentation/git-mailsplit.txt
+++ b/Documentation/git-mailsplit.txt
@@ -7,7 +7,7 @@ git-mailsplit - Simple UNIX mbox splitter program
SYNOPSIS
--------
-'git mailsplit' [-b] [-f<nn>] [-d<prec>] [--keep-cr] -o<directory> [--] [<mbox>|<Maildir>...]
+'git mailsplit' [-b] [-f<nn>] [-d<prec>] [--keep-cr] -o<directory> [--] [(<mbox>|<Maildir>)...]
DESCRIPTION
-----------
diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt
index e4ed016..1f75a84 100644
--- a/Documentation/git-mergetool.txt
+++ b/Documentation/git-mergetool.txt
@@ -7,7 +7,7 @@ git-mergetool - Run merge conflict resolution tools to resolve merge conflicts
SYNOPSIS
--------
-'git mergetool' [--tool=<tool>] [-y|--no-prompt|--prompt] [<file>]...
+'git mergetool' [--tool=<tool>] [-y|--no-prompt|--prompt] [<file>...]
DESCRIPTION
-----------
diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
index a1dd3e9..65eff66 100644
--- a/Documentation/git-pack-objects.txt
+++ b/Documentation/git-pack-objects.txt
@@ -12,7 +12,7 @@ SYNOPSIS
'git pack-objects' [-q | --progress | --all-progress] [--all-progress-implied]
[--no-reuse-delta] [--delta-base-offset] [--non-empty]
[--local] [--incremental] [--window=<n>] [--depth=<n>]
- [--revs [--unpacked | --all]*] [--stdout | base-name]
+ [--revs [--unpacked | --all]] [--stdout | base-name]
[--keep-true-parents] < object-list
diff --git a/Documentation/git-relink.txt b/Documentation/git-relink.txt
index 8a5842b..8fc809f 100644
--- a/Documentation/git-relink.txt
+++ b/Documentation/git-relink.txt
@@ -7,7 +7,7 @@ git-relink - Hardlink common objects in local repositories
SYNOPSIS
--------
-'git relink' [--safe] <dir> [<dir>]* <master_dir>
+'git relink' [--safe] <dir>... <master_dir>
DESCRIPTION
-----------
diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt
index b317086..0d28feb 100644
--- a/Documentation/git-remote.txt
+++ b/Documentation/git-remote.txt
@@ -20,7 +20,7 @@ SYNOPSIS
'git remote set-url --delete' [--push] <name> <url>
'git remote' [-v | --verbose] 'show' [-n] <name>
'git remote prune' [-n | --dry-run] <name>
-'git remote' [-v | --verbose] 'update' [-p | --prune] [<group> | <remote>]...
+'git remote' [-v | --verbose] 'update' [-p | --prune] [(<group> | <remote>)...]
DESCRIPTION
-----------
diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
index cfb1d21..8e1e329 100644
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.txt
@@ -37,7 +37,7 @@ SYNOPSIS
[ \--regexp-ignore-case | -i ]
[ \--extended-regexp | -E ]
[ \--fixed-strings | -F ]
- [ \--date={local|relative|default|iso|rfc|short} ]
+ [ \--date=(local|relative|default|iso|rfc|short) ]
[ [\--objects | \--objects-edge] [ \--unpacked ] ]
[ \--pretty | \--header ]
[ \--bisect ]
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 341ca90..4a27643 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -95,7 +95,7 @@ OPTIONS
unfortunately named tag "master"), and show them as full
refnames (e.g. "refs/heads/master").
---abbrev-ref[={strict|loose}]::
+--abbrev-ref[=(strict|loose)]::
A non-ambiguous short name of the objects name.
The option core.warnAmbiguousRefs is used to select the strict
abbreviation mode.
diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt
index 6453263..bd9f886 100644
--- a/Documentation/git-show-branch.txt
+++ b/Documentation/git-show-branch.txt
@@ -12,7 +12,7 @@ SYNOPSIS
[--current] [--color[=<when>] | --no-color] [--sparse]
[--more=<n> | --list | --independent | --merge-base]
[--no-name | --sha1-name] [--topics]
- [<rev> | <glob>]...
+ [(<rev> | <glob>)...]
'git show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>]
diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index be8a51f..139d314 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -438,7 +438,7 @@ git rebase --onto remotes/git-svn A^ master
OPTIONS
-------
---shared[={false|true|umask|group|all|world|everybody}]::
+--shared[=(false|true|umask|group|all|world|everybody)]::
--template=<template_directory>::
Only used with the 'init' command.
These are passed directly to 'git init'.
diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index 74d1d49..a5782a6 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -12,7 +12,7 @@ SYNOPSIS
'git update-index'
[--add] [--remove | --force-remove] [--replace]
[--refresh] [-q] [--unmerged] [--ignore-missing]
- [--cacheinfo <mode> <object> <file>]*
+ [(--cacheinfo <mode> <object> <file>)...]
[--chmod=(+|-)x]
[--assume-unchanged | --no-assume-unchanged]
[--skip-worktree | --no-skip-worktree]
@@ -21,7 +21,7 @@ SYNOPSIS
[--info-only] [--index-info]
[-z] [--stdin]
[--verbose]
- [--] [<file>]*
+ [--] [<file>...]
DESCRIPTION
-----------
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 1b13c1f..7a42567 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -13,7 +13,7 @@ include::pretty-options.txt[]
Synonym for `--date=relative`.
---date={relative,local,default,iso,rfc,short,raw}::
+--date=(relative|local|default|iso|rfc|short|raw)::
Only takes effect for dates shown in human-readable format, such
as when using "--pretty". `log.date` config variable sets a default
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index ce45bfc..cb3b98a 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -3850,7 +3850,7 @@ You create a commit object by giving it the tree that describes the
state at the time of the commit, and a list of parents:
-------------------------------------------------
-$ git commit-tree <tree> -p <parent> [-p <parent2> ..]
+$ git commit-tree <tree> -p <parent> [(-p <parent2>)...]
-------------------------------------------------
and then giving the reason for the commit on stdin (either through
diff --git a/builtin/commit-tree.c b/builtin/commit-tree.c
index 87f0591..e065739 100644
--- a/builtin/commit-tree.c
+++ b/builtin/commit-tree.c
@@ -9,7 +9,7 @@
#include "builtin.h"
#include "utf8.h"
-static const char commit_tree_usage[] = "git commit-tree <sha1> [-p <sha1>]* < changelog";
+static const char commit_tree_usage[] = "git commit-tree <sha1> [(-p <sha1>)...] < changelog";
static void new_parent(struct commit *parent, struct commit_list **parents_p)
{
diff --git a/builtin/fetch.c b/builtin/fetch.c
index 6fc5047..d35f000 100644
--- a/builtin/fetch.c
+++ b/builtin/fetch.c
@@ -16,7 +16,7 @@
static const char * const builtin_fetch_usage[] = {
"git fetch [<options>] [<repository> [<refspec>...]]",
"git fetch [<options>] <group>",
- "git fetch --multiple [<options>] [<repository> | <group>]...",
+ "git fetch --multiple [<options>] [(<repository> | <group>)...]",
"git fetch --all [<options>]",
NULL
};
diff --git a/builtin/index-pack.c b/builtin/index-pack.c
index e243d9d..8dc5c0b 100644
--- a/builtin/index-pack.c
+++ b/builtin/index-pack.c
@@ -11,7 +11,7 @@
#include "exec_cmd.h"
static const char index_pack_usage[] =
-"git index-pack [-v] [-o <index-file>] [{ --keep | --keep=<msg> }] [--strict] { <pack-file> | --stdin [--fix-thin] [<pack-file>] }";
+"git index-pack [-v] [-o <index-file>] [ --keep | --keep=<msg> ] [--strict] (<pack-file> | --stdin [--fix-thin] [<pack-file>])";
struct object_entry
{
diff --git a/builtin/ls-files.c b/builtin/ls-files.c
index bb4f612..6a307ab 100644
--- a/builtin/ls-files.c
+++ b/builtin/ls-files.c
@@ -424,7 +424,7 @@ int report_path_error(const char *ps_matched, const char **pathspec, int prefix_
}
static const char * const ls_files_usage[] = {
- "git ls-files [options] [<file>]*",
+ "git ls-files [options] [<file>...]",
NULL
};
diff --git a/builtin/mailsplit.c b/builtin/mailsplit.c
index 99654d0..2d43278 100644
--- a/builtin/mailsplit.c
+++ b/builtin/mailsplit.c
@@ -10,7 +10,7 @@
#include "strbuf.h"
static const char git_mailsplit_usage[] =
-"git mailsplit [-d<prec>] [-f<n>] [-b] [--keep-cr] -o<directory> [<mbox>|<Maildir>...]";
+"git mailsplit [-d<prec>] [-f<n>] [-b] [--keep-cr] -o<directory> [(<mbox>|<Maildir>)...]";
static int is_from_line(const char *line, int len)
{
diff --git a/builtin/pack-objects.c b/builtin/pack-objects.c
index 1e4c386..26f2304 100644
--- a/builtin/pack-objects.c
+++ b/builtin/pack-objects.c
@@ -23,7 +23,7 @@
#endif
static const char pack_usage[] =
- "git pack-objects [{ -q | --progress | --all-progress }]\n"
+ "git pack-objects [ -q | --progress | --all-progress ]\n"
" [--all-progress-implied]\n"
" [--max-pack-size=<n>] [--local] [--incremental]\n"
" [--window=<n>] [--window-memory=<n>] [--depth=<n>]\n"
diff --git a/builtin/remote.c b/builtin/remote.c
index c0198fc..e9a6e09 100644
--- a/builtin/remote.c
+++ b/builtin/remote.c
@@ -15,7 +15,7 @@ static const char * const builtin_remote_usage[] = {
"git remote set-head <name> (-a | -d | <branch>)",
"git remote [-v | --verbose] show [-n] <name>",
"git remote prune [-n | --dry-run] <name>",
- "git remote [-v | --verbose] update [-p | --prune] [<group> | <remote>]",
+ "git remote [-v | --verbose] update [-p | --prune] [(<group> | <remote>)...]",
"git remote set-branches <name> [--add] <branch>...",
"git remote set-url <name> <newurl> [<oldurl>]",
"git remote set-url --add <name> <newurl>",
diff --git a/builtin/show-branch.c b/builtin/show-branch.c
index e8719aa..8663cca 100644
--- a/builtin/show-branch.c
+++ b/builtin/show-branch.c
@@ -6,7 +6,7 @@
#include "parse-options.h"
static const char* show_branch_usage[] = {
- "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>]...",
+ "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>)...]",
"git show-branch (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>]",
NULL
};
diff --git a/git-am.sh b/git-am.sh
index 9317b38..763fd20 100755
--- a/git-am.sh
+++ b/git-am.sh
@@ -5,7 +5,7 @@
SUBDIRECTORY_OK=Yes
OPTIONS_KEEPDASHDASH=
OPTIONS_SPEC="\
-git am [options] [<mbox>|<Maildir>...]
+git am [options] [(<mbox>|<Maildir>)...]
git am [options] (--resolved | --skip | --abort)
--
i,interactive run interactively
diff --git a/git-relink.perl b/git-relink.perl
index 937c69a..c2a0ef8 100755
--- a/git-relink.perl
+++ b/git-relink.perl
@@ -163,7 +163,7 @@ sub link_two_files($$) {
sub usage() {
- print("Usage: git relink [--safe] <dir> [<dir> ...] <master_dir> \n");
+ print("Usage: git relink [--safe] <dir>... <master_dir> \n");
print("All directories should contain a .git/objects/ subdirectory.\n");
print("Options\n");
print("\t--safe\t" .
--
1.7.3.rc2.221.gbf93f.dirty
^ permalink raw reply related [flat|nested] 43+ messages in thread
* [PATCH 4/6] Remove stray quotes in --pretty and --format documentation
2010-10-08 11:13 ` Štěpán Němec
` (3 preceding siblings ...)
2010-10-08 17:31 ` [PATCH 3/6] Use parentheses and `...' where appropriate Štěpán Němec
@ 2010-10-08 17:31 ` Štěpán Němec
2010-10-08 17:31 ` [PATCH 5/6] Put a space between `<' and argument in pack-objects usage string Štěpán Němec
2010-10-08 17:31 ` [PATCH 6/6] Fix {update,checkout}-index usage strings Štěpán Němec
6 siblings, 0 replies; 43+ messages in thread
From: Štěpán Němec @ 2010-10-08 17:31 UTC (permalink / raw)
To: git; +Cc: jrnieder, gitster
Quotes (for emphasis) are used in option explanations, not the
headings.
Signed-off-by: Štěpán Němec <stepnem@gmail.com>
---
Documentation/git-shortlog.txt | 2 +-
Documentation/pretty-options.txt | 4 ++--
2 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt
index bc1ac77..5cc3baf 100644
--- a/Documentation/git-shortlog.txt
+++ b/Documentation/git-shortlog.txt
@@ -44,7 +44,7 @@ OPTIONS
--email::
Show the email address of each author.
---format[='<format>']::
+--format[=<format>]::
Instead of the commit subject, use some other information to
describe each commit. '<format>' can be any string accepted
by the `--format` option of 'git log', such as '{asterisk} [%h] %s'.
diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt
index 9b6f389..50923e2 100644
--- a/Documentation/pretty-options.txt
+++ b/Documentation/pretty-options.txt
@@ -1,5 +1,5 @@
---pretty[='<format>']::
---format='<format>'::
+--pretty[=<format>]::
+--format=<format>::
Pretty-print the contents of the commit logs in a given format,
where '<format>' can be one of 'oneline', 'short', 'medium',
--
1.7.3.rc2.221.gbf93f.dirty
^ permalink raw reply related [flat|nested] 43+ messages in thread
* [PATCH 5/6] Put a space between `<' and argument in pack-objects usage string
2010-10-08 11:13 ` Štěpán Němec
` (4 preceding siblings ...)
2010-10-08 17:31 ` [PATCH 4/6] Remove stray quotes in --pretty and --format documentation Štěpán Němec
@ 2010-10-08 17:31 ` Štěpán Němec
2010-10-08 17:31 ` [PATCH 6/6] Fix {update,checkout}-index usage strings Štěpán Němec
6 siblings, 0 replies; 43+ messages in thread
From: Štěpán Němec @ 2010-10-08 17:31 UTC (permalink / raw)
To: git; +Cc: jrnieder, gitster
This makes it cosistent with other places (including the
git-pack-objects(1) manpage itself) and avoids possible confusion (I,
for one, mistook `<object-list' for a `<object-list>' typo at first when
preparing this series).
Signed-off-by: Štěpán Němec <stepnem@gmail.com>
---
builtin/pack-objects.c | 2 +-
1 files changed, 1 insertions(+), 1 deletions(-)
diff --git a/builtin/pack-objects.c b/builtin/pack-objects.c
index 26f2304..f8eba53 100644
--- a/builtin/pack-objects.c
+++ b/builtin/pack-objects.c
@@ -31,7 +31,7 @@ static const char pack_usage[] =
" [--threads=<n>] [--non-empty] [--revs [--unpacked | --all]]\n"
" [--reflog] [--stdout | base-name] [--include-tag]\n"
" [--keep-unreachable | --unpack-unreachable]\n"
- " [<ref-list | <object-list]";
+ " [< ref-list | < object-list]";
struct object_entry {
struct pack_idx_entry idx;
--
1.7.3.rc2.221.gbf93f.dirty
^ permalink raw reply related [flat|nested] 43+ messages in thread
* [PATCH 6/6] Fix {update,checkout}-index usage strings
2010-10-08 11:13 ` Štěpán Němec
` (5 preceding siblings ...)
2010-10-08 17:31 ` [PATCH 5/6] Put a space between `<' and argument in pack-objects usage string Štěpán Němec
@ 2010-10-08 17:31 ` Štěpán Němec
6 siblings, 0 replies; 43+ messages in thread
From: Štěpán Němec @ 2010-10-08 17:31 UTC (permalink / raw)
To: git; +Cc: jrnieder, gitster
The `<file>' argument is optional in both cases (the man pages are
already correct).
Signed-off-by: Štěpán Němec <stepnem@gmail.com>
---
builtin/checkout-index.c | 2 +-
builtin/update-index.c | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/builtin/checkout-index.c b/builtin/checkout-index.c
index a7a5ee1..65cbee0 100644
--- a/builtin/checkout-index.c
+++ b/builtin/checkout-index.c
@@ -155,7 +155,7 @@ static void checkout_all(const char *prefix, int prefix_length)
}
static const char * const builtin_checkout_index_usage[] = {
- "git checkout-index [options] [--] <file>...",
+ "git checkout-index [options] [--] [<file>...]",
NULL
};
diff --git a/builtin/update-index.c b/builtin/update-index.c
index 3ab214d..62d9f3f 100644
--- a/builtin/update-index.c
+++ b/builtin/update-index.c
@@ -398,7 +398,7 @@ static void read_index_info(int line_termination)
}
static const char update_index_usage[] =
-"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>...";
+"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>...]";
static unsigned char head_sha1[20];
static unsigned char merge_head_sha1[20];
--
1.7.3.rc2.221.gbf93f.dirty
^ permalink raw reply related [flat|nested] 43+ messages in thread
* Re: [PATCH 2/6] Fix odd markup in --diff-filter documentation
2010-10-08 17:31 ` [PATCH 2/6] Fix odd markup in --diff-filter documentation Štěpán Němec
@ 2010-10-08 17:39 ` Jonathan Nieder
2010-10-08 17:57 ` Štěpán Němec
0 siblings, 1 reply; 43+ messages in thread
From: Jonathan Nieder @ 2010-10-08 17:39 UTC (permalink / raw)
To: Štěpán Němec; +Cc: git, gitster
Štěpán Němec wrote:
> --- a/Documentation/diff-options.txt
> +++ b/Documentation/diff-options.txt
> @@ -248,13 +248,13 @@ endif::git-log[]
> If `n` is specified, it has the same meaning as for `-M<n>`.
>
> ifndef::git-format-patch[]
> ---diff-filter=[ACDMRTUXB*]::
> +--diff-filter=<spec>::
Maybe something like
--diff-filter=((A|C|D|M|R|T|U|X|B)...[*])
to keep the overview while following the conventions you've set out?
Strictly speaking, --diff-filter= (with empty argument) is allowed, too,
but I don't know if it's worth fitting that in.
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH 0/6] Unify argument and option notation in the docs
2010-10-08 17:31 ` [PATCH 0/6] " Štěpán Němec
@ 2010-10-08 17:44 ` Jonathan Nieder
2010-10-08 19:43 ` Junio C Hamano
1 sibling, 0 replies; 43+ messages in thread
From: Jonathan Nieder @ 2010-10-08 17:44 UTC (permalink / raw)
To: Štěpán Němec; +Cc: git, gitster
Štěpán Němec wrote:
> [PATCH 1/6] Use angles for placeholders consistently
> [PATCH 2/6] Fix odd markup in --diff-filter documentation
> [PATCH 3/6] Use parentheses and `...' where appropriate
> [PATCH 4/6] Remove stray quotes in --pretty and --format documentation
> [PATCH 5/6] Put a space between `<' and argument in pack-objects usage string
> [PATCH 6/6] Fix {update,checkout}-index usage strings
All these seem like improvements to me. So:
Acked-by: Jonathan Nieder <jrnieder@gmail.com>
Thanks.
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH 2/6] Fix odd markup in --diff-filter documentation
2010-10-08 17:39 ` Jonathan Nieder
@ 2010-10-08 17:57 ` Štěpán Němec
2010-10-08 18:03 ` Jonathan Nieder
0 siblings, 1 reply; 43+ messages in thread
From: Štěpán Němec @ 2010-10-08 17:57 UTC (permalink / raw)
To: Jonathan Nieder; +Cc: git, gitster
Jonathan Nieder <jrnieder@gmail.com> writes:
> Štěpán Němec wrote:
>
>> --- a/Documentation/diff-options.txt
>> +++ b/Documentation/diff-options.txt
>> @@ -248,13 +248,13 @@ endif::git-log[]
>> If `n` is specified, it has the same meaning as for `-M<n>`.
>>
>> ifndef::git-format-patch[]
>> ---diff-filter=[ACDMRTUXB*]::
>> +--diff-filter=<spec>::
>
> Maybe something like
>
> --diff-filter=((A|C|D|M|R|T|U|X|B)...[*])
>
> to keep the overview while following the conventions you've set out?
Looks good to me as well, thanks.
> Strictly speaking, --diff-filter= (with empty argument) is allowed, too,
> but I don't know if it's worth fitting that in.
If it provides some kind of useful behaviour (I don't know and you
didn't clarify that either), then it should be documented I guess?
Štěpán
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH 2/6] Fix odd markup in --diff-filter documentation
2010-10-08 17:57 ` Štěpán Němec
@ 2010-10-08 18:03 ` Jonathan Nieder
2010-10-08 18:40 ` Štěpán Němec
0 siblings, 1 reply; 43+ messages in thread
From: Jonathan Nieder @ 2010-10-08 18:03 UTC (permalink / raw)
To: Štěpán Němec; +Cc: git, gitster
Štěpán Němec wrote:
> Jonathan Nieder <jrnieder@gmail.com> writes:
>> Strictly speaking, --diff-filter= (with empty argument) is allowed, too,
>> but I don't know if it's worth fitting that in.
>
> If it provides some kind of useful behaviour (I don't know and you
> didn't clarify that either), then it should be documented I guess?
Just a special case of the usual behavior: it selects the empty set of
files. Doesn't sound useful to me, but maybe someone writing a
front-end would want to be reassured that --diff-filter will still
work if the user unchecks all the boxes.
Of course, one can also just try it...
If you can find a way to format it nicely (using brackets?), then I
think it should be part of the documented syntax, yes.
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH 2/6] Fix odd markup in --diff-filter documentation
2010-10-08 18:03 ` Jonathan Nieder
@ 2010-10-08 18:40 ` Štěpán Němec
2010-10-08 18:53 ` Jonathan Nieder
0 siblings, 1 reply; 43+ messages in thread
From: Štěpán Němec @ 2010-10-08 18:40 UTC (permalink / raw)
To: Jonathan Nieder; +Cc: git, gitster
Jonathan Nieder <jrnieder@gmail.com> writes:
> Štěpán Němec wrote:
>> Jonathan Nieder <jrnieder@gmail.com> writes:
>
>>> Strictly speaking, --diff-filter= (with empty argument) is allowed, too,
>>> but I don't know if it's worth fitting that in.
>>
>> If it provides some kind of useful behaviour (I don't know and you
>> didn't clarify that either), then it should be documented I guess?
>
> Just a special case of the usual behavior: it selects the empty set of
> files. Doesn't sound useful to me, but maybe someone writing a
> front-end would want to be reassured that --diff-filter will still
> work if the user unchecks all the boxes.
>
> Of course, one can also just try it...
>
> If you can find a way to format it nicely (using brackets?), then I
> think it should be part of the documented syntax, yes.
Well, in that case simply replacing parens with brackets would do, i.e.
--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]
instead of
--diff-filter=((A|C|D|M|R|T|U|X|B)...[*])
That would mean the following instead of the original [2/6]:
--- 8< ---
Subject: Fix odd markup in --diff-filter documentation
Instead of using the regex-like bracket expression, use grouping to make
it more consistent with other similar places. The brackets now have the
same meaning as in other documentation (i.e., the argument is optional).
Signed-off-by: Štěpán Němec <stepnem@gmail.com>
Mentored-by: Jonathan Nieder <jrnieder@gmail.com>
---
Documentation/diff-options.txt | 4 ++--
1 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index cbf3c92..e954af0 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -248,13 +248,13 @@ endif::git-log[]
If `n` is specified, it has the same meaning as for `-M<n>`.
ifndef::git-format-patch[]
---diff-filter=[ACDMRTUXB*]::
+--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]::
Select only files that are Added (`A`), Copied (`C`),
Deleted (`D`), Modified (`M`), Renamed (`R`), have their
type (i.e. regular file, symlink, submodule, ...) changed (`T`),
are Unmerged (`U`), are
Unknown (`X`), or have had their pairing Broken (`B`).
- Any combination of the filter characters may be used.
+ Any combination of the filter characters (including none) can be used.
When `*` (All-or-none) is added to the combination, all
paths are selected if there is any file that matches
other criteria in the comparison; if there is no file
--
^ permalink raw reply related [flat|nested] 43+ messages in thread
* Re: [PATCH 2/6] Fix odd markup in --diff-filter documentation
2010-10-08 18:40 ` Štěpán Němec
@ 2010-10-08 18:53 ` Jonathan Nieder
0 siblings, 0 replies; 43+ messages in thread
From: Jonathan Nieder @ 2010-10-08 18:53 UTC (permalink / raw)
To: Štěpán Němec; +Cc: git, gitster
Štěpán Němec wrote:
> That would mean the following instead of the original [2/6]:
Looks good, thanks.
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH 0/6] Unify argument and option notation in the docs
2010-10-08 17:31 ` [PATCH 0/6] " Štěpán Němec
2010-10-08 17:44 ` Jonathan Nieder
@ 2010-10-08 19:43 ` Junio C Hamano
2010-10-08 20:15 ` Štěpán Němec
1 sibling, 1 reply; 43+ messages in thread
From: Junio C Hamano @ 2010-10-08 19:43 UTC (permalink / raw)
To: Štěpán Němec; +Cc: git, jrnieder
I had to fix up the whitespace damage in the rerolled 2/6 but otherwise
looked good.
Thanks, both. It might make sense to outline the rules applied somewhere in
CodingGuidelines to help people who add to our documents. Something along
the lines of...
- A placeholder is spelled inside angle brackets, e.g. <file>, <object>.
- Choosing one from many is written with possible choices separated with
a vertical bar and the whole thing enclosed in parentheses, e.g.
answer=(yes|no|true|false)
- Repetition of zero or more times of X is spelled as [(X)...], e.g.
[(-p <parent>)...]
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH 0/6] Unify argument and option notation in the docs
2010-10-08 19:43 ` Junio C Hamano
@ 2010-10-08 20:15 ` Štěpán Němec
2010-10-21 22:21 ` Jonathan Nieder
0 siblings, 1 reply; 43+ messages in thread
From: Štěpán Němec @ 2010-10-08 20:15 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git, jrnieder
Junio C Hamano <gitster@pobox.com> writes:
> I had to fix up the whitespace damage in the rerolled 2/6 but otherwise
> looked good.
Yeah, sorry for that. Obviously the tabs got replaced by spaces when I
copy-pasted the hunk and I didn't notice.
> Thanks, both. It might make sense to outline the rules applied somewhere in
> CodingGuidelines to help people who add to our documents. Something along
> the lines of...
>
> - A placeholder is spelled inside angle brackets, e.g. <file>, <object>.
>
> - Choosing one from many is written with possible choices separated with
> a vertical bar and the whole thing enclosed in parentheses, e.g.
> answer=(yes|no|true|false)
>
> - Repetition of zero or more times of X is spelled as [(X)...], e.g.
> [(-p <parent>)...]
:-) I was actually considering just that, so I'm glad you mention it.
I can try to compile an initial version of such a document, based on the
commit message of the original single-patch version
(<http://article.gmane.org/gmane.comp.version-control.git/158467>) and
including some more cases/examples.
Where do you think would be the most appropriate place for it?
Just add a section to CodingGuidelines, or a separate
Documentation/WritingGuidelines or something?
Štěpán
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH 0/6] Unify argument and option notation in the docs
2010-10-08 20:15 ` Štěpán Němec
@ 2010-10-21 22:21 ` Jonathan Nieder
2010-10-24 15:51 ` [PATCH] CodingGuidelines: Add a section on writing documentation Štěpán Němec
0 siblings, 1 reply; 43+ messages in thread
From: Jonathan Nieder @ 2010-10-21 22:21 UTC (permalink / raw)
To: Štěpán Němec; +Cc: Junio C Hamano, git
Štěpán Němec wrote:
> :-) I was actually considering just that, so I'm glad you mention it.
>
> I can try to compile an initial version of such a document, based on the
> commit message of the original single-patch version
> (<http://article.gmane.org/gmane.comp.version-control.git/158467>) and
> including some more cases/examples.
>
> Where do you think would be the most appropriate place for it?
> Just add a section to CodingGuidelines, or a separate
> Documentation/WritingGuidelines or something?
Sorry for the slow response. Documentation/CodingGuidelines makes sense
to me, since it affects the usage strings in code.
^ permalink raw reply [flat|nested] 43+ messages in thread
* [PATCH] CodingGuidelines: Add a section on writing documentation
2010-10-21 22:21 ` Jonathan Nieder
@ 2010-10-24 15:51 ` Štěpán Němec
2010-10-29 2:56 ` Mark Lodato
0 siblings, 1 reply; 43+ messages in thread
From: Štěpán Němec @ 2010-10-24 15:51 UTC (permalink / raw)
To: git; +Cc: Junio C Hamano, Jonathan Nieder
Provide a few examples on argument and option notation in usage strings
and command synopses.
Signed-off-by: Štěpán Němec <stepnem@gmail.com>
---
Jonathan Nieder <jrnieder@gmail.com> writes:
> Štěpán Němec wrote:
[...]
>> I can try to compile an initial version of such a document, based on the
>> commit message of the original single-patch version
>> (<http://article.gmane.org/gmane.comp.version-control.git/158467>) and
>> including some more cases/examples.
>>
>> Where do you think would be the most appropriate place for it?
>> Just add a section to CodingGuidelines, or a separate
>> Documentation/WritingGuidelines or something?
>
> Sorry for the slow response. Documentation/CodingGuidelines makes sense
> to me, since it affects the usage strings in code.
Thanks, here's a patch.
Documentation/CodingGuidelines | 53 ++++++++++++++++++++++++++++++++++++++++
1 files changed, 53 insertions(+), 0 deletions(-)
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 09ffc46..0ac7aac 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -139,3 +139,56 @@ For C programs:
- When we pass <string, length> pair to functions, we should try to
pass them in that order.
+
+Writing Documentation:
+
+ Every user-visible change should be reflected in the documentation.
+ The same general rule as for code applies -- imitate the existing
+ conventions. A few commented examples follow to provide reference
+ when writing or modifying command usage strings and synopsis sections
+ in the manual pages:
+
+ Placeholders are enclosed in angle brackets:
+ <file>
+ --sort=<key>
+ --abbrev[=<n>]
+
+ Possibility of multiple occurences is indicated by three dots:
+ <file>...
+ (One or more of <file>.)
+
+ Optional parts are enclosed in square brackets:
+ [<extra>]
+ (Zero or one <extra>.)
+
+ --exec-path[=<path>]
+ (Option with an optional argument. Note that the "=" is inside the
+ brackets.)
+
+ [<patch>...]
+ (Zero or more of <patch>. Note that the dots are inside, not
+ outside the brackets.)
+
+ Parentheses are used for grouping, often combined with vertical bar
+ to indicate alternatives:
+ [(<rev>|<range>)...]
+ (Any number of either <rev> or <range>. Parens are needed to make
+ it clear that "..." pertains to both <rev> and <range>.)
+
+ [(-p <parent>)...]
+ (Any number of option -p, each with one <parent> argument.)
+
+ git remote set-head <name> (-a | -d | <branch>)
+ (One and only one of "-a", "-d" or "<branch>" _must_ (no square
+ brackets) be provided.)
+
+ Specific number of occurences is indicated as follows:
+ <commit>{0,2}
+ (Up to two <commit>s.)
+
+ And a somewhat more contrived example:
+ --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]
+ Here "=" is outside the brackets, because "--diff-filter=" is a
+ valid usage. "*" has its own pair of brackets, because it can
+ (optionally) be specified only when one or more of the letters is
+ also provided.
--
1.7.3.rc2.221.gbf93f.dirty
^ permalink raw reply related [flat|nested] 43+ messages in thread
* Re: [PATCH] CodingGuidelines: Add a section on writing documentation
2010-10-24 15:51 ` [PATCH] CodingGuidelines: Add a section on writing documentation Štěpán Němec
@ 2010-10-29 2:56 ` Mark Lodato
2010-10-29 11:54 ` Štěpán Němec
0 siblings, 1 reply; 43+ messages in thread
From: Mark Lodato @ 2010-10-29 2:56 UTC (permalink / raw)
To: git, Junio C Hamano, Jonathan Nieder
On Sun, Oct 24, 2010 at 11:51 AM, Štěpán Němec <stepnem@gmail.com> wrote:
> Provide a few examples on argument and option notation in usage strings
> and command synopses.
I think this is a great idea.
> + Specific number of occurences is indicated as follows:
> + <commit>{0,2}
> + (Up to two <commit>s.)
I suggest removing this notation - it is confusing and is only used by
git-diff.txt and git-difftool.txt. We already have notation to serve
this purpose:
[<commit> [<commit>]]
> + Parentheses are used for grouping, often combined with vertical bar
> + to indicate alternatives:
> + [(<rev>|<range>)...]
> + (Any number of either <rev> or <range>. Parens are needed to make
> + it clear that "..." pertains to both <rev> and <range>.)
You could also mention that parentheses are not needed if square
brackets will do:
[-q | --quiet]
Also, should there be a standard for spacing and for whether the short
or the long option comes first?
git-add.txt:
[--patch | -p]
git-commit.txt:
[-a | --interactive]
git-stash.txt:
[-q|--quiet]
Otherwise, I think this patch looks good.
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH] CodingGuidelines: Add a section on writing documentation
2010-10-29 2:56 ` Mark Lodato
@ 2010-10-29 11:54 ` Štěpán Němec
2010-10-29 17:14 ` Sverre Rabbelier
0 siblings, 1 reply; 43+ messages in thread
From: Štěpán Němec @ 2010-10-29 11:54 UTC (permalink / raw)
To: Mark Lodato; +Cc: git, Junio C Hamano, Jonathan Nieder
Mark Lodato <lodatom@gmail.com> writes:
> On Sun, Oct 24, 2010 at 11:51 AM, Štěpán Němec <stepnem@gmail.com> wrote:
>> + Specific number of occurences is indicated as follows:
>> + <commit>{0,2}
>> + (Up to two <commit>s.)
>
> I suggest removing this notation - it is confusing and is only used by
> git-diff.txt and git-difftool.txt. We already have notation to serve
> this purpose:
>
> [<commit> [<commit>]]
Yeah, it's kind of an oddball, although I don't really find it
confusing. I guess it might be useful in cases where you have a bigger
number of "things", say 4 or more, where the brackets could get
unwieldy.
But given that it's only used as {0,2} at the two places right now
(disregarding occurences of "0{40}" in the documentation), I agree it
might be better to get rid of it, although I don't feel strongly about
it. Any other opinions?
>> + Parentheses are used for grouping, often combined with vertical bar
>> + to indicate alternatives:
>> + [(<rev>|<range>)...]
>> + (Any number of either <rev> or <range>. Parens are needed to make
>> + it clear that "..." pertains to both <rev> and <range>.)
>
> You could also mention that parentheses are not needed if square
> brackets will do:
> [-q | --quiet]
Good point, will do.
> Also, should there be a standard for spacing and for whether the short
> or the long option comes first?
>
> git-add.txt:
> [--patch | -p]
> git-commit.txt:
> [-a | --interactive]
> git-stash.txt:
> [-q|--quiet]
I thought about this already when preparing the recent unification
series, and came to the conclusion "no, there shouldn't". :-) As the
examples you give show, the current usage is inconsistent, but given
that it brings no semantic ambiguity, I don't think it is a problem. You
could find more similar cosmetic inconsistencies and I don't think it
makes much sense to mandate any rules for such things. (But again, I
don't feel _too_ strongly about this either, so if more people think
it's worth it, I can prepare a patch that unifies them and mention the
preference in CodingGuidelines.)
> Otherwise, I think this patch looks good.
Thank you for the feedback!
Štěpán
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH] CodingGuidelines: Add a section on writing documentation
2010-10-29 11:54 ` Štěpán Němec
@ 2010-10-29 17:14 ` Sverre Rabbelier
2010-11-01 17:00 ` Štěpán Němec
0 siblings, 1 reply; 43+ messages in thread
From: Sverre Rabbelier @ 2010-10-29 17:14 UTC (permalink / raw)
To: Štěpán Němec
Cc: Mark Lodato, git, Junio C Hamano, Jonathan Nieder
Heya,
On Fri, Oct 29, 2010 at 04:54, Štěpán Němec <stepnem@gmail.com> wrote:
> But given that it's only used as {0,2} at the two places right now
> (disregarding occurences of "0{40}" in the documentation), I agree it
> might be better to get rid of it, although I don't feel strongly about
> it. Any other opinions?
Let's get rid of it for now, we can always resurrect it later if we
have a need for it.
> I thought about this already when preparing the recent unification
> series, and came to the conclusion "no, there shouldn't". :-) As the
> examples you give show, the current usage is inconsistent, but given
> that it brings no semantic ambiguity, I don't think it is a problem. You
> could find more similar cosmetic inconsistencies and I don't think it
> makes much sense to mandate any rules for such things. (But again, I
> don't feel _too_ strongly about this either, so if more people think
> it's worth it, I can prepare a patch that unifies them and mention the
> preference in CodingGuidelines.)
Perhaps we can set a standard to do it, but just leave the existing
cases as is (to prevent unneeded churn)? That way we'll eventually
converge on something.
--
Cheers,
Sverre Rabbelier
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH] CodingGuidelines: Add a section on writing documentation
2010-10-29 17:14 ` Sverre Rabbelier
@ 2010-11-01 17:00 ` Štěpán Němec
2010-11-04 17:12 ` [PATCH v2] " Štěpán Němec
2010-11-04 17:18 ` [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings Štěpán Němec
0 siblings, 2 replies; 43+ messages in thread
From: Štěpán Němec @ 2010-11-01 17:00 UTC (permalink / raw)
To: Sverre Rabbelier; +Cc: Mark Lodato, git, Junio C Hamano, Jonathan Nieder
Sverre Rabbelier <srabbelier@gmail.com> writes:
> Heya,
>
> On Fri, Oct 29, 2010 at 04:54, Štěpán Němec <stepnem@gmail.com> wrote:
>> But given that it's only used as {0,2} at the two places right now
>> (disregarding occurences of "0{40}" in the documentation), I agree it
>> might be better to get rid of it, although I don't feel strongly about
>> it. Any other opinions?
>
> Let's get rid of it for now, we can always resurrect it later if we
> have a need for it.
OK.
>> I thought about this already when preparing the recent unification
>> series, and came to the conclusion "no, there shouldn't". :-) As the
>> examples you give show, the current usage is inconsistent, but given
>> that it brings no semantic ambiguity, I don't think it is a problem. You
>> could find more similar cosmetic inconsistencies and I don't think it
>> makes much sense to mandate any rules for such things. (But again, I
>> don't feel _too_ strongly about this either, so if more people think
>> it's worth it, I can prepare a patch that unifies them and mention the
>> preference in CodingGuidelines.)
>
> Perhaps we can set a standard to do it, but just leave the existing
> cases as is (to prevent unneeded churn)? That way we'll eventually
> converge on something.
Hm... that seems like the worst solution to me -- if we do end up
standardizing this after all, any occurence of non-standard usage would
be a bug that needs fixing (think about it from the POV of a new
contributor who reads CodingGuidelines but sees the actual usage being
different).
I guess it wouldn't be so much of a code churn to unify the spacing, but
I'm still not convinced we should be enforcing this kind of thing.
Štěpán
^ permalink raw reply [flat|nested] 43+ messages in thread
* [PATCH v2] CodingGuidelines: Add a section on writing documentation
2010-11-01 17:00 ` Štěpán Němec
@ 2010-11-04 17:12 ` Štěpán Němec
2010-11-04 17:18 ` [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings Štěpán Němec
1 sibling, 0 replies; 43+ messages in thread
From: Štěpán Němec @ 2010-11-04 17:12 UTC (permalink / raw)
To: git; +Cc: Sverre Rabbelier, Mark Lodato, Junio C Hamano, Jonathan Nieder
Provide a few examples on argument and option notation in usage strings
and command synopses.
Signed-off-by: Štěpán Němec <stepnem@gmail.com>
---
Changes since the last version:
- add a separate subsection on vertical bar without parentheses (suggested
by Mark Lodato)
- do not include the <thing>{M,N} usage for fixed number of occurences
(Mark Lodato and Sverre Rabbelier)
Documentation/CodingGuidelines | 52 ++++++++++++++++++++++++++++++++++++++++
1 files changed, 52 insertions(+), 0 deletions(-)
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 09ffc46..5aa2d34 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -139,3 +139,55 @@ For C programs:
- When we pass <string, length> pair to functions, we should try to
pass them in that order.
+
+Writing Documentation:
+
+ Every user-visible change should be reflected in the documentation.
+ The same general rule as for code applies -- imitate the existing
+ conventions. A few commented examples follow to provide reference
+ when writing or modifying command usage strings and synopsis sections
+ in the manual pages:
+
+ Placeholders are enclosed in angle brackets:
+ <file>
+ --sort=<key>
+ --abbrev[=<n>]
+
+ Possibility of multiple occurences is indicated by three dots:
+ <file>...
+ (One or more of <file>.)
+
+ Optional parts are enclosed in square brackets:
+ [<extra>]
+ (Zero or one <extra>.)
+
+ --exec-path[=<path>]
+ (Option with an optional argument. Note that the "=" is inside the
+ brackets.)
+
+ [<patch>...]
+ (Zero or more of <patch>. Note that the dots are inside, not
+ outside the brackets.)
+
+ Multiple alternatives are indicated with vertical bar:
+ [-q | --quiet]
+ [--utf8 | --no-utf8]
+
+ Parentheses are used for grouping:
+ [(<rev>|<range>)...]
+ (Any number of either <rev> or <range>. Parens are needed to make
+ it clear that "..." pertains to both <rev> and <range>.)
+
+ [(-p <parent>)...]
+ (Any number of option -p, each with one <parent> argument.)
+
+ git remote set-head <name> (-a | -d | <branch>)
+ (One and only one of "-a", "-d" or "<branch>" _must_ (no square
+ brackets) be provided.)
+
+ And a somewhat more contrived example:
+ --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]
+ Here "=" is outside the brackets, because "--diff-filter=" is a
+ valid usage. "*" has its own pair of brackets, because it can
+ (optionally) be specified only when one or more of the letters is
+ also provided.
--
1.7.3.rc2.221.gbf93f.dirty
^ permalink raw reply related [flat|nested] 43+ messages in thread
* [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings
2010-11-01 17:00 ` Štěpán Němec
2010-11-04 17:12 ` [PATCH v2] " Štěpán Němec
@ 2010-11-04 17:18 ` Štěpán Němec
2010-11-04 17:22 ` Sverre Rabbelier
2010-11-04 17:49 ` Jeff King
1 sibling, 2 replies; 43+ messages in thread
From: Štěpán Němec @ 2010-11-04 17:18 UTC (permalink / raw)
To: git; +Cc: Sverre Rabbelier, Mark Lodato, Junio C Hamano, Jonathan Nieder
This was the only occurence of that usage, and square brackets are
sufficient and already well-established for that purpose.
Signed-off-by: Štěpán Němec <stepnem@gmail.com>
---
As per discussion upthread, this notation is not worth keeping; hence
not mentioning it in the v2 of the CodingGuidlines patch and this
removal.
Documentation/git-diff.txt | 2 +-
Documentation/git-difftool.txt | 2 +-
builtin/diff.c | 2 +-
3 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index dd1fb32..61728f6 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -8,7 +8,7 @@ git-diff - Show changes between commits, commit and working tree, etc
SYNOPSIS
--------
-'git diff' [<common diff options>] <commit>{0,2} [--] [<path>...]
+'git diff' [<common diff options>] [<commit> [<commit>]] [--] [<path>...]
DESCRIPTION
-----------
diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt
index 8250bad..a02e3b5 100644
--- a/Documentation/git-difftool.txt
+++ b/Documentation/git-difftool.txt
@@ -7,7 +7,7 @@ git-difftool - Show changes using common diff tools
SYNOPSIS
--------
-'git difftool' [<options>] <commit>{0,2} [--] [<path>...]
+'git difftool' [<options>] [<commit> [<commit>]] [--] [<path>...]
DESCRIPTION
-----------
diff --git a/builtin/diff.c b/builtin/diff.c
index a43d326..945e758 100644
--- a/builtin/diff.c
+++ b/builtin/diff.c
@@ -22,7 +22,7 @@ struct blobinfo {
};
static const char builtin_diff_usage[] =
-"git diff <options> <rev>{0,2} -- <path>*";
+"git diff [<options>] [<commit> [<commit>]] [--] [<path>...]";
static void stuff_change(struct diff_options *opt,
unsigned old_mode, unsigned new_mode,
--
1.7.3.rc2.221.gbf93f.dirty
^ permalink raw reply related [flat|nested] 43+ messages in thread
* Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings
2010-11-04 17:18 ` [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings Štěpán Němec
@ 2010-11-04 17:22 ` Sverre Rabbelier
2010-11-04 17:49 ` Jeff King
1 sibling, 0 replies; 43+ messages in thread
From: Sverre Rabbelier @ 2010-11-04 17:22 UTC (permalink / raw)
To: Štěpán Němec
Cc: git, Mark Lodato, Junio C Hamano, Jonathan Nieder
Heya,
2010/11/4 Štěpán Němec <stepnem@gmail.com>:
> This was the only occurence of that usage, and square brackets are
> sufficient and already well-established for that purpose.
>
> Signed-off-by: Štěpán Němec <stepnem@gmail.com>
Not sure if it's appropriate for Documentation patches, but fwiw:
Acked by: Sverre Rabbelier <srabbelier@gmail.com>
--
Cheers,
Sverre Rabbelier
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings
2010-11-04 17:18 ` [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings Štěpán Němec
2010-11-04 17:22 ` Sverre Rabbelier
@ 2010-11-04 17:49 ` Jeff King
2010-11-04 18:02 ` Jonathan Nieder
1 sibling, 1 reply; 43+ messages in thread
From: Jeff King @ 2010-11-04 17:49 UTC (permalink / raw)
To: Štěpán Němec
Cc: git, Sverre Rabbelier, Mark Lodato, Junio C Hamano,
Jonathan Nieder
On Thu, Nov 04, 2010 at 06:18:17PM +0100, Štěpán Němec wrote:
> This was the only occurence of that usage, and square brackets are
> sufficient and already well-established for that purpose.
>
> Signed-off-by: Štěpán Němec <stepnem@gmail.com>
> ---
>
> As per discussion upthread, this notation is not worth keeping; hence
> not mentioning it in the v2 of the CodingGuidlines patch and this
> removal.
I agree the notation is kind of odd. But the intent of the original is
to point out that diff has several modes of operation, depending on the
number of arguments it is given. Your change seems to make that even
more subtle. I would be more in favor of showing the major modes of
operation, one per line, which is what we do in other places. E.g., see
git-branch(1).
Now in the case of diff, as soon as the "description" section starts, we
do start talking about those modes (and there are a lot of them). But I
think it may make sense to cover them with a short comment in the
synopsis. Something like:
# diff between index and working tree
git diff [options] [--] [<path>...]
# diff between HEAD and index
git diff --cached [options] [--] [<path>...]
# diff between commit and working tree
git diff [options] <commit> [--] [<path>...]
# diff between commit and index
git diff --cached [options] <commit> [--] [<path>...]
# diff between commits
git diff [options] <commit> <commit> [--] [<path>...]
# diff two paths
git diff [options] [--] <path> <path>
which obviously is way more verbose, but I think it improves in two
ways:
1. New users will immediately see what diff is for: it is the
all-purpose diffing tool in git, and it has several modes of
operation.
2. People who know what diff does but need a quick reference on which
mode they are looking for can quickly scan the list.
If it's too verbose, we could collapse a few cases (e.g., "HEAD and
index" and "commit and index" could come in one line).
-Peff
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings
2010-11-04 17:49 ` Jeff King
@ 2010-11-04 18:02 ` Jonathan Nieder
2010-11-04 18:13 ` Jeff King
0 siblings, 1 reply; 43+ messages in thread
From: Jonathan Nieder @ 2010-11-04 18:02 UTC (permalink / raw)
To: Jeff King
Cc: Štěpán Němec, git, Sverre Rabbelier,
Mark Lodato, Junio C Hamano
Jeff King wrote:
> # diff between index and working tree
> git diff [options] [--] [<path>...]
>
> # diff between HEAD and index
> git diff --cached [options] [--] [<path>...]
>
> # diff between commit and working tree
> git diff [options] <commit> [--] [<path>...]
>
> # diff between commit and index
> git diff --cached [options] <commit> [--] [<path>...]
>
> # diff between commits
> git diff [options] <commit> <commit> [--] [<path>...]
>
> # diff two paths
> git diff [options] [--] <path> <path>
>
> which obviously is way more verbose
Yes, that's way more verbose than a typical manpage synopsis.
For example, from printf(3):
SYNOPSIS
#include <stdio.h>
int printf(const char *format, ...);
int fprintf(FILE *stream, const char *format, ...);
int sprintf(char *str, const char *format, ...);
int snprintf(char *str, size_t size, const char *format, ...);
#include <stdarg.h>
int vprintf(const char *format, va_list ap);
int vfprintf(FILE *stream, const char *format, va_list ap);
int vsprintf(char *str, const char *format, va_list ap);
int vsnprintf(char *str, size_t size, const char *format, va_list ap);
Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
snprintf(), vsnprintf(): _BSD_SOURCE || _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE; or cc -std=c99
which would suggest that for git-diff(!) we should say something like:
SYNOPSIS
git diff [options] [--] [<path>...]
git diff [options] --cached [--] [<path>...]
git diff [options] <commit> [--] [<path>...]
git diff [options] --cached <commit> [--] [<path>...]
git diff [options] <commit> <commit> [--] [<path>...]
git diff [options] --no-index [--] <path> <path>
I would rather treat --cached as one of the options ("instead of
comparing the worktree, compare its cached content in the index to the
specified commit"), and if I were running the world, I'd leave off the
[options]. :)
SYNOPSIS
git diff [--] [<path>...]
git diff <commit> [--] [<path>...]
git diff <commit> <commit> [--] [<path>...]
git diff --no-index [--] <path> <path>
perhaps with some kind of reminder about --cached:
The first two forms accept a --cached option to compare
to staged content in the index instead of the work tree.
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings
2010-11-04 18:02 ` Jonathan Nieder
@ 2010-11-04 18:13 ` Jeff King
2010-11-04 18:38 ` Jonathan Nieder
0 siblings, 1 reply; 43+ messages in thread
From: Jeff King @ 2010-11-04 18:13 UTC (permalink / raw)
To: Jonathan Nieder
Cc: Štěpán Němec, git, Sverre Rabbelier,
Mark Lodato, Junio C Hamano
On Thu, Nov 04, 2010 at 01:02:42PM -0500, Jonathan Nieder wrote:
> Yes, that's way more verbose than a typical manpage synopsis.
Well, yes, but...
> For example, from printf(3):
>
> SYNOPSIS
> #include <stdio.h>
>
> int printf(const char *format, ...);
> int fprintf(FILE *stream, const char *format, ...);
> int sprintf(char *str, const char *format, ...);
> int snprintf(char *str, size_t size, const char *format, ...);
>
> #include <stdarg.h>
>
> int vprintf(const char *format, va_list ap);
> int vfprintf(FILE *stream, const char *format, va_list ap);
> int vsprintf(char *str, const char *format, va_list ap);
> int vsnprintf(char *str, size_t size, const char *format, va_list ap);
>
> Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
>
> snprintf(), vsnprintf(): _BSD_SOURCE || _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE; or cc -std=c99
That's a little unfair as a comparison, as it's from a different
section. Try "man IO::Handle", or most other perl modules, for example.
They are quite a bit more verbose.
But yes, in general it is more verbose than other commands in section 1.
> which would suggest that for git-diff(!) we should say something like:
>
> SYNOPSIS
>
> git diff [options] [--] [<path>...]
> git diff [options] --cached [--] [<path>...]
> git diff [options] <commit> [--] [<path>...]
> git diff [options] --cached <commit> [--] [<path>...]
> git diff [options] <commit> <commit> [--] [<path>...]
> git diff [options] --no-index [--] <path> <path>
I would be OK with that; my comment lines were an attempt to make it a
bit more clear to the user. But reading your revised versions, they seem
pretty clear to me. I think your example there can actually be collapsed
down to:
git diff [options] [<commit>] [--] [<path>...]
git diff [options] --cached [<commit>] [--] [<path>...]
git diff [options] <commit> <commit> [--] [<path>...]
git diff [options] [--no-index] [--] <path> <path>
which covers the four major modes.
> I would rather treat --cached as one of the options ("instead of
> comparing the worktree, compare its cached content in the index to the
> specified commit"),
Except it is not quite that. For the first two that I listed above,
--cached makes that distinction. But --cached doesn't make sense at all
in the third or fourth ones. So I think in practice it ends up defining
a mode of operation more than simply an option.
But I do recognize that such a distinction is largely in the mental
model of the user. On the other hand, this is documentation, so we are
trying to promote healthy mental models for users. :)
> and if I were running the world, I'd leave off the [options]. :)
I have no strong opinion on that. There are pretty few unix programs
that don't take [options] at the beginning, so it really is kind of
superfluous. But it's also pretty standard, and clues the user in that
we are a normal program.
-Peff
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings
2010-11-04 18:13 ` Jeff King
@ 2010-11-04 18:38 ` Jonathan Nieder
2010-11-04 18:55 ` Jeff King
0 siblings, 1 reply; 43+ messages in thread
From: Jonathan Nieder @ 2010-11-04 18:38 UTC (permalink / raw)
To: Jeff King
Cc: Štěpán Němec, git, Sverre Rabbelier,
Mark Lodato, Junio C Hamano
Jeff King wrote:
> git diff [options] [<commit>] [--] [<path>...]
> git diff [options] --cached [<commit>] [--] [<path>...]
> git diff [options] <commit> <commit> [--] [<path>...]
> git diff [options] [--no-index] [--] <path> <path>
>
> which covers the four major modes.
Makes sense. There is just one particularity of
git diff --cached [<commit>]
I am worried about. Namely: according to a recent patch,
git diff --cached
should not be considered as
git diff --cached HEAD
with the "HEAD" implicit, but a distinct operation meaning
"show me what changes git commit would store".
> On Thu, Nov 04, 2010 at 01:02:42PM -0500, Jonathan Nieder wrote:
>> I would rather treat --cached as one of the options ("instead of
>> comparing the worktree, compare its cached content in the index to the
>> specified commit"),
>
> Except it is not quite that. For the first two that I listed above,
> --cached makes that distinction. But --cached doesn't make sense at all
> in the third or fourth ones. So I think in practice it ends up defining
> a mode of operation more than simply an option.
Not sure I understand your logic. Is your point that --cached in
those cases does not print
fatal: --cached does not make sense in this operation mode
but
usage: git diff <options> <rev>{0,2} -- <path>*
that implies the operation mode is not known?
> There are pretty few unix programs
> that don't take [options] at the beginning, so it really is kind of
> superfluous. But it's also pretty standard, and clues the user in that
> we are a normal program.
Yes, sorry about the tangent.
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings
2010-11-04 18:38 ` Jonathan Nieder
@ 2010-11-04 18:55 ` Jeff King
2010-11-04 20:26 ` Štěpán Němec
0 siblings, 1 reply; 43+ messages in thread
From: Jeff King @ 2010-11-04 18:55 UTC (permalink / raw)
To: Jonathan Nieder
Cc: Štěpán Němec, git, Sverre Rabbelier,
Mark Lodato, Junio C Hamano
On Thu, Nov 04, 2010 at 01:38:51PM -0500, Jonathan Nieder wrote:
> Makes sense. There is just one particularity of
>
> git diff --cached [<commit>]
>
> I am worried about. Namely: according to a recent patch,
>
> git diff --cached
>
> should not be considered as
>
> git diff --cached HEAD
>
> with the "HEAD" implicit, but a distinct operation meaning
> "show me what changes git commit would store".
Yeah, I'm not sure I agree with that change, for the reason that it
makes "git diff" more conceptually complex. Generally we think of "no
commit" as "behave as if HEAD was given". But now it's not, but only in
this one particular place.
I guess I should go complain in that thread, though...
> >> I would rather treat --cached as one of the options ("instead of
> >> comparing the worktree, compare its cached content in the index to the
> >> specified commit"),
> >
> > Except it is not quite that. For the first two that I listed above,
> > --cached makes that distinction. But --cached doesn't make sense at all
> > in the third or fourth ones. So I think in practice it ends up defining
> > a mode of operation more than simply an option.
>
> Not sure I understand your logic. Is your point that --cached in
> those cases does not print
>
> fatal: --cached does not make sense in this operation mode
>
> but
>
> usage: git diff <options> <rev>{0,2} -- <path>*
>
> that implies the operation mode is not known?
No, I am fine with what it actually prints[1]. But my point is that
"--cached" is not simply an option that should go in [options] in each
synopsis line. Even though it _looks_ like an option (because it starts
with --, and can go anywhere in the options list) it changes the syntax
of the rest of the command line (in particular, you can provide 0 or 1
commits, not 2, and you cannot use --no-index)[2].
Removing it from the synopsis and just listing it as an option does not
capture that aspect.
And yes, it's obviously a gray area. There are other mutually exclusive
options that are really just normal options. I just happen to think that
the action of "--cached" changes the operation significantly enough to
be considered a separate mode. Just as we do with "-m" and "-d" for
git-branch.
-Peff
[1] If we are on a quest to remove <rev>{0,2}, this is one other spot to
do it.
[2] This ties in with an idea mentioned in years past (but never
actually implemented) to have some symbolic name for referring to
the working tree and index, like:
git diff HEAD INDEX
which makes it quite obvious what is going on, and that diff really
only has one syntactic mode: diff thing A and thing B. The details
of that depend on what thing A and thing B actually resolve to. But
in theory that is identical to "git diff --cached HEAD".
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings
2010-11-04 18:55 ` Jeff King
@ 2010-11-04 20:26 ` Štěpán Němec
2010-11-04 20:43 ` Jeff King
0 siblings, 1 reply; 43+ messages in thread
From: Štěpán Němec @ 2010-11-04 20:26 UTC (permalink / raw)
To: Jeff King
Cc: Jonathan Nieder, git, Sverre Rabbelier, Mark Lodato,
Junio C Hamano
Jeff King <peff@peff.net> writes:
[...]
>> usage: git diff <options> <rev>{0,2} -- <path>*
[...]
> [1] If we are on a quest to remove <rev>{0,2}, this is one other spot to
> do it.
That's already included in the patch.
I think this thread already has nothing to do with the purpose of the
patch, though. I find your suggestion that <commit>{0,2} better conveys
some information about git-diff's operation modes than [<commit>
[<commit>]] does (which seems to have been your starting point) rather
far-fetched.
Note that I do not feel strongly about removing the {M,N} notation (I
expressed my opinion in the thread already[1]), but I see the notation
problem as orthogonal to the issues you are discussing here.
So AIUI the patch can still be applied and we/you can then work on
improving the usage string in other ways -- providing that we agree that
the {M,N} notation should go, of course, which we apparently still
don't?
In any case this seems to be less and less my itch to scratch, so I'm
not sure I'm going to be of much help in this discussion. The thing I
need to know for the CodingGuidelines patch is whether we're going to
preserve and encourage the {M,N} usage or not (so please let's arrive to
some conclusion on that matter -- I waited for several days before
sending the updated version and nobody chimed in, so I assumed nobody
other than Mark and Sverre really cared). Although, that's actually
somewhat orthogonal, too -- we can always re-add the {M,N} subsection
later.
Thanks,
Štěpán
[1]
http://thread.gmane.org/gmane.comp.version-control.git/158467/focus=160330
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings
2010-11-04 20:26 ` Štěpán Němec
@ 2010-11-04 20:43 ` Jeff King
2010-11-04 21:17 ` [PATCH] docs: clarify git diff modes of operation Jeff King
2010-11-04 21:30 ` [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings Štěpán Němec
0 siblings, 2 replies; 43+ messages in thread
From: Jeff King @ 2010-11-04 20:43 UTC (permalink / raw)
To: Štěpán Němec
Cc: Jonathan Nieder, git, Sverre Rabbelier, Mark Lodato,
Junio C Hamano
On Thu, Nov 04, 2010 at 09:26:14PM +0100, Štěpán Němec wrote:
> > [1] If we are on a quest to remove <rev>{0,2}, this is one other spot to
> > do it.
>
> That's already included in the patch.
Ah, sorry, I missed that hunk.
> I think this thread already has nothing to do with the purpose of the
> patch, though. I find your suggestion that <commit>{0,2} better conveys
> some information about git-diff's operation modes than [<commit>
> [<commit>]] does (which seems to have been your starting point) rather
> far-fetched.
I find your version slightly harder to read than the original, which is
why I complained. However, I find both way worse than what Jonathan and
I ended up with.
> So AIUI the patch can still be applied and we/you can then work on
> improving the usage string in other ways -- providing that we agree that
> the {M,N} notation should go, of course, which we apparently still
> don't?
My main argument against that would be that if we are planning on
changing it to something totally different right now anyway, your patch
will just end up making textual conflicts for Junio to resolve. :)
> In any case this seems to be less and less my itch to scratch, so I'm
> not sure I'm going to be of much help in this discussion. The thing I
> need to know for the CodingGuidelines patch is whether we're going to
> preserve and encourage the {M,N} usage or not (so please let's arrive to
> some conclusion on that matter -- I waited for several days before
> sending the updated version and nobody chimed in, so I assumed nobody
> other than Mark and Sverre really cared). Although, that's actually
> somewhat orthogonal, too -- we can always re-add the {M,N} subsection
> later.
Yeah, sorry to come in late to the discussion. I missed the other thread
entirely. I think getting rid of {M,N} is fine. In general, your
proposed replacement is better. It's just that in this case it seemed to
be obfuscating a subtle point that the original syntax (as ugly and
incomprehensible as it was) called out.
So yes, go ahead with your coding guidelines patch. I'll summarize what
Jonathan and I discussed with a new patch.
-Peff
^ permalink raw reply [flat|nested] 43+ messages in thread
* [PATCH] docs: clarify git diff modes of operation
2010-11-04 20:43 ` Jeff King
@ 2010-11-04 21:17 ` Jeff King
2010-11-04 21:50 ` Jonathan Nieder
2010-11-04 21:51 ` Štěpán Němec
2010-11-04 21:30 ` [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings Štěpán Němec
1 sibling, 2 replies; 43+ messages in thread
From: Jeff King @ 2010-11-04 21:17 UTC (permalink / raw)
To: Štěpán Němec
Cc: Jonathan Nieder, git, Sverre Rabbelier, Mark Lodato,
Junio C Hamano
It is an oversimplification to say that we can take
"[<commit> [<commit>]]", as it really depends on what
options have been given. Instead, let's list the major modes
of operation separately, as we do in other manpages.
This patch also adjusts the text immediately after the
synopsis to match the lines given in the synopsis.
For git-difftool, which has the same issue, let's refer the
user to the git-diff manpage rather than spelling it all out
again.
Signed-off-by: Jeff King <peff@peff.net>
---
On Thu, Nov 04, 2010 at 04:43:04PM -0400, Jeff King wrote:
> > So AIUI the patch can still be applied and we/you can then work on
> > improving the usage string in other ways -- providing that we agree that
> > the {M,N} notation should go, of course, which we apparently still
> > don't?
>
> My main argument against that would be that if we are planning on
> changing it to something totally different right now anyway, your patch
> will just end up making textual conflicts for Junio to resolve. :)
I had intially thought I would tweak all three sites that you did, but
after thinking about it, I really just want to change the one in
Documentation/git-diff.txt. Which turned my patch into a mix of two
different changes, and means it probably should just go on top of yours.
So here is my patch, which should apply on top of yours.
Note that in all versions (the original, yours, and mine) we gloss over
the fact that <commit> can actually be any two objects (as long as they
are bother either tree-ishs or blobs). I'm not sure if it is worth
documenting that subtlety here (at least the tree-ish thing gets
mentioned later in the description; I'm not sure we ever document "git
diff HEAD:Makefile HEAD^:Makefile" anywhere).
Jonathan, does this look ok based on our earlier discussion?
Documentation/git-diff.txt | 11 ++++++++---
Documentation/git-difftool.txt | 3 ++-
2 files changed, 10 insertions(+), 4 deletions(-)
diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 61728f6..f6ac847 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -8,12 +8,17 @@ git-diff - Show changes between commits, commit and working tree, etc
SYNOPSIS
--------
-'git diff' [<common diff options>] [<commit> [<commit>]] [--] [<path>...]
+[verse]
+'git diff' [options] [<commit>] [--] [<path>...]
+'git diff' [options] --cached [<commit>] [--] [<path>...]
+'git diff' [options] <commit> <commit> [--] [<path>...]
+'git diff' [options] [--no-index] [--] <path> <path>
DESCRIPTION
-----------
-Show changes between two trees, a tree and the working tree, a
-tree and the index file, or the index file and the working tree.
+Show changes between the working tree and the index or a tree, changes
+between the index and a tree, changes between two trees, or changes
+between two files on disk.
'git diff' [--options] [--] [<path>...]::
diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt
index a02e3b5..6fffbc7 100644
--- a/Documentation/git-difftool.txt
+++ b/Documentation/git-difftool.txt
@@ -13,7 +13,8 @@ DESCRIPTION
-----------
'git difftool' is a git command that allows you to compare and edit files
between revisions using common diff tools. 'git difftool' is a frontend
-to 'git diff' and accepts the same options and arguments.
+to 'git diff' and accepts the same options and arguments. See
+linkgit:git-diff[1].
OPTIONS
-------
--
1.7.3.2.218.g4ee9d
^ permalink raw reply related [flat|nested] 43+ messages in thread
* Re: [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings
2010-11-04 20:43 ` Jeff King
2010-11-04 21:17 ` [PATCH] docs: clarify git diff modes of operation Jeff King
@ 2010-11-04 21:30 ` Štěpán Němec
1 sibling, 0 replies; 43+ messages in thread
From: Štěpán Němec @ 2010-11-04 21:30 UTC (permalink / raw)
To: Jeff King
Cc: Jonathan Nieder, git, Sverre Rabbelier, Mark Lodato,
Junio C Hamano
Jeff King <peff@peff.net> writes:
> My main argument against that would be that if we are planning on
> changing it to something totally different right now anyway, your patch
> will just end up making textual conflicts for Junio to resolve. :)
Right. I hoped you'd come up with a patch yourself, which now happend,
so, thank you. :-)
> Yeah, sorry to come in late to the discussion. I missed the other thread
> entirely. I think getting rid of {M,N} is fine. In general, your
> proposed replacement is better. It's just that in this case it seemed to
> be obfuscating a subtle point that the original syntax (as ugly and
> incomprehensible as it was) called out.
>
> So yes, go ahead with your coding guidelines patch. I'll summarize what
> Jonathan and I discussed with a new patch.
In that case the v2 [1] is still a valid review target, thanks.
Štěpán
[1] Earlier in the thread and here for anyone interested:
http://article.gmane.org/gmane.comp.version-control.git/160733
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH] docs: clarify git diff modes of operation
2010-11-04 21:17 ` [PATCH] docs: clarify git diff modes of operation Jeff King
@ 2010-11-04 21:50 ` Jonathan Nieder
2010-11-05 1:57 ` Mark Lodato
2010-11-04 21:51 ` Štěpán Němec
1 sibling, 1 reply; 43+ messages in thread
From: Jonathan Nieder @ 2010-11-04 21:50 UTC (permalink / raw)
To: Jeff King
Cc: Štěpán Němec, git, Sverre Rabbelier,
Mark Lodato, Junio C Hamano
Jeff King wrote:
> Jonathan, does this look ok based on our earlier discussion?
Yep, it's way better than the current state.
The list of operation modes still seems wrong: in addition to
the meaning of
git diff --cached
from an unborn branch not fitting the model of implicit HEAD
as mentioned before, there is also
git diff
not meaning the same thing as
git diff HEAD
. So I guess technically the separate operation modes are
git diff [--cached]
git diff [--cached] <tree>
git diff <tree> <tree>
git diff --no-index <path> <path>
git diff <blob> <blob>
where --cached means "use the version of the work tree stored
in the index in place of the real thing".
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH] docs: clarify git diff modes of operation
2010-11-04 21:17 ` [PATCH] docs: clarify git diff modes of operation Jeff King
2010-11-04 21:50 ` Jonathan Nieder
@ 2010-11-04 21:51 ` Štěpán Němec
1 sibling, 0 replies; 43+ messages in thread
From: Štěpán Němec @ 2010-11-04 21:51 UTC (permalink / raw)
To: Jeff King
Cc: Jonathan Nieder, git, Sverre Rabbelier, Mark Lodato,
Junio C Hamano
Jeff King <peff@peff.net> writes:
> Note that in all versions (the original, yours, and mine) we gloss over
> the fact that <commit> can actually be any two objects (as long as they
> are bother either tree-ishs or blobs).
Yeah, I thought about that, too. I think it would be nice to use more
precise placeholders like <tree-ish> or <object> (which do already
occur in other places), but I suspect it might be needed/useful at more
places and would better be done as a separate patch (preferably by someone
who is more familiar with the internals than me).
> I'm not sure if it is worth documenting that subtlety here (at least
> the tree-ish thing gets mentioned later in the description; I'm not
> sure we ever document "git diff HEAD:Makefile HEAD^:Makefile"
> anywhere).
There's gitrevisions(7) (also pointed to from the git-diff manpage)
which describes those in some detail.
Štěpán
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH] docs: clarify git diff modes of operation
2010-11-04 21:50 ` Jonathan Nieder
@ 2010-11-05 1:57 ` Mark Lodato
0 siblings, 0 replies; 43+ messages in thread
From: Mark Lodato @ 2010-11-05 1:57 UTC (permalink / raw)
To: Jonathan Nieder
Cc: Jeff King, Štěpán Němec, git,
Sverre Rabbelier, Junio C Hamano
On Thu, Nov 4, 2010 at 5:50 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:
> . So I guess technically the separate operation modes are
>
> git diff [--cached]
> git diff [--cached] <tree>
> git diff <tree> <tree>
> git diff --no-index <path> <path>
> git diff <blob> <blob>
>
> where --cached means "use the version of the work tree stored
> in the index in place of the real thing".
I prefer this above the other proposals. This breakdown makes the
most sense to me, and I see no reason to use <commit> when we really
mean <tree>. One minor thing: should the "<blob> <blob>" form be
moved above "<path> <path>" so that all the git object forms are
together?
On a related note, I find it a bit confusing that <path> is used to
mean two very different things. For "<path> <path>", it means a file
that must exist on disk. For "[<path>...]", it means a pattern on
which to filter the output of the command. Since we already have a
name for the latter, perhaps we should use the term "[<pathspec>...]".
^ permalink raw reply [flat|nested] 43+ messages in thread
end of thread, other threads:[~2010-11-05 1:57 UTC | newest]
Thread overview: 43+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2010-10-08 0:52 [PATCH/RFC] Unify argument and option notation in the docs Štěpán Němec
2010-10-08 7:43 ` Jonathan Nieder
2010-10-08 11:13 ` Štěpán Němec
2010-10-08 17:31 ` [PATCH 0/6] " Štěpán Němec
2010-10-08 17:44 ` Jonathan Nieder
2010-10-08 19:43 ` Junio C Hamano
2010-10-08 20:15 ` Štěpán Němec
2010-10-21 22:21 ` Jonathan Nieder
2010-10-24 15:51 ` [PATCH] CodingGuidelines: Add a section on writing documentation Štěpán Němec
2010-10-29 2:56 ` Mark Lodato
2010-10-29 11:54 ` Štěpán Němec
2010-10-29 17:14 ` Sverre Rabbelier
2010-11-01 17:00 ` Štěpán Němec
2010-11-04 17:12 ` [PATCH v2] " Štěpán Němec
2010-11-04 17:18 ` [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings Štěpán Němec
2010-11-04 17:22 ` Sverre Rabbelier
2010-11-04 17:49 ` Jeff King
2010-11-04 18:02 ` Jonathan Nieder
2010-11-04 18:13 ` Jeff King
2010-11-04 18:38 ` Jonathan Nieder
2010-11-04 18:55 ` Jeff King
2010-11-04 20:26 ` Štěpán Němec
2010-11-04 20:43 ` Jeff King
2010-11-04 21:17 ` [PATCH] docs: clarify git diff modes of operation Jeff King
2010-11-04 21:50 ` Jonathan Nieder
2010-11-05 1:57 ` Mark Lodato
2010-11-04 21:51 ` Štěpán Němec
2010-11-04 21:30 ` [PATCH] diff,difftool: Don't use the {0,2} notation in usage strings Štěpán Němec
2010-10-08 17:31 ` [PATCH 1/6] Use angles for placeholders consistently Štěpán Němec
2010-10-08 17:31 ` [PATCH 2/6] Fix odd markup in --diff-filter documentation Štěpán Němec
2010-10-08 17:39 ` Jonathan Nieder
2010-10-08 17:57 ` Štěpán Němec
2010-10-08 18:03 ` Jonathan Nieder
2010-10-08 18:40 ` Štěpán Němec
2010-10-08 18:53 ` Jonathan Nieder
2010-10-08 17:31 ` [PATCH 3/6] Use parentheses and `...' where appropriate Štěpán Němec
2010-10-08 17:31 ` [PATCH 4/6] Remove stray quotes in --pretty and --format documentation Štěpán Němec
2010-10-08 17:31 ` [PATCH 5/6] Put a space between `<' and argument in pack-objects usage string Štěpán Němec
2010-10-08 17:31 ` [PATCH 6/6] Fix {update,checkout}-index usage strings Štěpán Němec
2010-10-08 16:45 ` [PATCH 0/2] pack-objects: use ALLOC_GROW in place of manual growth Jonathan Nieder
2010-10-08 16:46 ` [PATCH 1/2] Documentation: No argument of ALLOC_GROW should have side-effects Jonathan Nieder
2010-10-08 16:47 ` [PATCH 2/2] pack-objects: use ALLOC_GROW Jonathan Nieder
2010-10-08 17:02 ` [PATCH 3/2] Allow side-effects in second argument to ALLOC_GROW Jonathan Nieder
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).