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 underlying `git-rev-list` command they use internally 19and flags and parameters for other commands they use as the 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-dash-dash:: 30 Only meaningful in `--parseopt` mode. Tells the option parser to echo 31 out the first `--` met instead of skipping it. 32 33--revs-only:: 34 Do not output flags and parameters not meant for 35 `git-rev-list` command. 36 37--no-revs:: 38 Do not output flags and parameters meant for 39 `git-rev-list` command. 40 41--flags:: 42 Do not output non-flag parameters. 43 44--no-flags:: 45 Do not output flag parameters. 46 47--default <arg>:: 48 If there is no parameter given by the user, use `<arg>` 49 instead. 50 51--verify:: 52 The parameter given must be usable as a single, valid 53 object name. Otherwise barf and abort. 54 55-q, --quiet:: 56 Only meaningful in `--verify` mode. Do not output an error 57 message if the first argument is not a valid object name; 58 instead exit with non-zero status silently. 59 60--sq:: 61 Usually the output is made one line per flag and 62 parameter. This option makes output a single line, 63 properly quoted for consumption by shell. Useful when 64 you expect your parameter to contain whitespaces and 65 newlines (e.g. when using pickaxe `-S` with 66 `git-diff-\*`). 67 68--not:: 69 When showing object names, prefix them with '{caret}' and 70 strip '{caret}' prefix from the object names that already have 71 one. 72 73--symbolic:: 74 Usually the object names are output in SHA1 form (with 75 possible '{caret}' prefix); this option makes them output in a 76 form as close to the original input as possible. 77 78--symbolic-full-name:: 79 This is similar to \--symbolic, but it omits input that 80 are not refs (i.e. branch or tag names; or more 81 explicitly disambiguating "heads/master" form, when you 82 want to name the "master" branch when there is an 83 unfortunately named tag "master"), and show them as full 84 refnames (e.g. "refs/heads/master"). 85 86--all:: 87 Show all refs found in `$GIT_DIR/refs`. 88 89--branches:: 90 Show branch refs found in `$GIT_DIR/refs/heads`. 91 92--tags:: 93 Show tag refs found in `$GIT_DIR/refs/tags`. 94 95--remotes:: 96 Show tag refs found in `$GIT_DIR/refs/remotes`. 97 98--show-prefix:: 99 When the command is invoked from a subdirectory, show the 100 path of the current directory relative to the top-level 101 directory. 102 103--show-cdup:: 104 When the command is invoked from a subdirectory, show the 105 path of the top-level directory relative to the current 106 directory (typically a sequence of "../", or an empty string). 107 108--git-dir:: 109 Show `$GIT_DIR` if defined else show the path to the .git directory. 110 111--is-inside-git-dir:: 112 When the current working directory is below the repository 113 directory print "true", otherwise "false". 114 115--is-inside-work-tree:: 116 When the current working directory is inside the work tree of the 117 repository print "true", otherwise "false". 118 119--is-bare-repository:: 120 When the repository is bare print "true", otherwise "false". 121 122--short, --short=number:: 123 Instead of outputting the full SHA1 values of object names try to 124 abbreviate them to a shorter unique name. When no length is specified 125 7 is used. The minimum length is 4. 126 127--since=datestring, --after=datestring:: 128 Parses the date string, and outputs corresponding 129 --max-age= parameter for git-rev-list command. 130 131--until=datestring, --before=datestring:: 132 Parses the date string, and outputs corresponding 133 --min-age= parameter for git-rev-list command. 134 135<args>...:: 136 Flags and parameters to be parsed. 137 138 139SPECIFYING REVISIONS 140-------------------- 141 142A revision parameter typically, but not necessarily, names a 143commit object. They use what is called an 'extended SHA1' 144syntax. Here are various ways to spell object names. The 145ones listed near the end of this list are to name trees and 146blobs contained in a commit. 147 148* The full SHA1 object name (40-byte hexadecimal string), or 149 a substring of such that is unique within the repository. 150 E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both 151 name the same commit object if there are no other object in 152 your repository whose object name starts with dae86e. 153 154* An output from `git-describe`; i.e. a closest tag, followed by a 155 dash, a `g`, and an abbreviated object name. 156 157* A symbolic ref name. E.g. 'master' typically means the commit 158 object referenced by $GIT_DIR/refs/heads/master. If you 159 happen to have both heads/master and tags/master, you can 160 explicitly say 'heads/master' to tell git which one you mean. 161 When ambiguous, a `<name>` is disambiguated by taking the 162 first match in the following rules: 163 164 . if `$GIT_DIR/<name>` exists, that is what you mean (this is usually 165 useful only for `HEAD`, `FETCH_HEAD` and `MERGE_HEAD`); 166 167 . otherwise, `$GIT_DIR/refs/<name>` if exists; 168 169 . otherwise, `$GIT_DIR/refs/tags/<name>` if exists; 170 171 . otherwise, `$GIT_DIR/refs/heads/<name>` if exists; 172 173 . otherwise, `$GIT_DIR/refs/remotes/<name>` if exists; 174 175 . otherwise, `$GIT_DIR/refs/remotes/<name>/HEAD` if exists. 176 177* A ref followed by the suffix '@' with a date specification 178 enclosed in a brace 179 pair (e.g. '\{yesterday\}', '\{1 month 2 weeks 3 days 1 hour 1 180 second ago\}' or '\{1979-02-26 18:30:00\}') to specify the value 181 of the ref at a prior point in time. This suffix may only be 182 used immediately following a ref name and the ref must have an 183 existing log ($GIT_DIR/logs/<ref>). 184 185* A ref followed by the suffix '@' with an ordinal specification 186 enclosed in a brace pair (e.g. '\{1\}', '\{15\}') to specify 187 the n-th prior value of that ref. For example 'master@\{1\}' 188 is the immediate prior value of 'master' while 'master@\{5\}' 189 is the 5th prior value of 'master'. This suffix may only be used 190 immediately following a ref name and the ref must have an existing 191 log ($GIT_DIR/logs/<ref>). 192 193* You can use the '@' construct with an empty ref part to get at a 194 reflog of the current branch. For example, if you are on the 195 branch 'blabla', then '@\{1\}' means the same as 'blabla@\{1\}'. 196 197* A suffix '{caret}' to a revision parameter means the first parent of 198 that commit object. '{caret}<n>' means the <n>th parent (i.e. 199 'rev{caret}' 200 is equivalent to 'rev{caret}1'). As a special rule, 201 'rev{caret}0' means the commit itself and is used when 'rev' is the 202 object name of a tag object that refers to a commit object. 203 204* A suffix '{tilde}<n>' to a revision parameter means the commit 205 object that is the <n>th generation grand-parent of the named 206 commit object, following only the first parent. I.e. rev~3 is 207 equivalent to rev{caret}{caret}{caret} which is equivalent to 208 rev{caret}1{caret}1{caret}1. See below for a illustration of 209 the usage of this form. 210 211* A suffix '{caret}' followed by an object type name enclosed in 212 brace pair (e.g. `v0.99.8{caret}\{commit\}`) means the object 213 could be a tag, and dereference the tag recursively until an 214 object of that type is found or the object cannot be 215 dereferenced anymore (in which case, barf). `rev{caret}0` 216 introduced earlier is a short-hand for `rev{caret}\{commit\}`. 217 218* A suffix '{caret}' followed by an empty brace pair 219 (e.g. `v0.99.8{caret}\{\}`) means the object could be a tag, 220 and dereference the tag recursively until a non-tag object is 221 found. 222 223* A colon, followed by a slash, followed by a text: this names 224 a commit whose commit message starts with the specified text. 225 This name returns the youngest matching commit which is 226 reachable from any ref. If the commit message starts with a 227 '!', you have to repeat that; the special sequence ':/!', 228 followed by something else than '!' is reserved for now. 229 230* A suffix ':' followed by a path; this names the blob or tree 231 at the given path in the tree-ish object named by the part 232 before the colon. 233 234* A colon, optionally followed by a stage number (0 to 3) and a 235 colon, followed by a path; this names a blob object in the 236 index at the given path. Missing stage number (and the colon 237 that follows it) names a stage 0 entry. During a merge, stage 238 1 is the common ancestor, stage 2 is the target branch's version 239 (typically the current branch), and stage 3 is the version from 240 the branch being merged. 241 242Here is an illustration, by Jon Loeliger. Both commit nodes B 243and C are parents of commit node A. Parent commits are ordered 244left-to-right. 245 246 G H I J 247 \ / \ / 248 D E F 249 \ | / \ 250 \ | / | 251 \|/ | 252 B C 253 \ / 254 \ / 255 A 256 257 A = = A^0 258 B = A^ = A^1 = A~1 259 C = A^2 = A^2 260 D = A^^ = A^1^1 = A~2 261 E = B^2 = A^^2 262 F = B^3 = A^^3 263 G = A^^^ = A^1^1^1 = A~3 264 H = D^2 = B^^2 = A^^^2 = A~2^2 265 I = F^ = B^3^ = A^^3^ 266 J = F^2 = B^3^2 = A^^3^2 267 268 269SPECIFYING RANGES 270----------------- 271 272History traversing commands such as `git-log` operate on a set 273of commits, not just a single commit. To these commands, 274specifying a single revision with the notation described in the 275previous section means the set of commits reachable from that 276commit, following the commit ancestry chain. 277 278To exclude commits reachable from a commit, a prefix `{caret}` 279notation is used. E.g. "`{caret}r1 r2`" means commits reachable 280from `r2` but exclude the ones reachable from `r1`. 281 282This set operation appears so often that there is a shorthand 283for it. "`r1..r2`" is equivalent to "`{caret}r1 r2`". It is 284the difference of two sets (subtract the set of commits 285reachable from `r1` from the set of commits reachable from 286`r2`). 287 288A similar notation "`r1\...r2`" is called symmetric difference 289of `r1` and `r2` and is defined as 290"`r1 r2 --not $(git-merge-base --all r1 r2)`". 291It is the set of commits that are reachable from either one of 292`r1` or `r2` but not from both. 293 294Two other shorthands for naming a set that is formed by a commit 295and its parent commits exists. `r1{caret}@` notation means all 296parents of `r1`. `r1{caret}!` includes commit `r1` but excludes 297its all parents. 298 299Here are a handful of examples: 300 301 D G H D 302 D F G H I J D F 303 ^G D H D 304 ^D B E I J F B 305 B...C G H D E B C 306 ^D B C E I J F B C 307 C^@ I J F 308 F^! D G H D F 309 310PARSEOPT 311-------- 312 313In `--parseopt` mode, `git-rev-parse` helps massaging options to bring to shell 314scripts the same facilities C builtins have. It works as an option normalizer 315(e.g. splits single switches aggregate values), a bit like `getopt(1)` does. 316 317It takes on the standard input the specification of the options to parse and 318understand, and echoes on the standard output a line suitable for `sh(1)` `eval` 319to replace the arguments with normalized ones. In case of error, it outputs 320usage on the standard error stream, and exits with code 129. 321 322Input Format 323~~~~~~~~~~~~ 324 325`git-rev-parse --parseopt` input format is fully text based. It has two parts, 326separated by a line that contains only `--`. The lines before the separator 327(should be more than one) are used for the usage. 328The lines after the separator describe the options. 329 330Each line of options has this format: 331 332------------ 333<opt_spec><flags>* SP+ help LF 334------------ 335 336`<opt_spec>`:: 337 its format is the short option character, then the long option name 338 separated by a comma. Both parts are not required, though at least one 339 is necessary. `h,help`, `dry-run` and `f` are all three correct 340 `<opt_spec>`. 341 342`<flags>`:: 343 `<flags>` are of `*`, `=`, `?` or `!`. 344 * Use `=` if the option takes an argument. 345 346 * Use `?` to mean that the option is optional (though its use is discouraged). 347 348 * Use `*` to mean that this option should not be listed in the usage 349 generated for the `-h` argument. It's shown for `--help-all` as 350 documented in linkgit:gitcli[7]. 351 352 * Use `!` to not make the corresponding negated long option available. 353 354The remainder of the line, after stripping the spaces, is used 355as the help associated to the option. 356 357Blank lines are ignored, and lines that don't match this specification are used 358as option group headers (start the line with a space to create such 359lines on purpose). 360 361Example 362~~~~~~~ 363 364------------ 365OPTS_SPEC="\ 366some-command [options] <args>... 367 368some-command does foo and bar! 369-- 370h,help show the help 371 372foo some nifty option --foo 373bar= some cool option --bar with an argument 374 375 An option group Header 376C? option C with an optional argument" 377 378eval `echo "$OPTS_SPEC" | git-rev-parse --parseopt -- "$@" || echo exit $?` 379------------ 380 381 382Author 383------ 384Written by Linus Torvalds <torvalds@osdl.org> . 385Junio C Hamano <junkio@cox.net> and Pierre Habouzit <madcoder@debian.org> 386 387Documentation 388-------------- 389Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. 390 391GIT 392--- 393Part of the linkgit:git[7] suite