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