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