Documentation/git-rev-parse.txt

   1 git-rev-parse(1)
   2 ================
   3
   4 NAME
   5 ----
   6 git-rev-parse - Pick out and massage parameters
   7
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 'git rev-parse' [ --option ] <args>...
  13
  14 DESCRIPTION
  15 -----------
  16
  17 Many Git porcelainish commands take mixture of flags
  18 (i.e. parameters that begin with a dash '-') and parameters
  19 meant for the underlying 'git rev-list' command they use internally
  20 and flags and parameters for the other commands they use
  21 downstream of 'git rev-list'.  This command is used to
  22 distinguish between them.
  23
  24
  25 OPTIONS
  26 -------
  27 --parseopt::
  28         Use 'git rev-parse' in option parsing mode (see PARSEOPT section below).
  29
  30 --keep-dashdash::
  31         Only meaningful in `--parseopt` mode. Tells the option parser to echo
  32         out the first `--` met instead of skipping it.
  33
  34 --stop-at-non-option::
  35         Only meaningful in `--parseopt` mode.  Lets the option parser stop at
  36         the first non-option argument.  This can be used to parse sub-commands
  37         that take options themselves.
  38
  39 --sq-quote::
  40         Use 'git rev-parse' in shell quoting mode (see SQ-QUOTE
  41         section below). In contrast to the `--sq` option below, this
  42         mode does only quoting. Nothing else is done to command input.
  43
  44 --revs-only::
  45         Do not output flags and parameters not meant for
  46         'git rev-list' command.
  47
  48 --no-revs::
  49         Do not output flags and parameters meant for
  50         'git rev-list' command.
  51
  52 --flags::
  53         Do not output non-flag parameters.
  54
  55 --no-flags::
  56         Do not output flag parameters.
  57
  58 --default <arg>::
  59         If there is no parameter given by the user, use `<arg>`
  60         instead.
  61
  62 --verify::
  63         Verify that exactly one parameter is provided, and that it
  64         can be turned into a raw 20-byte SHA-1 that can be used to
  65         access the object database. If so, emit it to the standard
  66         output; otherwise, error out.
  67 +
  68 If you want to make sure that the output actually names an object in
  69 your object database and/or can be used as a specific type of object
  70 you require, you can add "^{type}" peeling operator to the parmeter.
  71 For example, `git rev-parse "$VAR^{commit}"` will make sure `$VAR`
  72 names an existing object that is a commit-ish (i.e. a commit, or an
  73 annotated tag that points at a commit).  To make sure that `$VAR`
  74 names an existing object of any type, `git rev-parse "$VAR^{object}"`
  75 can be used.
  76
  77 -q::
  78 --quiet::
  79         Only meaningful in `--verify` mode. Do not output an error
  80         message if the first argument is not a valid object name;
  81         instead exit with non-zero status silently.
  82
  83 --sq::
  84         Usually the output is made one line per flag and
  85         parameter.  This option makes output a single line,
  86         properly quoted for consumption by shell.  Useful when
  87         you expect your parameter to contain whitespaces and
  88         newlines (e.g. when using pickaxe `-S` with
  89         'git diff-{asterisk}'). In contrast to the `--sq-quote` option,
  90         the command input is still interpreted as usual.
  91
  92 --not::
  93         When showing object names, prefix them with '{caret}' and
  94         strip '{caret}' prefix from the object names that already have
  95         one.
  96
  97 --symbolic::
  98         Usually the object names are output in SHA-1 form (with
  99         possible '{caret}' prefix); this option makes them output in a
 100         form as close to the original input as possible.
 101
 102 --symbolic-full-name::
 103         This is similar to \--symbolic, but it omits input that
 104         are not refs (i.e. branch or tag names; or more
 105         explicitly disambiguating "heads/master" form, when you
 106         want to name the "master" branch when there is an
 107         unfortunately named tag "master"), and show them as full
 108         refnames (e.g. "refs/heads/master").
 109
 110 --abbrev-ref[=(strict|loose)]::
 111         A non-ambiguous short name of the objects name.
 112         The option core.warnAmbiguousRefs is used to select the strict
 113         abbreviation mode.
 114
 115 --disambiguate=<prefix>::
 116         Show every object whose name begins with the given prefix.
 117         The <prefix> must be at least 4 hexadecimal digits long to
 118         avoid listing each and every object in the repository by
 119         mistake.
 120
 121 --all::
 122         Show all refs found in `refs/`.
 123
 124 --branches[=pattern]::
 125 --tags[=pattern]::
 126 --remotes[=pattern]::
 127         Show all branches, tags, or remote-tracking branches,
 128         respectively (i.e., refs found in `refs/heads`,
 129         `refs/tags`, or `refs/remotes`, respectively).
 130 +
 131 If a `pattern` is given, only refs matching the given shell glob are
 132 shown.  If the pattern does not contain a globbing character (`?`,
 133 `*`, or `[`), it is turned into a prefix match by appending `/*`.
 134
 135 --glob=pattern::
 136         Show all refs matching the shell glob pattern `pattern`. If
 137         the pattern does not start with `refs/`, this is automatically
 138         prepended.  If the pattern does not contain a globbing
 139         character (`?`, `*`, or `[`), it is turned into a prefix
 140         match by appending `/*`.
 141
 142 --show-toplevel::
 143         Show the absolute path of the top-level directory.
 144
 145 --show-prefix::
 146         When the command is invoked from a subdirectory, show the
 147         path of the current directory relative to the top-level
 148         directory.
 149
 150 --show-cdup::
 151         When the command is invoked from a subdirectory, show the
 152         path of the top-level directory relative to the current
 153         directory (typically a sequence of "../", or an empty string).
 154
 155 --git-dir::
 156         Show `$GIT_DIR` if defined. Otherwise show the path to
 157         the .git directory. The path shown, when relative, is
 158         relative to the current working directory.
 159 +
 160 If `$GIT_DIR` is not defined and the current directory
 161 is not detected to lie in a Git repository or work tree
 162 print a message to stderr and exit with nonzero status.
 163
 164 --is-inside-git-dir::
 165         When the current working directory is below the repository
 166         directory print "true", otherwise "false".
 167
 168 --is-inside-work-tree::
 169         When the current working directory is inside the work tree of the
 170         repository print "true", otherwise "false".
 171
 172 --is-bare-repository::
 173         When the repository is bare print "true", otherwise "false".
 174
 175 --local-env-vars::
 176         List the GIT_* environment variables that are local to the
 177         repository (e.g. GIT_DIR or GIT_WORK_TREE, but not GIT_EDITOR).
 178         Only the names of the variables are listed, not their value,
 179         even if they are set.
 180
 181 --short::
 182 --short=number::
 183         Instead of outputting the full SHA-1 values of object names try to
 184         abbreviate them to a shorter unique name. When no length is specified
 185         7 is used. The minimum length is 4.
 186
 187 --since=datestring::
 188 --after=datestring::
 189         Parse the date string, and output the corresponding
 190         --max-age= parameter for 'git rev-list'.
 191
 192 --until=datestring::
 193 --before=datestring::
 194         Parse the date string, and output the corresponding
 195         --min-age= parameter for 'git rev-list'.
 196
 197 <args>...::
 198         Flags and parameters to be parsed.
 199
 200 --resolve-git-dir <path>::
 201         Check if <path> is a valid repository or a gitfile that
 202         points at a valid repository, and print the location of the
 203         repository.  If <path> is a gitfile then the resolved path
 204         to the real repository is printed.
 205
 206
 207 include::revisions.txt[]
 208
 209 PARSEOPT
 210 --------
 211
 212 In `--parseopt` mode, 'git rev-parse' helps massaging options to bring to shell
 213 scripts the same facilities C builtins have. It works as an option normalizer
 214 (e.g. splits single switches aggregate values), a bit like `getopt(1)` does.
 215
 216 It takes on the standard input the specification of the options to parse and
 217 understand, and echoes on the standard output a string suitable for `sh(1)` `eval`
 218 to replace the arguments with normalized ones.  In case of error, it outputs
 219 usage on the standard error stream, and exits with code 129.
 220
 221 Note: Make sure you quote the result when passing it to `eval`.  See
 222 below for an example.
 223
 224 Input Format
 225 ~~~~~~~~~~~~
 226
 227 'git rev-parse --parseopt' input format is fully text based. It has two parts,
 228 separated by a line that contains only `--`. The lines before the separator
 229 (should be more than one) are used for the usage.
 230 The lines after the separator describe the options.
 231
 232 Each line of options has this format:
 233
 234 ------------
 235 <opt_spec><flags>* SP+ help LF
 236 ------------
 237
 238 `<opt_spec>`::
 239         its format is the short option character, then the long option name
 240         separated by a comma. Both parts are not required, though at least one
 241         is necessary. `h,help`, `dry-run` and `f` are all three correct
 242         `<opt_spec>`.
 243
 244 `<flags>`::
 245         `<flags>` are of `*`, `=`, `?` or `!`.
 246         * Use `=` if the option takes an argument.
 247
 248         * Use `?` to mean that the option is optional (though its use is discouraged).
 249
 250         * Use `*` to mean that this option should not be listed in the usage
 251           generated for the `-h` argument. It's shown for `--help-all` as
 252           documented in linkgit:gitcli[7].
 253
 254         * Use `!` to not make the corresponding negated long option available.
 255
 256 The remainder of the line, after stripping the spaces, is used
 257 as the help associated to the option.
 258
 259 Blank lines are ignored, and lines that don't match this specification are used
 260 as option group headers (start the line with a space to create such
 261 lines on purpose).
 262
 263 Example
 264 ~~~~~~~
 265
 266 ------------
 267 OPTS_SPEC="\
 268 some-command [options] <args>...
 269
 270 some-command does foo and bar!
 271 --
 272 h,help    show the help
 273
 274 foo       some nifty option --foo
 275 bar=      some cool option --bar with an argument
 276
 277   An option group Header
 278 C?        option C with an optional argument"
 279
 280 eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)"
 281 ------------
 282
 283 SQ-QUOTE
 284 --------
 285
 286 In `--sq-quote` mode, 'git rev-parse' echoes on the standard output a
 287 single line suitable for `sh(1)` `eval`. This line is made by
 288 normalizing the arguments following `--sq-quote`. Nothing other than
 289 quoting the arguments is done.
 290
 291 If you want command input to still be interpreted as usual by
 292 'git rev-parse' before the output is shell quoted, see the `--sq`
 293 option.
 294
 295 Example
 296 ~~~~~~~
 297
 298 ------------
 299 $ cat >your-git-script.sh <<\EOF
 300 #!/bin/sh
 301 args=$(git rev-parse --sq-quote "$@")   # quote user-supplied arguments
 302 command="git frotz -n24 $args"          # and use it inside a handcrafted
 303                                         # command line
 304 eval "$command"
 305 EOF
 306
 307 $ sh your-git-script.sh "a b'c"
 308 ------------
 309
 310 EXAMPLES
 311 --------
 312
 313 * Print the object name of the current commit:
 314 +
 315 ------------
 316 $ git rev-parse --verify HEAD
 317 ------------
 318
 319 * Print the commit object name from the revision in the $REV shell variable:
 320 +
 321 ------------
 322 $ git rev-parse --verify $REV^{commit}
 323 ------------
 324 +
 325 This will error out if $REV is empty or not a valid revision.
 326
 327 * Similar to above:
 328 +
 329 ------------
 330 $ git rev-parse --default master --verify $REV
 331 ------------
 332 +
 333 but if $REV is empty, the commit object name from master will be printed.
 334
 335 GIT
 336 ---
 337 Part of the linkgit:git[1] suite