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 SHA-1 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 SHA-1 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 repository or a gitfile that 202 points at a valid repository, and print the location of the 203 repository. If <path> is a gitfile then the resolved path 204 to the real repository is printed. 205 206 207include::revisions.txt[] 208 209PARSEOPT 210-------- 211 212In `--parseopt` mode, 'git rev-parse' helps massaging options to bring to shell 213scripts the same facilities C builtins have. It works as an option normalizer 214(e.g. splits single switches aggregate values), a bit like `getopt(1)` does. 215 216It takes on the standard input the specification of the options to parse and 217understand, and echoes on the standard output a string suitable for `sh(1)` `eval` 218to replace the arguments with normalized ones. In case of error, it outputs 219usage on the standard error stream, and exits with code 129. 220 221Note: Make sure you quote the result when passing it to `eval`. See 222below for an example. 223 224Input Format 225~~~~~~~~~~~~ 226 227'git rev-parse --parseopt' input format is fully text based. It has two parts, 228separated by a line that contains only `--`. The lines before the separator 229(should be more than one) are used for the usage. 230The lines after the separator describe the options. 231 232Each line of options has this format: 233 234------------ 235<opt_spec><flags>* SP+ help LF 236------------ 237 238`<opt_spec>`:: 239 its format is the short option character, then the long option name 240 separated by a comma. Both parts are not required, though at least one 241 is necessary. `h,help`, `dry-run` and `f` are all three correct 242 `<opt_spec>`. 243 244`<flags>`:: 245 `<flags>` are of `*`, `=`, `?` or `!`. 246 * Use `=` if the option takes an argument. 247 248 * Use `?` to mean that the option is optional (though its use is discouraged). 249 250 * Use `*` to mean that this option should not be listed in the usage 251 generated for the `-h` argument. It's shown for `--help-all` as 252 documented in linkgit:gitcli[7]. 253 254 * Use `!` to not make the corresponding negated long option available. 255 256The remainder of the line, after stripping the spaces, is used 257as the help associated to the option. 258 259Blank lines are ignored, and lines that don't match this specification are used 260as option group headers (start the line with a space to create such 261lines on purpose). 262 263Example 264~~~~~~~ 265 266------------ 267OPTS_SPEC="\ 268some-command [options] <args>... 269 270some-command does foo and bar! 271-- 272h,help show the help 273 274foo some nifty option --foo 275bar= some cool option --bar with an argument 276 277 An option group Header 278C? option C with an optional argument" 279 280eval "$(echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?)" 281------------ 282 283SQ-QUOTE 284-------- 285 286In `--sq-quote` mode, 'git rev-parse' echoes on the standard output a 287single line suitable for `sh(1)` `eval`. This line is made by 288normalizing the arguments following `--sq-quote`. Nothing other than 289quoting the arguments is done. 290 291If you want command input to still be interpreted as usual by 292'git rev-parse' before the output is shell quoted, see the `--sq` 293option. 294 295Example 296~~~~~~~ 297 298------------ 299$ cat >your-git-script.sh <<\EOF 300#!/bin/sh 301args=$(git rev-parse --sq-quote "$@") # quote user-supplied arguments 302command="git frotz -n24 $args" # and use it inside a handcrafted 303 # command line 304eval "$command" 305EOF 306 307$ sh your-git-script.sh "a b'c" 308------------ 309 310EXAMPLES 311-------- 312 313* Print the object name of the current commit: 314+ 315------------ 316$ git rev-parse --verify HEAD 317------------ 318 319* Print the commit object name from the revision in the $REV shell variable: 320+ 321------------ 322$ git rev-parse --verify $REV^{commit} 323------------ 324+ 325This will error out if $REV is empty or not a valid revision. 326 327* Similar to above: 328+ 329------------ 330$ git rev-parse --default master --verify $REV 331------------ 332+ 333but if $REV is empty, the commit object name from master will be printed. 334 335GIT 336--- 337Part of the linkgit:git[1] suite