Changeset 782 for git/branches/dmik/Documentation/git-rev-parse.txt

Timestamp:

Jun 23, 2014, 9:45:51 PM (11 years ago)

Author:

dmik

Message:

git: Merge version 2.0.0 from vendor to dmik branch.

Location:

git/branches/dmik

Files:

• . (modified) (1 prop)
• Documentation/git-rev-parse.txt (modified) (17 diffs)

git/branches/dmik/Documentation/git-rev-parse.txt ¶

@@ -15 +15 @@
 -----------
 
-Many git porcelainish commands take mixture of flags
+Many Git porcelainish commands take mixture of flags
 (i.e. parameters that begin with a dash '-') and parameters
 meant for the underlying 'git rev-list' command they use internally
@@ -25 +25 @@
 OPTIONS
 -------
+
+Operation Modes
+~~~~~~~~~~~~~~~
+
+Each of these options must appear first on the command line.
+
 --parseopt::
         Use 'git rev-parse' in option parsing mode (see PARSEOPT section below).
+
+--sq-quote::
+        Use 'git rev-parse' in shell quoting mode (see SQ-QUOTE
+        section below). In contrast to the `--sq` option below, this
+        mode does only quoting. Nothing else is done to command input.
+
+Options for --parseopt
+~~~~~~~~~~~~~~~~~~~~~~
 
 --keep-dashdash::
@@ -37 +51 @@
         that take options themselves.
 
---sq-quote::
-        Use 'git rev-parse' in shell quoting mode (see SQ-QUOTE
-        section below). In contrast to the `--sq` option below, this
-        mode does only quoting. Nothing else is done to command input.
+--stuck-long::
+        Only meaningful in `--parseopt` mode. Output the options in their
+        long form if available, and with their arguments stuck.
+
+Options for Filtering
+~~~~~~~~~~~~~~~~~~~~~
 
 --revs-only::
@@ -56 +72 @@
         Do not output flag parameters.
 
+Options for Output
+~~~~~~~~~~~~~~~~~~
+
 --default <arg>::
         If there is no parameter given by the user, use `<arg>`
         instead.
 
+--prefix <arg>::
+        Behave as if 'git rev-parse' was invoked from the `<arg>`
+        subdirectory of the working tree.  Any relative filenames are
+        resolved as if they are prefixed by `<arg>` and will be printed
+        in that form.
++
+This can be used to convert arguments to a command run in a subdirectory
+so that they can still be used after moving to the top-level of the
+repository.  For example:
++
+----
+prefix=$(git rev-parse --show-prefix)
+cd "$(git rev-parse --show-toplevel)"
+eval "set -- $(git rev-parse --sq --prefix "$prefix" "$@")"
+----
+
 --verify::
-        The parameter given must be usable as a single, valid
-        object name.  Otherwise barf and abort.
+        Verify that exactly one parameter is provided, and that it
+        can be turned into a raw 20-byte SHA-1 that can be used to
+        access the object database. If so, emit it to the standard
+        output; otherwise, error out.
++
+If you want to make sure that the output actually names an object in
+your object database and/or can be used as a specific type of object
+you require, you can add "^{type}" peeling operator to the parameter.
+For example, `git rev-parse "$VAR^{commit}"` will make sure `$VAR`
+names an existing object that is a commit-ish (i.e. a commit, or an
+annotated tag that points at a commit).  To make sure that `$VAR`
+names an existing object of any type, `git rev-parse "$VAR^{object}"`
+can be used.
 
 -q::
@@ -84 +130 @@
         one.
 
+--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.
+
+--short::
+--short=number::
+        Instead of outputting the full SHA-1 values of object names try to
+        abbreviate them to a shorter unique name. When no length is specified
+        7 is used. The minimum length is 4.
+
 --symbolic::
-        Usually the object names are output in SHA1 form (with
+        Usually the object names are output in SHA-1 form (with
         possible '{caret}' prefix); this option makes them output in a
         form as close to the original input as possible.
@@ -97 +154 @@
         refnames (e.g. "refs/heads/master").
 
---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.
+Options for Objects
+~~~~~~~~~~~~~~~~~~~
 
 --all::
@@ -114 +169 @@
 If a `pattern` is given, only refs matching the given shell glob are
 shown.  If the pattern does not contain a globbing character (`?`,
-`{asterisk}`, or `[`), it is turned into a prefix match by
-appending `/{asterisk}`.
+`*`, or `[`), it is turned into a prefix match by appending `/*`.
 
 --glob=pattern::
@@ -121 +175 @@
         the pattern does not start with `refs/`, this is automatically
         prepended.  If the pattern does not contain a globbing
