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