Many git porcelainish commands take mixture of flags
(i.e. parameters that begin with a dash '-') and parameters
-meant for the underlying `git-rev-list` command they use internally
+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
+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.
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
--since=datestring::
--after=datestring::
Parse the date string, and output the corresponding
- --max-age= parameter for `git-rev-list`.
+ --max-age= parameter for 'git-rev-list'.
--until=datestring::
--before=datestring::
Parse the date string, and output the corresponding
- --min-age= parameter for `git-rev-list`.
+ --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
+* An output from 'git-describe'; i.e. a closest tag, followed by a
dash, a `g`, and an abbreviated object name.
* A symbolic ref name. E.g. 'master' typically means the commit
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
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` 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.