Merge branch 'mh/reflog-expire' into mh/ref-trans-value-check

diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 55ea1a037db76d03a3ad9c3a352d9a9e94d84bc9..d6de42f74efeedda228a97746c123de6e3e1f0ab 100644 (file)
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -114,6 +114,7 @@ can be used.
        Only meaningful in `--verify` mode. Do not output an error
        message if the first argument is not a valid object name;
        instead exit with non-zero status silently.
+       SHA-1s for valid object names are printed to stdout on success.
 
 --sq::
        Usually the output is made one line per flag and
@@ -183,7 +184,7 @@ shown.  If the pattern does not contain a globbing character (`?`,
        consider. Repetitions of this option accumulate exclusion patterns
        up to the next `--all`, `--branches`, `--tags`, `--remotes`, or
        `--glob` option (other options or arguments do not clear
-       accumlated patterns).
+       accumulated patterns).
 +
 The patterns given should not begin with `refs/heads`, `refs/tags`, or
 `refs/remotes` when applied to `--branches`, `--tags`, or `--remotes`,
@@ -245,6 +246,10 @@ print a message to stderr and exit with nonzero status.
 --show-toplevel::
        Show the absolute path of the top-level directory.
 
+--shared-index-path::
+       Show the path to the shared index file in split index mode, or
+       empty if not in split-index mode.
+
 Other Options
 ~~~~~~~~~~~~~
 
@@ -284,20 +289,20 @@ Input Format
 
 'git rev-parse --parseopt' input format is fully text based. It has two parts,
 separated by a line that contains only `--`. The lines before the separator
-(should be more than one) are used for the usage.
+(should be one or more) are used for the usage.
 The lines after the separator describe the options.
 
 Each line of options has this format:
 
 ------------
-<opt_spec><flags>* SP+ help LF
+<opt-spec><flags>*<arg-hint>? SP+ help LF
 ------------
 
-`<opt_spec>`::
+`<opt-spec>`::
        its format is the short option character, then the long option name
        separated by a comma. Both parts are not required, though at least one
        is necessary. `h,help`, `dry-run` and `f` are all three correct
-       `<opt_spec>`.
+       `<opt-spec>`.
 
 `<flags>`::
        `<flags>` are of `*`, `=`, `?` or `!`.
@@ -313,6 +318,12 @@ Each line of options has this format:
 
        * Use `!` to not make the corresponding negated long option available.
 
+`<arg-hint>`::
+       `<arg-hint>`, if specified, is used as a name of the argument in the
+       help output, for options that take arguments. `<arg-hint>` is
+       terminated by the first whitespace.  It is customary to use a
+       dash to separate words in a multi-word argument hint.
+
 The remainder of the line, after stripping the spaces, is used
 as the help associated to the option.
 
@@ -333,6 +344,8 @@ h,help    show the help
 
 foo       some nifty option --foo
 bar=      some cool option --bar with an argument
+baz=arg   another cool option --baz with a named argument
+qux?path  qux may take a path argument but has meaning by itself
 
   An option group Header
 C?        option C with an optional argument"
@@ -340,6 +353,28 @@ C?        option C with an optional argument"
 eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)"
 ------------
 
+
+Usage text
+~~~~~~~~~~
+
+When `"$@"` is `-h` or `--help` in the above example, the following
+usage text would be shown:
+
+------------
+usage: some-command [options] <args>...
+
+    some-command does foo and bar!
+
+    -h, --help            show the help
+    --foo                 some nifty option --foo
+    --bar ...             some cool option --bar with an argument
+    --baz <arg>           another cool option --baz with a named argument
+    --qux[=<path>]        qux may take a path argument but has meaning by itself
+
+An option group Header
+    -C[...]               option C with an optional argument
+------------
+
 SQ-QUOTE
 --------