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