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 a 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 commit nodes B
 238 and C are parents of commit node A.  Parent commits are ordered
 239 left-to-right.
 240
 241 ........................................
 242 G   H   I   J
 243  \ /     \ /
 244   D   E   F
 245    \  |  / \
 246     \ | /   |
 247      \|/    |
 248       B     C
 249        \   /
 250         \ /
 251          A
 252 ........................................
 253
 254     A =      = A^0
 255     B = A^   = A^1     = A~1
 256     C = A^2  = A^2
 257     D = A^^  = A^1^1   = A~2
 258     E = B^2  = A^^2
 259     F = B^3  = A^^3
 260     G = A^^^ = A^1^1^1 = A~3
 261     H = D^2  = B^^2    = A^^^2  = A~2^2
 262     I = F^   = B^3^    = A^^3^
 263     J = F^2  = B^3^2   = A^^3^2
 264
 265
 266 SPECIFYING RANGES
 267 -----------------
 268
 269 History traversing commands such as `git-log` operate on a set
 270 of commits, not just a single commit.  To these commands,
 271 specifying a single revision with the notation described in the
 272 previous section means the set of commits reachable from that
 273 commit, following the commit ancestry chain.
 274
 275 To exclude commits reachable from a commit, a prefix `{caret}`
 276 notation is used.  E.g. "`{caret}r1 r2`" means commits reachable
 277 from `r2` but exclude the ones reachable from `r1`.
 278
 279 This set operation appears so often that there is a shorthand
 280 for it.  "`r1..r2`" is equivalent to "`{caret}r1 r2`".  It is
 281 the difference of two sets (subtract the set of commits
 282 reachable from `r1` from the set of commits reachable from
 283 `r2`).
 284
 285 A similar notation "`r1\...r2`" is called symmetric difference
 286 of `r1` and `r2` and is defined as
 287 "`r1 r2 --not $(git-merge-base --all r1 r2)`".
 288 It is the set of commits that are reachable from either one of
 289 `r1` or `r2` but not from both.
 290
 291 Two other shorthands for naming a set that is formed by a commit
 292 and its parent commits exists.  `r1{caret}@` notation means all
 293 parents of `r1`.  `r1{caret}!` includes commit `r1` but excludes
 294 its all parents.
 295
 296 Here are a handful of examples:
 297
 298    D                G H D
 299    D F              G H I J D F
 300    ^G D             H D
 301    ^D B             E I J F B
 302    B...C            G H D E B C
 303    ^D B C           E I J F B C
 304    C^@              I J F
 305    F^! D            G H D F
 306
 307 PARSEOPT
 308 --------
 309
 310 In `--parseopt` mode, `git-rev-parse` helps massaging options to bring to shell
 311 scripts the same facilities C builtins have. It works as an option normalizer
 312 (e.g. splits single switches aggregate values), a bit like `getopt(1)` does.
 313
 314 It takes on the standard input the specification of the options to parse and
 315 understand, and echoes on the standard output a line suitable for `sh(1)` `eval`
 316 to replace the arguments with normalized ones.  In case of error, it outputs
 317 usage on the standard error stream, and exits with code 129.
 318
 319 Input Format
 320 ~~~~~~~~~~~~
 321
 322 `git-rev-parse --parseopt` input format is fully text based. It has two parts,
 323 separated by a line that contains only `--`. The lines before the separator
 324 (should be more than one) are used for the usage.
 325 The lines after the separator describe the options.
 326
 327 Each line of options has this format:
 328
 329 ------------
 330 <opt_spec><flags>* SP+ help LF
 331 ------------
 332
 333 `<opt_spec>`::
 334         its format is the short option character, then the long option name
 335         separated by a comma. Both parts are not required, though at least one
 336         is necessary. `h,help`, `dry-run` and `f` are all three correct
 337         `<opt_spec>`.
 338
 339 `<flags>`::
 340         `<flags>` are of `*`, `=`, `?` or `!`.
 341         * Use `=` if the option takes an argument.
 342
 343         * Use `?` to mean that the option is optional (though its use is discouraged).
 344
 345         * Use `*` to mean that this option should not be listed in the usage
 346           generated for the `-h` argument. It's shown for `--help-all` as
 347           documented in linkgit:gitcli[5].
 348
 349         * Use `!` to not make the corresponding negated long option available.
 350
 351 The remainder of the line, after stripping the spaces, is used
 352 as the help associated to the option.
 353
 354 Blank lines are ignored, and lines that don't match this specification are used
 355 as option group headers (start the line with a space to create such
 356 lines on purpose).
 357
 358 Example
 359 ~~~~~~~
 360
 361 ------------
 362 OPTS_SPEC="\
 363 some-command [options] <args>...
 364
 365 some-command does foo and bar!
 366 --
 367 h,help    show the help
 368
 369 foo       some nifty option --foo
 370 bar=      some cool option --bar with an argument
 371
 372   An option group Header
 373 C?        option C with an optional argument"
 374
 375 eval `echo "$OPTS_SPEC" | git-rev-parse --parseopt -- "$@" || echo exit $?`
 376 ------------
 377
 378
 379 Author
 380 ------
 381 Written by Linus Torvalds <torvalds@osdl.org> .
 382 Junio C Hamano <junkio@cox.net> and Pierre Habouzit <madcoder@debian.org>
 383
 384 Documentation
 385 --------------
 386 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 387
 388 GIT
 389 ---
 390 Part of the linkgit:git[7] suite