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 line 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 191Input Format 192~~~~~~~~~~~~ 193 194'git rev-parse --parseopt' input format is fully text based. It has two parts, 195separated by a line that contains only `--`. The lines before the separator 196(should be more than one) are used for the usage. 197The lines after the separator describe the options. 198 199Each line of options has this format: 200 201------------ 202<opt_spec><flags>* SP+ help LF 203------------ 204 205`<opt_spec>`:: 206 its format is the short option character, then the long option name 207 separated by a comma. Both parts are not required, though at least one 208 is necessary. `h,help`, `dry-run` and `f` are all three correct 209 `<opt_spec>`. 210 211`<flags>`:: 212 `<flags>` are of `*`, `=`, `?` or `!`. 213 * Use `=` if the option takes an argument. 214 215 * Use `?` to mean that the option is optional (though its use is discouraged). 216 217 * Use `*` to mean that this option should not be listed in the usage 218 generated for the `-h` argument. It's shown for `--help-all` as 219 documented in linkgit:gitcli[7]. 220 221 * Use `!` to not make the corresponding negated long option available. 222 223The remainder of the line, after stripping the spaces, is used 224as the help associated to the option. 225 226Blank lines are ignored, and lines that don't match this specification are used 227as option group headers (start the line with a space to create such 228lines on purpose). 229 230Example 231~~~~~~~ 232 233------------ 234OPTS_SPEC="\ 235some-command [options] <args>... 236 237some-command does foo and bar! 238-- 239h,help show the help 240 241foo some nifty option --foo 242bar= some cool option --bar with an argument 243 244 An option group Header 245C? option C with an optional argument" 246 247eval `echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?` 248------------ 249 250SQ-QUOTE 251-------- 252 253In `--sq-quote` mode, 'git rev-parse' echoes on the standard output a 254single line suitable for `sh(1)` `eval`. This line is made by 255normalizing the arguments following `--sq-quote`. Nothing other than 256quoting the arguments is done. 257 258If you want command input to still be interpreted as usual by 259'git rev-parse' before the output is shell quoted, see the `--sq` 260option. 261 262Example 263~~~~~~~ 264 265------------ 266$ cat >your-git-script.sh <<\EOF 267#!/bin/sh 268args=$(git rev-parse --sq-quote "$@") # quote user-supplied arguments 269command="git frotz -n24 $args" # and use it inside a handcrafted 270 # command line 271eval "$command" 272EOF 273 274$ sh your-git-script.sh "a b'c" 275------------ 276 277EXAMPLES 278-------- 279 280* Print the object name of the current commit: 281+ 282------------ 283$ git rev-parse --verify HEAD 284------------ 285 286* Print the commit object name from the revision in the $REV shell variable: 287+ 288------------ 289$ git rev-parse --verify $REV 290------------ 291+ 292This will error out if $REV is empty or not a valid revision. 293 294* Same as above: 295+ 296------------ 297$ git rev-parse --default master --verify $REV 298------------ 299+ 300but if $REV is empty, the commit object name from master will be printed. 301 302 303Author 304------ 305Written by Linus Torvalds <torvalds@osdl.org> . 306Junio C Hamano <gitster@pobox.com> and Pierre Habouzit <madcoder@debian.org> 307 308Documentation 309-------------- 310Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. 311 312GIT 313--- 314Part of the linkgit:git[1] suite