Merge branch 'jc/maint-add-u-remove-conflicted'
[gitweb.git] / Documentation / git-rev-parse.txt
index 9082fc991be760e385e162ba6d118911c659955f..3ccef2f2b3295c6d5e14b8f3a9d354d7b57598da 100644 (file)
@@ -8,23 +8,23 @@ git-rev-parse - Pick out and massage parameters
 
 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
@@ -32,11 +32,11 @@ OPTIONS
 
 --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.
@@ -64,7 +64,7 @@ OPTIONS
        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
@@ -128,13 +128,13 @@ OPTIONS
 
 --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.
@@ -155,8 +155,9 @@ blobs contained in a commit.
   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
@@ -166,7 +167,7 @@ blobs contained in a 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;
 
@@ -177,6 +178,16 @@ blobs contained in a commit.
   . 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
@@ -201,6 +212,9 @@ blobs contained in a commit.
   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}'
@@ -278,7 +292,7 @@ G   H   I   J
 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
@@ -289,14 +303,14 @@ 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
 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.
 
@@ -319,7 +333,7 @@ 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.
 
@@ -331,7 +345,7 @@ usage on the standard error stream, and exits with code 129.
 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.
@@ -384,7 +398,7 @@ bar=      some cool option --bar with an argument
   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