| git-rev-parse(1) |
| ================ |
| |
| NAME |
| ---- |
| git-rev-parse - Pick out and massage parameters |
| |
| |
| SYNOPSIS |
| -------- |
| [verse] |
| 'git rev-parse' [ --option ] <args>... |
| |
| DESCRIPTION |
| ----------- |
| |
| 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 |
| downstream of 'git rev-list'. This command is used to |
| distinguish between them. |
| |
| |
| OPTIONS |
| ------- |
| --parseopt:: |
| Use 'git rev-parse' in option parsing mode (see PARSEOPT section below). |
| |
| --keep-dashdash:: |
| Only meaningful in `--parseopt` mode. Tells the option parser to echo |
| out the first `--` met instead of skipping it. |
| |
| --stop-at-non-option:: |
| Only meaningful in `--parseopt` mode. Lets the option parser stop at |
| 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. |
| |
| --revs-only:: |
| Do not output flags and parameters not meant for |
| 'git rev-list' command. |
| |
| --no-revs:: |
| Do not output flags and parameters meant for |
| 'git rev-list' command. |
| |
| --flags:: |
| Do not output non-flag parameters. |
| |
| --no-flags:: |
| Do not output flag parameters. |
| |
| --default <arg>:: |
| If there is no parameter given by the user, use `<arg>` |
| instead. |
| |
| --verify:: |
| The parameter given must be usable as a single, valid |
| object name. Otherwise barf and abort. |
| |
| -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. |
| |
| --sq:: |
| Usually the output is made one line per flag and |
| parameter. This option makes output a single line, |
| properly quoted for consumption by shell. Useful when |
| you expect your parameter to contain whitespaces and |
| newlines (e.g. when using pickaxe `-S` with |
| 'git diff-{asterisk}'). In contrast to the `--sq-quote` option, |
| the command input is still interpreted as usual. |
| |
| --not:: |
| When showing object names, prefix them with '{caret}' and |
| strip '{caret}' prefix from the object names that already have |
| one. |
| |
| --symbolic:: |
| Usually the object names are output in SHA1 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 |
| 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. |
| |
| --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. |
| |
| --all:: |
| Show all refs found in `refs/`. |
| |
| --branches[=pattern]:: |
| --tags[=pattern]:: |
| --remotes[=pattern]:: |
| Show all branches, tags, or remote-tracking branches, |
| respectively (i.e., refs found in `refs/heads`, |
| `refs/tags`, or `refs/remotes`, respectively). |
| + |
| If a `pattern` is given, only refs matching the given shell glob are |
| shown. If the pattern does not contain a globbing character (`?`, |
| `*`, 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 (`?`, `*`, or `[`), it is turned into a prefix |
| match by appending `/*`. |
| |
| --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. 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". |
| |
| --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. |
| |
| --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. |
| |
| --since=datestring:: |
| --after=datestring:: |
| Parse the date string, and output the corresponding |
| --max-age= parameter for 'git rev-list'. |
| |
| --until=datestring:: |
| --before=datestring:: |
| Parse the date string, and output the corresponding |
| --min-age= parameter for 'git rev-list'. |
| |
| <args>...:: |
| Flags and parameters to be parsed. |
| |
| --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. |
| |
| |
| include::revisions.txt[] |
| |
| PARSEOPT |
| -------- |
| |
| In `--parseopt` mode, 'git rev-parse' helps massaging options to bring to shell |
| scripts the same facilities C builtins have. It works as an option normalizer |
| (e.g. splits single switches aggregate values), a bit like `getopt(1)` does. |
| |
| It takes on the standard input the specification of the options to parse and |
| understand, and echoes on the standard output a string suitable for `sh(1)` `eval` |
| to replace the arguments with normalized ones. In case of error, it outputs |
| usage on the standard error stream, and exits with code 129. |
| |
| Note: Make sure you quote the result when passing it to `eval`. See |
| below for an example. |
| |
| 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. |
| The lines after the separator describe the options. |
| |
| Each line of options has this format: |
| |
| ------------ |
| <opt_spec><flags>* 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>`. |
| |
| `<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 this option should not be listed in the usage |
| generated for the `-h` argument. It's shown for `--help-all` as |
| documented in linkgit:gitcli[7]. |
| |
| * Use `!` to not make the corresponding negated long option available. |
| |
| The remainder of the line, after stripping the spaces, is used |
| as the help associated to the option. |
| |
| Blank lines are ignored, and lines that don't match this specification are used |
| as option group headers (start the line with a space to create such |
| lines on purpose). |
| |
| Example |
| ~~~~~~~ |
| |
| ------------ |
| OPTS_SPEC="\ |
| 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 |
| |
| An option group Header |
| C? option C with an optional argument" |
| |
| eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)" |
| ------------ |
| |
| SQ-QUOTE |
| -------- |
| |
| In `--sq-quote` mode, 'git rev-parse' echoes on the standard output a |
| single line suitable for `sh(1)` `eval`. This line is made by |
| normalizing the arguments following `--sq-quote`. Nothing other than |
| quoting the arguments is done. |
| |
| If you want command input to still be interpreted as usual by |
| 'git rev-parse' before the output is shell quoted, see the `--sq` |
| option. |
| |
| Example |
| ~~~~~~~ |
| |
| ------------ |
| $ cat >your-git-script.sh <<\EOF |
| #!/bin/sh |
| args=$(git rev-parse --sq-quote "$@") # quote user-supplied arguments |
| command="git frotz -n24 $args" # and use it inside a handcrafted |
| # command line |
| eval "$command" |
| EOF |
| |
| $ sh your-git-script.sh "a b'c" |
| ------------ |
| |
| EXAMPLES |
| -------- |
| |
| * Print the object name of the current commit: |
| + |
| ------------ |
| $ git rev-parse --verify HEAD |
| ------------ |
| |
| * Print the commit object name from the revision in the $REV shell variable: |
| + |
| ------------ |
| $ git rev-parse --verify $REV |
| ------------ |
| + |
| This will error out if $REV is empty or not a valid revision. |
| |
| * Same as above: |
| + |
| ------------ |
| $ git rev-parse --default master --verify $REV |
| ------------ |
| + |
| but if $REV is empty, the commit object name from master will be printed. |
| |
| GIT |
| --- |
| Part of the linkgit:git[1] suite |