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 more than one) 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>* 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 316The remainder of the line, after stripping the spaces, is used 317as the help associated to the option. 318 319Blank lines are ignored, and lines that don't match this specification are used 320as option group headers (start the line with a space to create such 321lines on purpose). 322 323Example 324~~~~~~~ 325 326------------ 327OPTS_SPEC="\ 328some-command [options] <args>... 329 330some-command does foo and bar! 331-- 332h,help show the help 333 334foo some nifty option --foo 335bar= some cool option --bar with an argument 336 337 An option group Header 338C? option C with an optional argument" 339 340eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)" 341------------ 342 343SQ-QUOTE 344-------- 345 346In `--sq-quote` mode, 'git rev-parse' echoes on the standard output a 347single line suitable for `sh(1)` `eval`. This line is made by 348normalizing the arguments following `--sq-quote`. Nothing other than 349quoting the arguments is done. 350 351If you want command input to still be interpreted as usual by 352'git rev-parse' before the output is shell quoted, see the `--sq` 353option. 354 355Example 356~~~~~~~ 357 358------------ 359$ cat >your-git-script.sh <<\EOF 360#!/bin/sh 361args=$(git rev-parse --sq-quote "$@") # quote user-supplied arguments 362command="git frotz -n24 $args" # and use it inside a handcrafted 363 # command line 364eval "$command" 365EOF 366 367$ sh your-git-script.sh "a b'c" 368------------ 369 370EXAMPLES 371-------- 372 373* Print the object name of the current commit: 374+ 375------------ 376$ git rev-parse --verify HEAD 377------------ 378 379* Print the commit object name from the revision in the $REV shell variable: 380+ 381------------ 382$ git rev-parse --verify $REV^{commit} 383------------ 384+ 385This will error out if $REV is empty or not a valid revision. 386 387* Similar to above: 388+ 389------------ 390$ git rev-parse --default master --verify $REV 391------------ 392+ 393but if $REV is empty, the commit object name from master will be printed. 394 395GIT 396--- 397Part of the linkgit:git[1] suite