![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
index 5981c79f6a2568c33b455c649946d6af2d9baeb3..3ccef2f2b3295c6d5e14b8f3a9d354d7b57598da 100644 (file)
SYNOPSIS
--------
-'git-rev-parse' [ --option ] <args>...
+'git rev-parse' [ --option ] <args>...
DESCRIPTION
-----------
Many git porcelainish commands take mixture of flags
(i.e. parameters that begin with a dash '-') and parameters
-meant for underlying `git-rev-list` command they use internally
-and flags and parameters for other commands they use as the
-downstream of `git-rev-list`. This command is used to
+meant for the underlying 'git-rev-list' command they use internally
+and flags and parameters for the other commands they use
+downstream of 'git-rev-list'. This command is used to
distinguish between them.
OPTIONS
-------
--parseopt::
- Use `git-rev-parse` in option parsing mode (see PARSEOPT section below).
+ Use 'git-rev-parse' in option parsing mode (see PARSEOPT section below).
--keep-dash-dash::
Only meaningful in `--parseopt` mode. Tells the option parser to echo
--revs-only::
Do not output flags and parameters not meant for
- `git-rev-list` command.
+ 'git-rev-list' command.
--no-revs::
Do not output flags and parameters meant for
- `git-rev-list` command.
+ 'git-rev-list' command.
--flags::
Do not output non-flag parameters.
The parameter given must be usable as a single, valid
object name. Otherwise barf and abort.
+-q::
+--quiet::
+ Only meaningful in `--verify` mode. Do not output an error
+ message if the first argument is not a valid object name;
+ instead exit with non-zero status silently.
+
--sq::
Usually the output is made one line per flag and
parameter. This option makes output a single line,
properly quoted for consumption by shell. Useful when
you expect your parameter to contain whitespaces and
newlines (e.g. when using pickaxe `-S` with
- `git-diff-\*`).
+ 'git-diff-\*').
--not::
When showing object names, prefix them with '{caret}' and
--is-bare-repository::
When the repository is bare print "true", otherwise "false".
---short, --short=number::
+--short::
+--short=number::
Instead of outputting the full SHA1 values of object names try to
abbreviate them to a shorter unique name. When no length is specified
7 is used. The minimum length is 4.
---since=datestring, --after=datestring::
- Parses the date string, and outputs corresponding
- --max-age= parameter for git-rev-list command.
+--since=datestring::
+--after=datestring::
+ Parse the date string, and output the corresponding
+ --max-age= parameter for 'git-rev-list'.
---until=datestring, --before=datestring::
- Parses the date string, and outputs corresponding
- --min-age= parameter for git-rev-list command.
+--until=datestring::
+--before=datestring::
+ Parse the date string, and output the corresponding
+ --min-age= parameter for 'git-rev-list'.
<args>...::
Flags and parameters to be parsed.
name the same commit object if there are no other object in
your repository whose object name starts with dae86e.
-* An output from `git-describe`; i.e. a closest tag, followed by a
- dash, a `g`, and an abbreviated object name.
+* An output from 'git-describe'; i.e. a closest tag, optionally
+ followed by a dash and a number of commits, followed by a dash, a
+ `g`, and an abbreviated object name.
* A symbolic ref name. E.g. 'master' typically means the commit
object referenced by $GIT_DIR/refs/heads/master. If you
first match in the following rules:
. if `$GIT_DIR/<name>` exists, that is what you mean (this is usually
- useful only for `HEAD`, `FETCH_HEAD` and `MERGE_HEAD`);
+ useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD` and `MERGE_HEAD`);
. otherwise, `$GIT_DIR/refs/<name>` if exists;
. otherwise, `$GIT_DIR/refs/remotes/<name>` if exists;
. otherwise, `$GIT_DIR/refs/remotes/<name>/HEAD` if exists.
++
+HEAD names the commit your changes in the working tree is based on.
+FETCH_HEAD records the branch you fetched from a remote repository
+with your last 'git-fetch' invocation.
+ORIG_HEAD is created by commands that moves your HEAD in a drastic
+way, to record the position of the HEAD before their operation, so that
+you can change the tip of the branch back to the state before you ran
+them easily.
+MERGE_HEAD records the commit(s) you are merging into your branch
+when you run 'git-merge'.
* A ref followed by the suffix '@' with a date specification
enclosed in a brace
second ago\}' or '\{1979-02-26 18:30:00\}') to specify the value
of the ref at a prior point in time. This suffix may only be
used immediately following a ref name and the ref must have an
- existing log ($GIT_DIR/logs/<ref>).
+ existing log ($GIT_DIR/logs/<ref>). Note that this looks up the state
+ of your *local* ref at a given time; e.g., what was in your local
+ `master` branch last week. If you want to look at commits made during
+ certain times, see `--since` and `--until`.
* A ref followed by the suffix '@' with an ordinal specification
enclosed in a brace pair (e.g. '\{1\}', '\{15\}') to specify
reflog of the current branch. For example, if you are on the
branch 'blabla', then '@\{1\}' means the same as 'blabla@\{1\}'.
+* The special construct '@\{-<n>\}' means the <n>th branch checked out
+ before the current one.
+
* A suffix '{caret}' to a revision parameter means the first parent of
that commit object. '{caret}<n>' means the <n>th parent (i.e.
'rev{caret}'
SPECIFYING RANGES
-----------------
-History traversing commands such as `git-log` operate on a set
+History traversing commands such as 'git-log' operate on a set
of commits, not just a single commit. To these commands,
specifying a single revision with the notation described in the
previous section means the set of commits reachable from that
from `r2` but exclude the ones reachable from `r1`.
This set operation appears so often that there is a shorthand
-for it. "`r1..r2`" is equivalent to "`{caret}r1 r2`". It is
-the difference of two sets (subtract the set of commits
-reachable from `r1` from the set of commits reachable from
-`r2`).
+for it. When you have two commits `r1` and `r2` (named according
+to the syntax explained in SPECIFYING REVISIONS above), you can ask
+for commits that are reachable from r2 excluding those that are reachable
+from r1 by "`{caret}r1 r2`" and it can be written as "`r1..r2`".
A similar notation "`r1\...r2`" is called symmetric difference
of `r1` and `r2` and is defined as
-"`r1 r2 --not $(git-merge-base --all r1 r2)`".
+"`r1 r2 --not $(git merge-base --all r1 r2)`".
It is the set of commits that are reachable from either one of
`r1` or `r2` but not from both.
Two other shorthands for naming a set that is formed by a commit
-and its parent commits exists. `r1{caret}@` notation means all
+and its parent commits exist. The `r1{caret}@` notation means all
parents of `r1`. `r1{caret}!` includes commit `r1` but excludes
-its all parents.
+all of its parents.
Here are a handful of examples:
PARSEOPT
--------
-In `--parseopt` mode, `git-rev-parse` helps massaging options to bring to shell
+In `--parseopt` mode, 'git-rev-parse' helps massaging options to bring to shell
scripts the same facilities C builtins have. It works as an option normalizer
(e.g. splits single switches aggregate values), a bit like `getopt(1)` does.
Input Format
~~~~~~~~~~~~
-`git-rev-parse --parseopt` input format is fully text based. It has two parts,
+'git-rev-parse --parseopt' input format is fully text based. It has two parts,
separated by a line that contains only `--`. The lines before the separator
(should be more than one) are used for the usage.
The lines after the separator describe the options.
* Use `*` to mean that this option should not be listed in the usage
generated for the `-h` argument. It's shown for `--help-all` as
- documented in linkgit:gitcli[5].
+ documented in linkgit:gitcli[7].
* Use `!` to not make the corresponding negated long option available.
An option group Header
C? option C with an optional argument"
-eval `echo "$OPTS_SPEC" | git-rev-parse --parseopt -- "$@" || echo exit $?`
+eval `echo "$OPTS_SPEC" | git rev-parse --parseopt -- "$@" || echo exit $?`
+------------
+
+EXAMPLES
+--------
+
+* Print the object name of the current commit:
++
+------------
+$ git rev-parse --verify HEAD
+------------
+
+* Print the commit object name from the revision in the $REV shell variable:
++
+------------
+$ git rev-parse --verify $REV
+------------
++
+This will error out if $REV is empty or not a valid revision.
+
+* Same as above:
++
+------------
+$ git rev-parse --default master --verify $REV
------------
++
+but if $REV is empty, the commit object name from master will be printed.
Author
------
Written by Linus Torvalds <torvalds@osdl.org> .
-Junio C Hamano <junkio@cox.net> and Pierre Habouzit <madcoder@debian.org>
+Junio C Hamano <gitster@pobox.com> and Pierre Habouzit <madcoder@debian.org>
Documentation
--------------
GIT
---
-Part of the linkgit:git[7] suite
+Part of the linkgit:git[1] suite