diff options
Diffstat (limited to 'Documentation/git-rev-parse.txt')
| -rw-r--r-- | Documentation/git-rev-parse.txt | 247 |
1 files changed, 190 insertions, 57 deletions
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index ff23cb0219..95326b85ff 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -8,12 +8,13 @@ git-rev-parse - Pick out and massage parameters SYNOPSIS -------- +[verse] 'git rev-parse' [ --option ] <args>... DESCRIPTION ----------- -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 and flags and parameters for the other commands they use @@ -23,9 +24,23 @@ distinguish between them. 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:: Only meaningful in `--parseopt` mode. Tells the option parser to echo out the first `--` met instead of skipping it. @@ -35,10 +50,12 @@ OPTIONS the first non-option argument. This can be used to parse sub-commands 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:: Do not output flags and parameters not meant for @@ -54,19 +71,51 @@ OPTIONS --no-flags:: 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)" +# rev-parse provides the -- needed for 'set' +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 the `^{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:: --quiet:: 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 @@ -77,28 +126,37 @@ OPTIONS 'git diff-{asterisk}'). In contrast to the `--sq-quote` option, the command input is still interpreted as usual. +--short[=length]:: + Same as `--verify` but shortens the object name to a unique + prefix with at least `length` characters. The minimum length + is 4, the default is the effective value of the `core.abbrev` + configuration variable (see linkgit:git-config[1]). + --not:: When showing object names, prefix them with '{caret}' and strip '{caret}' prefix from the object names that already have 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. + --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. --symbolic-full-name:: - This is similar to \--symbolic, but it omits input that + This is similar to --symbolic, but it omits input that are not refs (i.e. branch or tag names; or more explicitly disambiguating "heads/master" form, when you want to name the "master" branch when there is an unfortunately named tag "master"), and show them as full 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:: Show all refs found in `refs/`. @@ -112,37 +170,60 @@ OPTIONS + 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:: Show all refs matching the shell glob pattern `pattern`. If 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}`. + 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 + accumulated 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. ---show-toplevel:: - Show the absolute path of the top-level directory. +--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. ---show-prefix:: - When the command is invoked from a subdirectory, show the - path of the current directory relative to the top-level - directory. +Options for Files +~~~~~~~~~~~~~~~~~ ---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). +--local-env-vars:: + List the GIT_* environment variables that are local to the + repository (e.g. GIT_DIR or GIT_WORK_TREE, but not GIT_EDITOR). + Only the names of the variables are listed, not their value, + even if they are set. --git-dir:: Show `$GIT_DIR` if defined. Otherwise show the path to - the .git directory, relative to the current directory. + 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 +is not detected to lie in a Git repository or work tree print a message to stderr and exit with nonzero status. +--absolute-git-dir:: + Like `--git-dir`, but its output is always the canonicalized + absolute path. + +--git-common-dir:: + Show `$GIT_COMMON_DIR` if defined, else `$GIT_DIR`. + --is-inside-git-dir:: When the current working directory is below the repository directory print "true", otherwise "false". @@ -154,17 +235,47 @@ print a message to stderr and exit with nonzero status. --is-bare-repository:: When the repository is bare print "true", otherwise "false". ---local-env-vars:: - List the GIT_* environment variables that are local to the - repository (e.g. GIT_DIR or GIT_WORK_TREE, but not GIT_EDITOR). - Only the names of the variables are listed, not their value, - even if they are set. +--is-shallow-repository:: + When the repository is shallow 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. + +--git-path <path>:: + Resolve "$GIT_DIR/<path>" and takes other path relocation + variables such as $GIT_OBJECT_DIRECTORY, + $GIT_INDEX_FILE... into account. For example, if + $GIT_OBJECT_DIRECTORY is set to /foo/bar then "git rev-parse + --git-path objects/abc" returns /foo/bar/abc. + +--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. ---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. +--show-superproject-working-tree:: + Show the absolute path of the root of the superproject's + working tree (if exists) that uses the current repository as + its submodule. Outputs nothing if the current repository is + not used as a submodule by any project. + +--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 +~~~~~~~~~~~~~ --since=datestring:: --after=datestring:: @@ -202,26 +313,28 @@ 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>`. + is necessary. May not contain any of the `<flags>` characters. + `h,help`, `dry-run` and `f` are examples of correct `<opt-spec>`. `<flags>`:: `<flags>` are of `*`, `=`, `?` or `!`. * 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 generated for the `-h` argument. It's shown for `--help-all` as @@ -229,6 +342,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. @@ -249,6 +368,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" @@ -256,6 +377,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 -------- @@ -295,12 +438,12 @@ $ git rev-parse --verify HEAD * Print the commit object name from the revision in the $REV shell variable: + ------------ -$ 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: + ------------ $ git rev-parse --default master --verify $REV @@ -308,16 +451,6 @@ $ git rev-parse --default master --verify $REV + but if $REV is empty, the commit object name from master will be printed. - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> . -Junio C Hamano <gitster@pobox.com> and Pierre Habouzit <madcoder@debian.org> - -Documentation --------------- -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. - GIT --- Part of the linkgit:git[1] suite |