-        character (`?`, `{asterisk}`, or `[`), it is turned into a prefix
-        match by appending `/{asterisk}`.
-
---show-toplevel::
-        Show the absolute path of the top-level directory.
-
---show-prefix::
-        When the command is invoked from a subdirectory, show the
-        path of the current directory relative to the top-level
-        directory.
-
---show-cdup::
-        When the command is invoked from a subdirectory, show the
-        path of the top-level directory relative to the current
-        directory (typically a sequence of "../", or an empty string).
-
---git-dir::
-        Show `$GIT_DIR` if defined. Otherwise show the path to
-        the .git directory, relative to the current directory.
-+
-If `$GIT_DIR` is not defined and the current directory
-is not detected to lie in a git repository or work tree
-print a message to stderr and exit with nonzero status.
-
---is-inside-git-dir::
-        When the current working directory is below the repository
-        directory print "true", otherwise "false".
-
---is-inside-work-tree::
-        When the current working directory is inside the work tree of the
-        repository print "true", otherwise "false".
-
---is-bare-repository::
-        When the repository is bare print "true", otherwise "false".
+        character (`?`, `*`, or `[`), it is turned into a prefix
+        match by appending `/*`.
+
+--exclude=<glob-pattern>::
+        Do not include refs matching '<glob-pattern>' that the next `--all`,
+        `--branches`, `--tags`, `--remotes`, or `--glob` would otherwise
+        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).
++
+The patterns given should not begin with `refs/heads`, `refs/tags`, or
+`refs/remotes` when applied to `--branches`, `--tags`, or `--remotes`,
+respectively, and they must begin with `refs/` when applied to `--glob`
+or `--all`. If a trailing '/{asterisk}' is intended, it must be given
+explicitly.
+
+--disambiguate=<prefix>::
+        Show every object whose name begins with the given prefix.
+        The <prefix> must be at least 4 hexadecimal digits long to
+        avoid listing each and every object in the repository by
+        mistake.
+
+Options for Files
+~~~~~~~~~~~~~~~~~
 
 --local-env-vars::
@@ -162 +207 @@
         even if they are set.
 
---short::
---short=number::
-        Instead of outputting the full SHA1 values of object names try to
-        abbreviate them to a shorter unique name. When no length is specified
-        7 is used. The minimum length is 4.
+--git-dir::
+        Show `$GIT_DIR` if defined. Otherwise show the path to
+        the .git directory. The path shown, when relative, is
+        relative to the current working directory.
++
+If `$GIT_DIR` is not defined and the current directory
+is not detected to lie in a Git repository or work tree
+print a message to stderr and exit with nonzero status.
+
+--is-inside-git-dir::
+        When the current working directory is below the repository
+        directory print "true", otherwise "false".
+
+--is-inside-work-tree::
+        When the current working directory is inside the work tree of the
+        repository print "true", otherwise "false".
+
+--is-bare-repository::
+        When the repository is bare print "true", otherwise "false".
+
+--resolve-git-dir <path>::
+        Check if <path> is a valid repository or a gitfile that
+        points at a valid repository, and print the location of the
+        repository.  If <path> is a gitfile then the resolved path
+        to the real repository is printed.
+
+--show-cdup::
+        When the command is invoked from a subdirectory, show the
+        path of the top-level directory relative to the current
+        directory (typically a sequence of "../", or an empty string).
+
+--show-prefix::
+        When the command is invoked from a subdirectory, show the
+        path of the current directory relative to the top-level
+        directory.
+
+--show-toplevel::
+        Show the absolute path of the top-level directory.
+
+Other Options
+~~~~~~~~~~~~~
 
 --since=datestring::
@@ -181 +262 @@
         Flags and parameters to be parsed.
 
---resolve-git-dir <path>::
-        Check if <path> is a valid git-dir or a git-file pointing to a valid
-        git-dir. If <path> is a valid git-dir the resolved path to git-dir will
-        be printed.
 
 include::revisions.txt[]
@@ -208 +285 @@
 '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.
 
@@ -214 +291 @@
 
 ------------
-<opt_spec><flags>* SP+ help LF
-------------
-
-`<opt_spec>`::
+<opt-spec><flags>*<arg-hint>? SP+ help LF
+------------
+
+`<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>`::
@@ -227 +304 @@
         * Use `=` if the option takes an argument.
 
-        * Use `?` to mean that the option is optional (though its use is discouraged).
+        * Use `?` to mean that the option takes an optional argument. You
+          probably want to use the `--stuck-long` mode to be able to
+          unambiguously parse the optional argument.
 
         * Use `*` to mean that this option should not be listed in the usage
@@ -235 +314 @@
         * 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.
@@ -255 +340 @@
 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
@@ -260 +347 @@
 
 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
 ------------
 
@@ -301 +410 @@
 +
 ------------
-$ git rev-parse --verify $REV
+$ git rev-parse --verify $REV^{commit}
 ------------
 +
 This will error out if $REV is empty or not a valid revision.
 
-* Same as above:
+* Similar to above:
 +
 ------------