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