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::
+--keep-dashdash::
Only meaningful in `--parseopt` mode. Tells the option parser to echo
out the first `--` met instead of skipping it.
+--stop-at-non-option::
+ Only meaningful in `--parseopt` mode. Lets the option parser stop at
+ the first non-option argument. This can be used to parse sub-commands
+ that take options themselves.
+
+--sq-quote::
+ Use 'git rev-parse' in shell quoting mode (see SQ-QUOTE
+ section below). In contrast to the `--sq` option below, this
+ mode does only quoting. Nothing else is done to command input.
+
--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.
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-\*'). In contrast to the `--sq-quote` option,
+ the command input is still interpreted as usual.
--not::
When showing object names, prefix them with '{caret}' and
unfortunately named tag "master"), and show them as full
refnames (e.g. "refs/heads/master").
---all::
- Show all refs found in `$GIT_DIR/refs`.
+--abbrev-ref[={strict|loose}]::
+ A non-ambiguous short name of the objects name.
+ The option core.warnAmbiguousRefs is used to select the strict
+ abbreviation mode.
---branches::
- Show branch refs found in `$GIT_DIR/refs/heads`.
+--all::
+ Show all refs found in `refs/`.
+
+--branches[=pattern]::
+--tags[=pattern]::
+--remotes[=pattern]::
+ Show all branches, tags, or remote-tracking branches,
+ respectively (i.e., refs found in `refs/heads`,
+ `refs/tags`, or `refs/remotes`, respectively).
++
+If a `pattern` is given, only refs matching the given shell glob are
+shown. If the pattern does not contain a globbing character (`?`,
+`\*`, or `[`), it is turned into a prefix match by appending `/\*`.
---tags::
- Show tag refs found in `$GIT_DIR/refs/tags`.
+--glob=pattern::
+ Show all refs matching the shell glob pattern `pattern`. If
+ the pattern does not start with `refs/`, this is automatically
+ prepended. If the pattern does not contain a globbing
+ character (`?`, `\*`, or `[`), it is turned into a prefix
+ match by appending `/\*`.
---remotes::
- Show tag refs found in `$GIT_DIR/refs/remotes`.
+--show-toplevel::
+ Show the absolute path of the top-level directory.
--show-prefix::
When the command is invoked from a subdirectory, show the
--is-bare-repository::
When the repository is bare print "true", otherwise "false".
+--local-env-vars::
+ List the GIT_* environment variables that are local to the
+ repository (e.g. GIT_DIR or GIT_WORK_TREE, but not GIT_EDITOR).
+ Only the names of the variables are listed, not their value,
+ even if they are set.
+
--short::
--short=number::
Instead of outputting the full SHA1 values of object names try to
--since=datestring::
--after=datestring::
- Parses the date string, and outputs corresponding
- --max-age= parameter for git-rev-list command.
+ 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.
+ 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
+ object referenced by refs/heads/master. If you
happen to have both heads/master and tags/master, you can
explicitly say 'heads/master' to tell git which one you mean.
When ambiguous, a `<name>` is disambiguated by taking the
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, `refs/<name>` if exists;
- . otherwise, `$GIT_DIR/refs/tags/<name>` if exists;
+ . otherwise, `refs/tags/<name>` if exists;
- . otherwise, `$GIT_DIR/refs/heads/<name>` if exists;
+ . otherwise, `refs/heads/<name>` if exists;
- . otherwise, `$GIT_DIR/refs/remotes/<name>` if exists;
+ . otherwise, `refs/remotes/<name>` if exists;
- . otherwise, `$GIT_DIR/refs/remotes/<name>/HEAD` if exists.
+ . otherwise, `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'.
++
+Note that any of the `refs/*` cases above may come either from
+the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.
* A ref followed by the suffix '@' with a date specification
enclosed in a brace
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.
+
+* The suffix '@\{upstream\}' to a ref (short form 'ref@\{u\}') refers to
+ the branch the ref is set to build on top of. Missing ref defaults
+ to the current branch.
+
* 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
commit, following the commit ancestry chain.
To exclude commits reachable from a commit, a prefix `{caret}`
-notation is used. E.g. "`{caret}r1 r2`" means commits reachable
+notation is used. E.g. `{caret}r1 r2` means commits reachable
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
+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.
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.
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 $?`
+------------
+
+SQ-QUOTE
+--------
+
+In `--sq-quote` mode, 'git rev-parse' echoes on the standard output a
+single line suitable for `sh(1)` `eval`. This line is made by
+normalizing the arguments following `--sq-quote`. Nothing other than
+quoting the arguments is done.
+
+If you want command input to still be interpreted as usual by
+'git rev-parse' before the output is shell quoted, see the `--sq`
+option.
+
+Example
+~~~~~~~
+
+------------
+$ cat >your-git-script.sh <<\EOF
+#!/bin/sh
+args=$(git rev-parse --sq-quote "$@") # quote user-supplied arguments
+command="git frotz -n24 $args" # and use it inside a handcrafted
+ # command line
+eval "$command"
+EOF
+
+$ sh your-git-script.sh "a b'c"
------------
EXAMPLES