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