Code

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