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