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