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