Documentation/git-rev-parse.txt

   1 git-rev-parse(1)
   2 ================
   3
   4 NAME
   5 ----
   6 git-rev-parse - Pick out and massage parameters
   7
   8
   9 SYNOPSIS
  10 --------
  11 'git rev-parse' [ --option ] <args>...
  12
  13 DESCRIPTION
  14 -----------
  15
  16 Many git porcelainish commands take mixture of flags
  17 (i.e. parameters that begin with a dash '-') and parameters
  18 meant for the underlying 'git rev-list' command they use internally
  19 and flags and parameters for the other commands they use
  20 downstream of 'git rev-list'.  This command is used to
  21 distinguish between them.
  22
  23
  24 OPTIONS
  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 +
 113 If a `pattern` is given, only refs matching the given shell glob are
 114 shown.  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 --short::
 152 --short=number::
 153         Instead of outputting the full SHA1 values of object names try to
 154         abbreviate them to a shorter unique name. When no length is specified
 155         7 is used. The minimum length is 4.
 156
 157 --since=datestring::
 158 --after=datestring::
 159         Parse the date string, and output the corresponding
 160         --max-age= parameter for 'git rev-list'.
 161
 162 --until=datestring::
 163 --before=datestring::
 164         Parse the date string, and output the corresponding
 165         --min-age= parameter for 'git rev-list'.
 166
 167 <args>...::
 168         Flags and parameters to be parsed.
 169
 170
 171 SPECIFYING REVISIONS
 172 --------------------
 173
 174 A revision parameter typically, but not necessarily, names a
 175 commit object.  They use what is called an 'extended SHA1'
 176 syntax.  Here are various ways to spell object names.  The
 177 ones listed near the end of this list are to name trees and
 178 blobs contained in a commit.
 179
 180 * The full SHA1 object name (40-byte hexadecimal string), or
 181   a substring of such that is unique within the repository.
 182   E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both
 183   name the same commit object if there are no other object in
 184   your repository whose object name starts with dae86e.
 185
 186 * An output from 'git describe'; i.e. a closest tag, optionally
 187   followed by a dash and a number of commits, followed by a dash, a
 188   `g`, and an abbreviated object name.
 189
 190 * A symbolic ref name.  E.g. 'master' typically means the commit
 191   object referenced by refs/heads/master.  If you
 192   happen to have both heads/master and tags/master, you can
 193   explicitly say 'heads/master' to tell git which one you mean.
 194   When ambiguous, a `<name>` is disambiguated by taking the
 195   first match in the following rules:
 196
 197   . if `$GIT_DIR/<name>` exists, that is what you mean (this is usually
 198     useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD` and `MERGE_HEAD`);
 199
 200   . otherwise, `refs/<name>` if exists;
 201
 202   . otherwise, `refs/tags/<name>` if exists;
 203
 204   . otherwise, `refs/heads/<name>` if exists;
 205
 206   . otherwise, `refs/remotes/<name>` if exists;
 207
 208   . otherwise, `refs/remotes/<name>/HEAD` if exists.
 209 +
 210 HEAD names the commit your changes in the working tree is based on.
 211 FETCH_HEAD records the branch you fetched from a remote repository
 212 with your last 'git fetch' invocation.
 213 ORIG_HEAD is created by commands that moves your HEAD in a drastic
 214 way, to record the position of the HEAD before their operation, so that
 215 you can change the tip of the branch back to the state before you ran
 216 them easily.
 217 MERGE_HEAD records the commit(s) you are merging into your branch
 218 when you run 'git merge'.
 219 +
 220 Note that any of the `refs/*` cases above may come either from
 221 the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.
 222
 223 * A ref followed by the suffix '@' with a date specification
 224   enclosed in a brace
 225   pair (e.g. '\{yesterday\}', '\{1 month 2 weeks 3 days 1 hour 1
 226   second ago\}' or '\{1979-02-26 18:30:00\}') to specify the value
 227   of the ref at a prior point in time.  This suffix may only be
 228   used immediately following a ref name and the ref must have an
 229   existing log ($GIT_DIR/logs/<ref>). Note that this looks up the state
 230   of your *local* ref at a given time; e.g., what was in your local
 231   `master` branch last week. If you want to look at commits made during
 232   certain times, see `--since` and `--until`.
 233
 234 * A ref followed by the suffix '@' with an ordinal specification
 235   enclosed in a brace pair (e.g. '\{1\}', '\{15\}') to specify
 236   the n-th prior value of that ref.  For example 'master@\{1\}'
 237   is the immediate prior value of 'master' while 'master@\{5\}'
 238   is the 5th prior value of 'master'. This suffix may only be used
 239   immediately following a ref name and the ref must have an existing
 240   log ($GIT_DIR/logs/<ref>).
 241
 242 * You can use the '@' construct with an empty ref part to get at a
 243   reflog of the current branch. For example, if you are on the
 244   branch 'blabla', then '@\{1\}' means the same as 'blabla@\{1\}'.
 245
 246 * The special construct '@\{-<n>\}' means the <n>th branch checked out
 247   before the current one.
 248
 249 * The suffix '@\{upstream\}' to a ref (short form 'ref@\{u\}') refers to
 250   the branch the ref is set to build on top of.  Missing ref defaults
 251   to the current branch.
 252
 253 * A suffix '{caret}' to a revision parameter means the first parent of
 254   that commit object.  '{caret}<n>' means the <n>th parent (i.e.
 255   'rev{caret}'
 256   is equivalent to 'rev{caret}1').  As a special rule,
 257   'rev{caret}0' means the commit itself and is used when 'rev' is the
 258   object name of a tag object that refers to a commit object.
 259
 260 * A suffix '{tilde}<n>' to a revision parameter means the commit
 261   object that is the <n>th generation grand-parent of the named
 262   commit object, following only the first parent.  I.e. rev~3 is
 263   equivalent to rev{caret}{caret}{caret} which is equivalent to
 264   rev{caret}1{caret}1{caret}1.  See below for a illustration of
 265   the usage of this form.
 266
 267 * A suffix '{caret}' followed by an object type name enclosed in
 268   brace pair (e.g. `v0.99.8{caret}\{commit\}`) means the object
 269   could be a tag, and dereference the tag recursively until an
 270   object of that type is found or the object cannot be
 271   dereferenced anymore (in which case, barf).  `rev{caret}0`
 272   introduced earlier is a short-hand for `rev{caret}\{commit\}`.
 273
 274 * A suffix '{caret}' followed by an empty brace pair
 275   (e.g. `v0.99.8{caret}\{\}`) means the object could be a tag,
 276   and dereference the tag recursively until a non-tag object is
 277   found.
 278
 279 * A colon, followed by a slash, followed by a text: this names
 280   a commit whose commit message starts with the specified text.
 281   This name returns the youngest matching commit which is
 282   reachable from any ref.  If the commit message starts with a
 283   '!', you have to repeat that;  the special sequence ':/!',
 284   followed by something else than '!' is reserved for now.
 285
 286 * A suffix ':' followed by a path; this names the blob or tree
 287   at the given path in the tree-ish object named by the part
 288   before the colon.
 289
 290 * A colon, optionally followed by a stage number (0 to 3) and a
 291   colon, followed by a path; this names a blob object in the
 292   index at the given path.  Missing stage number (and the colon
 293   that follows it) names a stage 0 entry. During a merge, stage
 294   1 is the common ancestor, stage 2 is the target branch's version
 295   (typically the current branch), and stage 3 is the version from
 296   the branch being merged.
 297
 298 Here is an illustration, by Jon Loeliger.  Both commit nodes B
 299 and C are parents of commit node A.  Parent commits are ordered
 300 left-to-right.
 301
 302 ........................................
 303 G   H   I   J
 304  \ /     \ /
 305   D   E   F
 306    \  |  / \
 307     \ | /   |
 308      \|/    |
 309       B     C
 310        \   /
 311         \ /
 312          A
 313 ........................................
 314
 315     A =      = A^0
 316     B = A^   = A^1     = A~1
 317     C = A^2  = A^2
 318     D = A^^  = A^1^1   = A~2
 319     E = B^2  = A^^2
 320     F = B^3  = A^^3
 321     G = A^^^ = A^1^1^1 = A~3
 322     H = D^2  = B^^2    = A^^^2  = A~2^2
 323     I = F^   = B^3^    = A^^3^
 324     J = F^2  = B^3^2   = A^^3^2
 325
 326
 327 SPECIFYING RANGES
 328 -----------------
 329
 330 History traversing commands such as 'git log' operate on a set
 331 of commits, not just a single commit.  To these commands,
 332 specifying a single revision with the notation described in the
 333 previous section means the set of commits reachable from that
 334 commit, following the commit ancestry chain.
 335
 336 To exclude commits reachable from a commit, a prefix `{caret}`
 337 notation is used.  E.g. `{caret}r1 r2` means commits reachable
 338 from `r2` but exclude the ones reachable from `r1`.
 339
 340 This set operation appears so often that there is a shorthand
 341 for it.  When you have two commits `r1` and `r2` (named according
 342 to the syntax explained in SPECIFYING REVISIONS above), you can ask
 343 for commits that are reachable from r2 excluding those that are reachable
 344 from r1 by `{caret}r1 r2` and it can be written as `r1..r2`.
 345
 346 A similar notation `r1\...r2` is called symmetric difference
 347 of `r1` and `r2` and is defined as
 348 `r1 r2 --not $(git merge-base --all r1 r2)`.
 349 It is the set of commits that are reachable from either one of
 350 `r1` or `r2` but not from both.
 351
 352 Two other shorthands for naming a set that is formed by a commit
 353 and its parent commits exist.  The `r1{caret}@` notation means all
 354 parents of `r1`.  `r1{caret}!` includes commit `r1` but excludes
 355 all of its parents.
 356
 357 Here are a handful of examples:
 358
 359    D                G H D
 360    D F              G H I J D F
 361    ^G D             H D
 362    ^D B             E I J F B
 363    B...C            G H D E B C
 364    ^D B C           E I J F B C
 365    C^@              I J F
 366    F^! D            G H D F
 367
 368 PARSEOPT
 369 --------
 370
 371 In `--parseopt` mode, 'git rev-parse' helps massaging options to bring to shell
 372 scripts the same facilities C builtins have. It works as an option normalizer
 373 (e.g. splits single switches aggregate values), a bit like `getopt(1)` does.
 374
 375 It takes on the standard input the specification of the options to parse and
 376 understand, and echoes on the standard output a line suitable for `sh(1)` `eval`
 377 to replace the arguments with normalized ones.  In case of error, it outputs
 378 usage on the standard error stream, and exits with code 129.
 379
 380 Input Format
 381 ~~~~~~~~~~~~
 382
 383 'git rev-parse --parseopt' input format is fully text based. It has two parts,
 384 separated by a line that contains only `--`. The lines before the separator
 385 (should be more than one) are used for the usage.
 386 The lines after the separator describe the options.
 387
 388 Each line of options has this format:
 389
 390 ------------
 391 <opt_spec><flags>* SP+ help LF
 392 ------------
 393
 394 `<opt_spec>`::
 395         its format is the short option character, then the long option name
 396         separated by a comma. Both parts are not required, though at least one
 397         is necessary. `h,help`, `dry-run` and `f` are all three correct
 398         `<opt_spec>`.
 399
 400 `<flags>`::
 401         `<flags>` are of `*`, `=`, `?` or `!`.
 402         * Use `=` if the option takes an argument.
 403
 404         * Use `?` to mean that the option is optional (though its use is discouraged).
 405
 406         * Use `*` to mean that this option should not be listed in the usage
 407           generated for the `-h` argument. It's shown for `--help-all` as
 408           documented in linkgit:gitcli[7].
 409
 410         * Use `!` to not make the corresponding negated long option available.
 411
 412 The remainder of the line, after stripping the spaces, is used
 413 as the help associated to the option.
 414
 415 Blank lines are ignored, and lines that don't match this specification are used
 416 as option group headers (start the line with a space to create such
 417 lines on purpose).
 418
 419 Example
 420 ~~~~~~~
 421
 422 ------------
 423 OPTS_SPEC="\
 424 some-command [options] <args>...
 425
 426 some-command does foo and bar!
 427 --
 428 h,help    show the help
 429
 430 foo       some nifty option --foo
 431 bar=      some cool option --bar with an argument
 432
 433   An option group Header
 434 C?        option C with an optional argument"
 435
 436 eval `echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?`
 437 ------------
 438
 439 SQ-QUOTE
 440 --------
 441
 442 In `--sq-quote` mode, 'git rev-parse' echoes on the standard output a
 443 single line suitable for `sh(1)` `eval`. This line is made by
 444 normalizing the arguments following `--sq-quote`. Nothing other than
 445 quoting the arguments is done.
 446
 447 If you want command input to still be interpreted as usual by
 448 'git rev-parse' before the output is shell quoted, see the `--sq`
 449 option.
 450
 451 Example
 452 ~~~~~~~
 453
 454 ------------
 455 $ cat >your-git-script.sh <<\EOF
 456 #!/bin/sh
 457 args=$(git rev-parse --sq-quote "$@")   # quote user-supplied arguments
 458 command="git frotz -n24 $args"          # and use it inside a handcrafted
 459                                         # command line
 460 eval "$command"
 461 EOF
 462
 463 $ sh your-git-script.sh "a b'c"
 464 ------------
 465
 466 EXAMPLES
 467 --------
 468
 469 * Print the object name of the current commit:
 470 +
 471 ------------
 472 $ git rev-parse --verify HEAD
 473 ------------
 474
 475 * Print the commit object name from the revision in the $REV shell variable:
 476 +
 477 ------------
 478 $ git rev-parse --verify $REV
 479 ------------
 480 +
 481 This will error out if $REV is empty or not a valid revision.
 482
 483 * Same as above:
 484 +
 485 ------------
 486 $ git rev-parse --default master --verify $REV
 487 ------------
 488 +
 489 but if $REV is empty, the commit object name from master will be printed.
 490
 491
 492 Author
 493 ------
 494 Written by Linus Torvalds <torvalds@osdl.org> .
 495 Junio C Hamano <gitster@pobox.com> and Pierre Habouzit <madcoder@debian.org>
 496
 497 Documentation
 498 --------------
 499 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 500
 501 GIT
 502 ---
 503 Part of the linkgit:git[1] suite