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 248--shared-index-path:: 249 Show the path to the shared index file in split index mode, or 250 empty if not in split-index mode. 251 252Other Options 253~~~~~~~~~~~~~ 254 255--since=datestring:: 256--after=datestring:: 257 Parse the date string, and output the corresponding 258 --max-age= parameter for 'git rev-list'. 259 260--until=datestring:: 261--before=datestring:: 262 Parse the date string, and output the corresponding 263 --min-age= parameter for 'git rev-list'. 264 265<args>...:: 266 Flags and parameters to be parsed. 267 268 269include::revisions.txt[] 270 271PARSEOPT 272-------- 273 274In `--parseopt` mode, 'git rev-parse' helps massaging options to bring to shell 275scripts the same facilities C builtins have. It works as an option normalizer 276(e.g. splits single switches aggregate values), a bit like `getopt(1)` does. 277 278It takes on the standard input the specification of the options to parse and 279understand, and echoes on the standard output a string suitable for `sh(1)` `eval` 280to replace the arguments with normalized ones. In case of error, it outputs 281usage on the standard error stream, and exits with code 129. 282 283Note: Make sure you quote the result when passing it to `eval`. See 284below for an example. 285 286Input Format 287~~~~~~~~~~~~ 288 289'git rev-parse --parseopt' input format is fully text based. It has two parts, 290separated by a line that contains only `--`. The lines before the separator 291(should be one or more) are used for the usage. 292The lines after the separator describe the options. 293 294Each line of options has this format: 295 296------------ 297<opt-spec><flags>*<arg-hint>? SP+ help LF 298------------ 299 300`<opt-spec>`:: 301 its format is the short option character, then the long option name 302 separated by a comma. Both parts are not required, though at least one 303 is necessary. `h,help`, `dry-run` and `f` are all three correct 304 `<opt-spec>`. 305 306`<flags>`:: 307 `<flags>` are of `*`, `=`, `?` or `!`. 308 * Use `=` if the option takes an argument. 309 310 * Use `?` to mean that the option takes an optional argument. You 311 probably want to use the `--stuck-long` mode to be able to 312 unambiguously parse the optional argument. 313 314 * Use `*` to mean that this option should not be listed in the usage 315 generated for the `-h` argument. It's shown for `--help-all` as 316 documented in linkgit:gitcli[7]. 317 318 * Use `!` to not make the corresponding negated long option available. 319 320`<arg-hint>`:: 321 `<arg-hint>`, if specified, is used as a name of the argument in the 322 help output, for options that take arguments. `<arg-hint>` is 323 terminated by the first whitespace. It is customary to use a 324 dash to separate words in a multi-word argument hint. 325 326The remainder of the line, after stripping the spaces, is used 327as the help associated to the option. 328 329Blank lines are ignored, and lines that don't match this specification are used 330as option group headers (start the line with a space to create such 331lines on purpose). 332 333Example 334~~~~~~~ 335 336------------ 337OPTS_SPEC="\ 338some-command [options] <args>... 339 340some-command does foo and bar! 341-- 342h,help show the help 343 344foo some nifty option --foo 345bar= some cool option --bar with an argument 346baz=arg another cool option --baz with a named argument 347qux?path qux may take a path argument but has meaning by itself 348 349 An option group Header 350C? option C with an optional argument" 351 352eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)" 353------------ 354 355 356Usage text 357~~~~~~~~~~ 358 359When `"$@"` is `-h` or `--help` in the above example, the following 360usage text would be shown: 361 362------------ 363usage: some-command [options] <args>... 364 365 some-command does foo and bar! 366 367 -h, --help show the help 368 --foo some nifty option --foo 369 --bar ... some cool option --bar with an argument 370 --baz <arg> another cool option --baz with a named argument 371 --qux[=<path>] qux may take a path argument but has meaning by itself 372 373An option group Header 374 -C[...] option C with an optional argument 375------------ 376 377SQ-QUOTE 378-------- 379 380In `--sq-quote` mode, 'git rev-parse' echoes on the standard output a 381single line suitable for `sh(1)` `eval`. This line is made by 382normalizing the arguments following `--sq-quote`. Nothing other than 383quoting the arguments is done. 384 385If you want command input to still be interpreted as usual by 386'git rev-parse' before the output is shell quoted, see the `--sq` 387option. 388 389Example 390~~~~~~~ 391 392------------ 393$ cat >your-git-script.sh <<\EOF 394#!/bin/sh 395args=$(git rev-parse --sq-quote "$@") # quote user-supplied arguments 396command="git frotz -n24 $args" # and use it inside a handcrafted 397 # command line 398eval "$command" 399EOF 400 401$ sh your-git-script.sh "a b'c" 402------------ 403 404EXAMPLES 405-------- 406 407* Print the object name of the current commit: 408+ 409------------ 410$ git rev-parse --verify HEAD 411------------ 412 413* Print the commit object name from the revision in the $REV shell variable: 414+ 415------------ 416$ git rev-parse --verify $REV^{commit} 417------------ 418+ 419This will error out if $REV is empty or not a valid revision. 420 421* Similar to above: 422+ 423------------ 424$ git rev-parse --default master --verify $REV 425------------ 426+ 427but if $REV is empty, the commit object name from master will be printed. 428 429GIT 430--- 431Part of the linkgit:git[1] suite