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 --revs-only::
  27         Do not output flags and parameters not meant for
  28         `git-rev-list` command.
  29
  30 --no-revs::
  31         Do not output flags and parameters meant for
  32         `git-rev-list` command.
  33
  34 --flags::
  35         Do not output non-flag parameters.
  36
  37 --no-flags::
  38         Do not output flag parameters.
  39
  40 --default <arg>::
  41         If there is no parameter given by the user, use `<arg>`
  42         instead.
  43
  44 --verify::
  45         The parameter given must be usable as a single, valid
  46         object name.  Otherwise barf and abort.
  47
  48 --sq::
  49         Usually the output is made one line per flag and
  50         parameter.  This option makes output a single line,
  51         properly quoted for consumption by shell.  Useful when
  52         you expect your parameter to contain whitespaces and
  53         newlines (e.g. when using pickaxe `-S` with
  54         `git-diff-\*`).
  55
  56 --not::
  57         When showing object names, prefix them with '{caret}' and
  58         strip '{caret}' prefix from the object names that already have
  59         one.
  60
  61 --symbolic::
  62         Usually the object names are output in SHA1 form (with
  63         possible '{caret}' prefix); this option makes them output in a
  64         form as close to the original input as possible.
  65
  66
  67 --all::
  68         Show all refs found in `$GIT_DIR/refs`.
  69
  70 --branches::
  71         Show branch refs found in `$GIT_DIR/refs/heads`.
  72
  73 --tags::
  74         Show tag refs found in `$GIT_DIR/refs/tags`.
  75
  76 --remotes::
  77         Show tag refs found in `$GIT_DIR/refs/remotes`.
  78
  79 --show-prefix::
  80         When the command is invoked from a subdirectory, show the
  81         path of the current directory relative to the top-level
  82         directory.
  83
  84 --show-cdup::
  85         When the command is invoked from a subdirectory, show the
  86         path of the top-level directory relative to the current
  87         directory (typically a sequence of "../", or an empty string).
  88
  89 --git-dir::
  90         Show `$GIT_DIR` if defined else show the path to the .git directory.
  91
  92 --is-inside-git-dir::
  93         Return "true" if we are in the git directory, otherwise "false".
  94         Some commands require to be run in a working directory.
  95
  96 --short, --short=number::
  97         Instead of outputting the full SHA1 values of object names try to
  98         abbreviate them to a shorter unique name. When no length is specified
  99         7 is used. The minimum length is 4.
 100
 101 --since=datestring, --after=datestring::
 102         Parses the date string, and outputs corresponding
 103         --max-age= parameter for git-rev-list command.
 104
 105 --until=datestring, --before=datestring::
 106         Parses the date string, and outputs corresponding
 107         --min-age= parameter for git-rev-list command.
 108
 109 <args>...::
 110         Flags and parameters to be parsed.
 111
 112
 113 SPECIFYING REVISIONS
 114 --------------------
 115
 116 A revision parameter typically, but not necessarily, names a
 117 commit object.  They use what is called an 'extended SHA1'
 118 syntax.  Here are various ways to spell object names.  The
 119 ones listed near the end of this list are to name trees and
 120 blobs contained in a commit.
 121
 122 * The full SHA1 object name (40-byte hexadecimal string), or
 123   a substring of such that is unique within the repository.
 124   E.g. dae86e1950b1277e545cee180551750029cfe735 and dae86e both
 125   name the same commit object if there are no other object in
 126   your repository whose object name starts with dae86e.
 127
 128 * An output from `git-describe`; i.e. a closest tag, followed by a
 129   dash, a `g`, and an abbreviated object name.
 130
 131 * A symbolic ref name.  E.g. 'master' typically means the commit
 132   object referenced by $GIT_DIR/refs/heads/master.  If you
 133   happen to have both heads/master and tags/master, you can
 134   explicitly say 'heads/master' to tell git which one you mean.
 135   When ambiguous, a `<name>` is disambiguated by taking the
 136   first match in the following rules:
 137
 138   . if `$GIT_DIR/<name>` exists, that is what you mean (this is usually
 139     useful only for `HEAD`, `FETCH_HEAD` and `MERGE_HEAD`);
 140
 141   . otherwise, `$GIT_DIR/refs/<name>` if exists;
 142
 143   . otherwise, `$GIT_DIR/refs/tags/<name>` if exists;
 144
 145   . otherwise, `$GIT_DIR/refs/heads/<name>` if exists;
 146
 147   . otherwise, `$GIT_DIR/refs/remotes/<name>` if exists;
 148
 149   . otherwise, `$GIT_DIR/refs/remotes/<name>/HEAD` if exists.
 150
 151 * A ref followed by the suffix '@' with a date specification
 152   enclosed in a brace
 153   pair (e.g. '\{yesterday\}', '\{1 month 2 weeks 3 days 1 hour 1
 154   second ago\}' or '\{1979-02-26 18:30:00\}') to specify the value
 155   of the ref at a prior point in time.  This suffix may only be
 156   used immediately following a ref name and the ref must have an
 157   existing log ($GIT_DIR/logs/<ref>).
 158
 159 * A ref followed by the suffix '@' with an ordinal specification
 160   enclosed in a brace pair (e.g. '\{1\}', '\{15\}') to specify
 161   the n-th prior value of that ref.  For example 'master@\{1\}'
 162   is the immediate prior value of 'master' while 'master@\{5\}'
 163   is the 5th prior value of 'master'. This suffix may only be used
 164   immediately following a ref name and the ref must have an existing
 165   log ($GIT_DIR/logs/<ref>).
 166
 167 * You can use the '@' construct with an empty ref part to get at a
 168   reflog of the current branch. For example, if you are on the
 169   branch 'blabla', then '@\{1\}' means the same as 'blabla@\{1\}'.
 170
 171 * A suffix '{caret}' to a revision parameter means the first parent of
 172   that commit object.  '{caret}<n>' means the <n>th parent (i.e.
 173   'rev{caret}'
 174   is equivalent to 'rev{caret}1').  As a special rule,
 175   'rev{caret}0' means the commit itself and is used when 'rev' is the
 176   object name of a tag object that refers to a commit object.
 177
 178 * A suffix '{tilde}<n>' to a revision parameter means the commit
 179   object that is the <n>th generation grand-parent of the named
 180   commit object, following only the first parent.  I.e. rev~3 is
 181   equivalent to rev{caret}{caret}{caret} which is equivalent to
 182   rev{caret}1{caret}1{caret}1.  See below for a illustration of
 183   the usage of this form.
 184
 185 * A suffix '{caret}' followed by an object type name enclosed in
 186   brace pair (e.g. `v0.99.8{caret}\{commit\}`) means the object
 187   could be a tag, and dereference the tag recursively until an
 188   object of that type is found or the object cannot be
 189   dereferenced anymore (in which case, barf).  `rev{caret}0`
 190   introduced earlier is a short-hand for `rev{caret}\{commit\}`.
 191
 192 * A suffix '{caret}' followed by an empty brace pair
 193   (e.g. `v0.99.8{caret}\{\}`) means the object could be a tag,
 194   and dereference the tag recursively until a non-tag object is
 195   found.
 196
 197 * A colon, followed by a slash, followed by a text: this names
 198   a commit whose commit message starts with the specified text.
 199   This name returns the youngest matching commit which is
 200   reachable from any ref.  If the commit message starts with a
 201   '!', you have to repeat that;  the special sequence ':/!',
 202   followed by something else than '!' is reserved for now.
 203
 204 * A suffix ':' followed by a path; this names the blob or tree
 205   at the given path in the tree-ish object named by the part
 206   before the colon.
 207
 208 * A colon, optionally followed by a stage number (0 to 3) and a
 209   colon, followed by a path; this names a blob object in the
 210   index at the given path.  Missing stage number (and the colon
 211   that follows it) names an stage 0 entry.
 212
 213 Here is an illustration, by Jon Loeliger.  Both node B and C are
 214 a commit parents of commit node A.  Parent commits are ordered
 215 left-to-right.
 216
 217     G   H   I   J
 218      \ /     \ /
 219       D   E   F
 220        \  |  / \
 221         \ | /   |
 222          \|/    |
 223           B     C
 224            \   /
 225             \ /
 226              A
 227
 228     A =      = A^0
 229     B = A^   = A^1     = A~1
 230     C = A^2  = A^2
 231     D = A^^  = A^1^1   = A~2
 232     E = B^2  = A^^2
 233     F = B^3  = A^^3
 234     G = A^^^ = A^1^1^1 = A~3
 235     H = D^2  = B^^2    = A^^^2  = A~2^2
 236     I = F^   = B^3^    = A^^3^
 237     J = F^2  = B^3^2   = A^^3^2
 238
 239
 240 SPECIFYING RANGES
 241 -----------------
 242
 243 History traversing commands such as `git-log` operate on a set
 244 of commits, not just a single commit.  To these commands,
 245 specifying a single revision with the notation described in the
 246 previous section means the set of commits reachable from that
 247 commit, following the commit ancestry chain.
 248
 249 To exclude commits reachable from a commit, a prefix `{caret}`
 250 notation is used.  E.g. "`{caret}r1 r2`" means commits reachable
 251 from `r2` but exclude the ones reachable from `r1`.
 252
 253 This set operation appears so often that there is a shorthand
 254 for it.  "`r1..r2`" is equivalent to "`{caret}r1 r2`".  It is
 255 the difference of two sets (subtract the set of commits
 256 reachable from `r1` from the set of commits reachable from
 257 `r2`).
 258
 259 A similar notation "`r1\...r2`" is called symmetric difference
 260 of `r1` and `r2` and is defined as
 261 "`r1 r2 --not $(git-merge-base --all r1 r2)`".
 262 It is the set of commits that are reachable from either one of
 263 `r1` or `r2` but not from both.
 264
 265 Two other shorthands for naming a set that is formed by a commit
 266 and its parent commits exists.  `r1{caret}@` notation means all
 267 parents of `r1`.  `r1{caret}!` includes commit `r1` but excludes
 268 its all parents.
 269
 270 Here are a handful examples:
 271
 272    D                G H D
 273    D F              G H I J D F
 274    ^G D             H D
 275    ^D B             E I J F B
 276    B...C            G H D E B C
 277    ^D B C           E I J F B C
 278    C^@              I J F
 279    F^! D            G H D F
 280
 281 Author
 282 ------
 283 Written by Linus Torvalds <torvalds@osdl.org> and
 284 Junio C Hamano <junkio@cox.net>
 285
 286 Documentation
 287 --------------
 288 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 289
 290 GIT
 291 ---
 292 Part of the gitlink:git[7] suite