| 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' [<options>] <arg>... |
| 13 | |
| 14 | DESCRIPTION |
| 15 | ----------- |
| 16 | |
| 17 | Many Git porcelainish commands take a 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'. The primary purpose of this command |
| 22 | is to allow calling programs to distinguish between them. There are |
| 23 | a few other operation modes that have nothing to do with the above |
| 24 | "help parse command line options". |
| 25 | |
| 26 | Unless otherwise specified, most of the options and operation modes |
| 27 | require you to run this command inside a git repository or a working |
| 28 | tree that is under the control of a git repository, and will give you |
| 29 | a fatal error otherwise. |
| 30 | |
| 31 | |
| 32 | OPTIONS |
| 33 | ------- |
| 34 | |
| 35 | Operation Modes |
| 36 | ~~~~~~~~~~~~~~~ |
| 37 | |
| 38 | Each of these options must appear first on the command line. |
| 39 | |
| 40 | --parseopt:: |
| 41 | Use 'git rev-parse' in option parsing mode (see PARSEOPT section below). |
| 42 | The command in this mode can be used outside a repository or |
| 43 | a working tree controlled by a repository. |
| 44 | |
| 45 | --sq-quote:: |
| 46 | Use 'git rev-parse' in shell quoting mode (see SQ-QUOTE |
| 47 | section below). In contrast to the `--sq` option below, this |
| 48 | mode only does quoting. Nothing else is done to command input. |
| 49 | The command in this mode can be used outside a repository or |
| 50 | a working tree controlled by a repository. |
| 51 | |
| 52 | Options for --parseopt |
| 53 | ~~~~~~~~~~~~~~~~~~~~~~ |
| 54 | |
| 55 | --keep-dashdash:: |
| 56 | Only meaningful in `--parseopt` mode. Tells the option parser to echo |
| 57 | out the first `--` met instead of skipping it. |
| 58 | |
| 59 | --stop-at-non-option:: |
| 60 | Only meaningful in `--parseopt` mode. Lets the option parser stop at |
| 61 | the first non-option argument. This can be used to parse sub-commands |
| 62 | that take options themselves. |
| 63 | |
| 64 | --stuck-long:: |
| 65 | Only meaningful in `--parseopt` mode. Output the options in their |
| 66 | long form if available, and with their arguments stuck. |
| 67 | |
| 68 | Options for Filtering |
| 69 | ~~~~~~~~~~~~~~~~~~~~~ |
| 70 | |
| 71 | --revs-only:: |
| 72 | Do not output flags and parameters not meant for |
| 73 | 'git rev-list' command. |
| 74 | |
| 75 | --no-revs:: |
| 76 | Do not output flags and parameters meant for |
| 77 | 'git rev-list' command. |
| 78 | |
| 79 | --flags:: |
| 80 | Do not output non-flag parameters. |
| 81 | |
| 82 | --no-flags:: |
| 83 | Do not output flag parameters. |
| 84 | |
| 85 | Options for Output |
| 86 | ~~~~~~~~~~~~~~~~~~ |
| 87 | |
| 88 | --default <arg>:: |
| 89 | If there is no parameter given by the user, use `<arg>` |
| 90 | instead. |
| 91 | |
| 92 | --prefix <arg>:: |
| 93 | Behave as if 'git rev-parse' was invoked from the `<arg>` |
| 94 | subdirectory of the working tree. Any relative filenames are |
| 95 | resolved as if they are prefixed by `<arg>` and will be printed |
| 96 | in that form. |
| 97 | + |
| 98 | This can be used to convert arguments to a command run in a subdirectory |
| 99 | so that they can still be used after moving to the top-level of the |
| 100 | repository. For example: |
| 101 | + |
| 102 | ---- |
| 103 | prefix=$(git rev-parse --show-prefix) |
| 104 | cd "$(git rev-parse --show-toplevel)" |
| 105 | # rev-parse provides the -- needed for 'set' |
| 106 | eval "set $(git rev-parse --sq --prefix "$prefix" -- "$@")" |
| 107 | ---- |
| 108 | |
| 109 | --verify:: |
| 110 | Verify that exactly one parameter is provided, and that it |
| 111 | can be turned into a raw 20-byte SHA-1 that can be used to |
| 112 | access the object database. If so, emit it to the standard |
| 113 | output; otherwise, error out. |
| 114 | + |
| 115 | If you want to make sure that the output actually names an object in |
| 116 | your object database and/or can be used as a specific type of object |
| 117 | you require, you can add the `^{type}` peeling operator to the parameter. |
| 118 | For example, `git rev-parse "$VAR^{commit}"` will make sure `$VAR` |
| 119 | names an existing object that is a commit-ish (i.e. a commit, or an |
| 120 | annotated tag that points at a commit). To make sure that `$VAR` |
| 121 | names an existing object of any type, `git rev-parse "$VAR^{object}"` |
| 122 | can be used. |
| 123 | + |
| 124 | Note that if you are verifying a name from an untrusted source, it is |
| 125 | wise to use `--end-of-options` so that the name argument is not mistaken |
| 126 | for another option. |
| 127 | |
| 128 | -q:: |
| 129 | --quiet:: |
| 130 | Only meaningful in `--verify` mode. Do not output an error |
| 131 | message if the first argument is not a valid object name; |
| 132 | instead exit with non-zero status silently. |
| 133 | SHA-1s for valid object names are printed to stdout on success. |
| 134 | |
| 135 | --sq:: |
| 136 | Usually the output is made one line per flag and |
| 137 | parameter. This option makes output a single line, |
| 138 | properly quoted for consumption by shell. Useful when |
| 139 | you expect your parameter to contain whitespaces and |
| 140 | newlines (e.g. when using pickaxe `-S` with |
| 141 | 'git diff-{asterisk}'). In contrast to the `--sq-quote` option, |
| 142 | the command input is still interpreted as usual. |
| 143 | |
| 144 | --short[=<length>]:: |
| 145 | Same as `--verify` but shortens the object name to a unique |
| 146 | prefix with at least `length` characters. The minimum length |
| 147 | is 4, the default is the effective value of the `core.abbrev` |
| 148 | configuration variable (see linkgit:git-config[1]). |
| 149 | |
| 150 | --not:: |
| 151 | When showing object names, prefix them with '{caret}' and |
| 152 | strip '{caret}' prefix from the object names that already have |
| 153 | one. |
| 154 | |
| 155 | --abbrev-ref[=(strict|loose)]:: |
| 156 | A non-ambiguous short name of the objects name. |
| 157 | The option core.warnAmbiguousRefs is used to select the strict |
| 158 | abbreviation mode. |
| 159 | |
| 160 | --symbolic:: |
| 161 | Usually the object names are output in SHA-1 form (with |
| 162 | possible '{caret}' prefix); this option makes them output in a |
| 163 | form as close to the original input as possible. |
| 164 | |
| 165 | --symbolic-full-name:: |
| 166 | This is similar to --symbolic, but it omits input that |
| 167 | are not refs (i.e. branch or tag names; or more |
| 168 | explicitly disambiguating "heads/master" form, when you |
| 169 | want to name the "master" branch when there is an |
| 170 | unfortunately named tag "master"), and shows them as full |
| 171 | refnames (e.g. "refs/heads/master"). |
| 172 | |
| 173 | --output-object-format=(sha1|sha256|storage):: |
| 174 | |
| 175 | Allow oids to be input from any object format that the current |
| 176 | repository supports. |
| 177 | + |
| 178 | Specifying "sha1" translates if necessary and returns a sha1 oid. |
| 179 | + |
| 180 | Specifying "sha256" translates if necessary and returns a sha256 oid. |
| 181 | + |
| 182 | Specifying "storage" translates if necessary and returns an oid in |
| 183 | encoded in the storage hash algorithm. |
| 184 | |
| 185 | Options for Objects |
| 186 | ~~~~~~~~~~~~~~~~~~~ |
| 187 | |
| 188 | --all:: |
| 189 | Show all refs found in `refs/`. |
| 190 | |
| 191 | --branches[=<pattern>]:: |
| 192 | --tags[=<pattern>]:: |
| 193 | --remotes[=<pattern>]:: |
| 194 | Show all branches, tags, or remote-tracking branches, |
| 195 | respectively (i.e., refs found in `refs/heads`, |
| 196 | `refs/tags`, or `refs/remotes`, respectively). |
| 197 | + |
| 198 | If a `pattern` is given, only refs matching the given shell glob are |
| 199 | shown. If the pattern does not contain a globbing character (`?`, |
| 200 | `*`, or `[`), it is turned into a prefix match by appending `/*`. |
| 201 | |
| 202 | --glob=<pattern>:: |
| 203 | Show all refs matching the shell glob pattern `pattern`. If |
| 204 | the pattern does not start with `refs/`, this is automatically |
| 205 | prepended. If the pattern does not contain a globbing |
| 206 | character (`?`, `*`, or `[`), it is turned into a prefix |
| 207 | match by appending `/*`. |
| 208 | |
| 209 | --exclude=<glob-pattern>:: |
| 210 | Do not include refs matching '<glob-pattern>' that the next `--all`, |
| 211 | `--branches`, `--tags`, `--remotes`, or `--glob` would otherwise |
| 212 | consider. Repetitions of this option accumulate exclusion patterns |
| 213 | up to the next `--all`, `--branches`, `--tags`, `--remotes`, or |
| 214 | `--glob` option (other options or arguments do not clear |
| 215 | accumulated patterns). |
| 216 | + |
| 217 | The patterns given should not begin with `refs/heads`, `refs/tags`, or |
| 218 | `refs/remotes` when applied to `--branches`, `--tags`, or `--remotes`, |
| 219 | respectively, and they must begin with `refs/` when applied to `--glob` |
| 220 | or `--all`. If a trailing '/{asterisk}' is intended, it must be given |
| 221 | explicitly. |
| 222 | |
| 223 | --exclude-hidden=(fetch|receive|uploadpack):: |
| 224 | Do not include refs that would be hidden by `git-fetch`, |
| 225 | `git-receive-pack` or `git-upload-pack` by consulting the appropriate |
| 226 | `fetch.hideRefs`, `receive.hideRefs` or `uploadpack.hideRefs` |
| 227 | configuration along with `transfer.hideRefs` (see |
| 228 | linkgit:git-config[1]). This option affects the next pseudo-ref option |
| 229 | `--all` or `--glob` and is cleared after processing them. |
| 230 | |
| 231 | --disambiguate=<prefix>:: |
| 232 | Show every object whose name begins with the given prefix. |
| 233 | The <prefix> must be at least 4 hexadecimal digits long to |
| 234 | avoid listing each and every object in the repository by |
| 235 | mistake. |
| 236 | |
| 237 | Options for Files |
| 238 | ~~~~~~~~~~~~~~~~~ |
| 239 | |
| 240 | --local-env-vars:: |
| 241 | List the GIT_* environment variables that are local to the |
| 242 | repository (e.g. GIT_DIR or GIT_WORK_TREE, but not GIT_EDITOR). |
| 243 | Only the names of the variables are listed, not their value, |
| 244 | even if they are set. |
| 245 | |
| 246 | --path-format=(absolute|relative):: |
| 247 | Controls the behavior of certain other options. If specified as absolute, the |
| 248 | paths printed by those options will be absolute and canonical. If specified as |
| 249 | relative, the paths will be relative to the current working directory if that |
| 250 | is possible. The default is option specific. |
| 251 | + |
| 252 | This option may be specified multiple times and affects only the arguments that |
| 253 | follow it on the command line, either to the end of the command line or the next |
| 254 | instance of this option. |
| 255 | |
| 256 | The following options are modified by `--path-format`: |
| 257 | |
| 258 | --git-dir:: |
| 259 | Show `$GIT_DIR` if defined. Otherwise show the path to |
| 260 | the .git directory. The path shown, when relative, is |
| 261 | relative to the current working directory. |
| 262 | + |
| 263 | If `$GIT_DIR` is not defined and the current directory |
| 264 | is not detected to lie in a Git repository or work tree |
| 265 | print a message to stderr and exit with nonzero status. |
| 266 | |
| 267 | --git-common-dir:: |
| 268 | Show `$GIT_COMMON_DIR` if defined, else `$GIT_DIR`. |
| 269 | |
| 270 | --resolve-git-dir <path>:: |
| 271 | Check if <path> is a valid repository or a gitfile that |
| 272 | points at a valid repository, and print the location of the |
| 273 | repository. If <path> is a gitfile then the resolved path |
| 274 | to the real repository is printed. |
| 275 | |
| 276 | --git-path <path>:: |
| 277 | Resolve "$GIT_DIR/<path>" and takes other path relocation |
| 278 | variables such as $GIT_OBJECT_DIRECTORY, |
| 279 | $GIT_INDEX_FILE... into account. For example, if |
| 280 | $GIT_OBJECT_DIRECTORY is set to /foo/bar then "git rev-parse |
| 281 | --git-path objects/abc" returns /foo/bar/abc. |
| 282 | |
| 283 | --show-toplevel:: |
| 284 | Show the (by default, absolute) path of the top-level directory |
| 285 | of the working tree. If there is no working tree, report an error. |
| 286 | |
| 287 | --show-superproject-working-tree:: |
| 288 | Show the absolute path of the root of the superproject's |
| 289 | working tree (if exists) that uses the current repository as |
| 290 | its submodule. Outputs nothing if the current repository is |
| 291 | not used as a submodule by any project. |
| 292 | |
| 293 | --shared-index-path:: |
| 294 | Show the path to the shared index file in split index mode, or |
| 295 | empty if not in split-index mode. |
| 296 | |
| 297 | The following options are unaffected by `--path-format`: |
| 298 | |
| 299 | --absolute-git-dir:: |
| 300 | Like `--git-dir`, but its output is always the canonicalized |
| 301 | absolute path. |
| 302 | |
| 303 | --is-inside-git-dir:: |
| 304 | When the current working directory is below the repository |
| 305 | directory print "true", otherwise "false". |
| 306 | |
| 307 | --is-inside-work-tree:: |
| 308 | When the current working directory is inside the work tree of the |
| 309 | repository print "true", otherwise "false". |
| 310 | |
| 311 | --is-bare-repository:: |
| 312 | When the repository is bare print "true", otherwise "false". |
| 313 | |
| 314 | --is-shallow-repository:: |
| 315 | When the repository is shallow print "true", otherwise "false". |
| 316 | |
| 317 | --show-cdup:: |
| 318 | When the command is invoked from a subdirectory, show the |
| 319 | path of the top-level directory relative to the current |
| 320 | directory (typically a sequence of "../", or an empty string). |
| 321 | |
| 322 | --show-prefix:: |
| 323 | When the command is invoked from a subdirectory, show the |
| 324 | path of the current directory relative to the top-level |
| 325 | directory. |
| 326 | |
| 327 | --show-object-format[=(storage|input|output|compat)]:: |
| 328 | Show the object format (hash algorithm) used for the repository for storage |
| 329 | inside the `.git` directory, input, output, or compatibility. For input, |
| 330 | multiple algorithms may be printed, space-separated. If `compat` is |
| 331 | requested and no compatibility algorithm is enabled, prints an empty line. If |
| 332 | not specified, the default is "storage". |
| 333 | |
| 334 | --show-ref-format:: |
| 335 | Show the reference storage format used for the repository. |
| 336 | |
| 337 | |
| 338 | Other Options |
| 339 | ~~~~~~~~~~~~~ |
| 340 | |
| 341 | --since=<datestring>:: |
| 342 | --after=<datestring>:: |
| 343 | Parse the date string, and output the corresponding |
| 344 | --max-age= parameter for 'git rev-list'. |
| 345 | |
| 346 | --until=<datestring>:: |
| 347 | --before=<datestring>:: |
| 348 | Parse the date string, and output the corresponding |
| 349 | --min-age= parameter for 'git rev-list'. |
| 350 | |
| 351 | <arg>...:: |
| 352 | Flags and parameters to be parsed. |
| 353 | |
| 354 | |
| 355 | include::revisions.adoc[] |
| 356 | |
| 357 | PARSEOPT |
| 358 | -------- |
| 359 | |
| 360 | In `--parseopt` mode, 'git rev-parse' helps massaging options to bring to shell |
| 361 | scripts the same facilities C builtins have. It works as an option normalizer |
| 362 | (e.g. splits single switches aggregate values), a bit like `getopt(1)` does. |
| 363 | |
| 364 | It takes on the standard input the specification of the options to parse and |
| 365 | understand, and echoes on the standard output a string suitable for `sh(1)` `eval` |
| 366 | to replace the arguments with normalized ones. In case of error, it outputs |
| 367 | usage on the standard error stream, and exits with code 129. |
| 368 | |
| 369 | Note: Make sure you quote the result when passing it to `eval`. See |
| 370 | below for an example. |
| 371 | |
| 372 | Input Format |
| 373 | ~~~~~~~~~~~~ |
| 374 | |
| 375 | 'git rev-parse --parseopt' input format is fully text based. It has two parts, |
| 376 | separated by a line that contains only `--`. The lines before the separator |
| 377 | (should be one or more) are used for the usage. |
| 378 | The lines after the separator describe the options. |
| 379 | |
| 380 | Each line of options has this format: |
| 381 | |
| 382 | ------------ |
| 383 | <opt-spec><flags>*<arg-hint>? SP+ help LF |
| 384 | ------------ |
| 385 | |
| 386 | `<opt-spec>`:: |
| 387 | its format is the short option character, then the long option name |
| 388 | separated by a comma. Both parts are not required, though at least one |
| 389 | is necessary. May not contain any of the `<flags>` characters. |
| 390 | `h,help`, `dry-run` and `f` are examples of correct `<opt-spec>`. |
| 391 | |
| 392 | `<flags>`:: |
| 393 | `<flags>` are of `*`, `=`, `?` or `!`. |
| 394 | * Use `=` if the option takes an argument. |
| 395 | |
| 396 | * Use `?` to mean that the option takes an optional argument. You |
| 397 | probably want to use the `--stuck-long` mode to be able to |
| 398 | unambiguously parse the optional argument. |
| 399 | |
| 400 | * Use `*` to mean that this option should not be listed in the usage |
| 401 | generated for the `-h` argument. It's shown for `--help-all` as |
| 402 | documented in linkgit:gitcli[7]. |
| 403 | |
| 404 | * Use `!` to not make the corresponding negated long option available. |
| 405 | |
| 406 | `<arg-hint>`:: |
| 407 | `<arg-hint>`, if specified, is used as a name of the argument in the |
| 408 | help output, for options that take arguments. `<arg-hint>` is |
| 409 | terminated by the first whitespace. It is customary to use a |
| 410 | dash to separate words in a multi-word argument hint. |
| 411 | |
| 412 | The remainder of the line, after stripping the spaces, is used |
| 413 | as the help associated with the option. |
| 414 | |
| 415 | Blank lines are ignored, and lines that don't match this specification are used |
| 416 | as option group headers (start the line with a space to create such |
| 417 | lines on purpose). |
| 418 | |
| 419 | Example |
| 420 | ~~~~~~~ |
| 421 | |
| 422 | ------------ |
| 423 | OPTS_SPEC="\ |
| 424 | some-command [<options>] <args>... |
| 425 | |
| 426 | some-command does foo and bar! |
| 427 | -- |
| 428 | h,help! show the help |
| 429 | |
| 430 | foo some nifty option --foo |
| 431 | bar= some cool option --bar with an argument |
| 432 | baz=arg another cool option --baz with a named argument |
| 433 | qux?path qux may take a path argument but has meaning by itself |
| 434 | |
| 435 | An option group Header |
| 436 | C? option C with an optional argument" |
| 437 | |
| 438 | eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)" |
| 439 | ------------ |
| 440 | |
| 441 | |
| 442 | Usage text |
| 443 | ~~~~~~~~~~ |
| 444 | |
| 445 | When `"$@"` is `-h` or `--help` in the above example, the following |
| 446 | usage text would be shown: |
| 447 | |
| 448 | ------------ |
| 449 | usage: some-command [<options>] <args>... |
| 450 | |
| 451 | some-command does foo and bar! |
| 452 | |
| 453 | -h, --help show the help |
| 454 | --[no-]foo some nifty option --foo |
| 455 | --[no-]bar ... some cool option --bar with an argument |
| 456 | --[no-]baz <arg> another cool option --baz with a named argument |
| 457 | --[no-]qux[=<path>] qux may take a path argument but has meaning by itself |
| 458 | |
| 459 | An option group Header |
| 460 | -C[...] option C with an optional argument |
| 461 | ------------ |
| 462 | |
| 463 | SQ-QUOTE |
| 464 | -------- |
| 465 | |
| 466 | In `--sq-quote` mode, 'git rev-parse' echoes on the standard output a |
| 467 | single line suitable for `sh(1)` `eval`. This line is made by |
| 468 | normalizing the arguments following `--sq-quote`. Nothing other than |
| 469 | quoting the arguments is done. |
| 470 | |
| 471 | If you want command input to still be interpreted as usual by |
| 472 | 'git rev-parse' before the output is shell quoted, see the `--sq` |
| 473 | option. |
| 474 | |
| 475 | Example |
| 476 | ~~~~~~~ |
| 477 | |
| 478 | ------------ |
| 479 | $ cat >your-git-script.sh <<\EOF |
| 480 | #!/bin/sh |
| 481 | args=$(git rev-parse --sq-quote "$@") # quote user-supplied arguments |
| 482 | command="git frotz -n24 $args" # and use it inside a handcrafted |
| 483 | # command line |
| 484 | eval "$command" |
| 485 | EOF |
| 486 | |
| 487 | $ sh your-git-script.sh "a b'c" |
| 488 | ------------ |
| 489 | |
| 490 | EXAMPLES |
| 491 | -------- |
| 492 | |
| 493 | * Print the object name of the current commit: |
| 494 | + |
| 495 | ------------ |
| 496 | $ git rev-parse --verify HEAD |
| 497 | ------------ |
| 498 | |
| 499 | * Print the commit object name from the revision in the $REV shell variable: |
| 500 | + |
| 501 | ------------ |
| 502 | $ git rev-parse --verify --end-of-options $REV^{commit} |
| 503 | ------------ |
| 504 | + |
| 505 | This will error out if $REV is empty or not a valid revision. |
| 506 | |
| 507 | * Similar to above: |
| 508 | + |
| 509 | ------------ |
| 510 | $ git rev-parse --default master --verify --end-of-options $REV |
| 511 | ------------ |
| 512 | + |
| 513 | but if $REV is empty, the commit object name from master will be printed. |
| 514 | |
| 515 | GIT |
| 516 | --- |
| 517 | Part of the linkgit:git[1] suite |