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