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