Merge branch 'jc/format-patch'
[gitweb.git] / Documentation / git-rev-parse.txt
index 431b8f6e06194e302aac02fdf90522e6f5c04167..b761b4b9656eebf5b9caafc9d702c02e3f243fff 100644 (file)
@@ -3,7 +3,7 @@ git-rev-parse(1)
 
 NAME
 ----
-git-rev-parse - Pick out and massage parameters.
+git-rev-parse - Pick out and massage parameters
 
 
 SYNOPSIS
@@ -13,7 +13,7 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-Many git Porcelainish commands take mixture of flags
+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
@@ -67,11 +67,33 @@ OPTIONS
 --all::
        Show all refs found in `$GIT_DIR/refs`.
 
+--branches::
+       Show branch refs found in `$GIT_DIR/refs/heads`.
+
+--tags::
+       Show tag refs found in `$GIT_DIR/refs/tags`.
+
+--remotes::
+       Show tag refs found in `$GIT_DIR/refs/remotes`.
+
 --show-prefix::
-       When the command is invoked from a directory show the
+       When the command is invoked from a subdirectory, show the
        path of the current directory relative to the top-level
        directory.
 
+--show-cdup::
+       When the command is invoked from a subdirectory, show the
+       path of the top-level directory relative to the current
+       directory (typically a sequence of "../", or an empty string).
+
+--git-dir::
+       Show `$GIT_DIR` if defined else show the path to the .git directory.
+
+--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.
@@ -102,6 +124,13 @@ syntax.
   happen to have both heads/master and tags/master, you can
   explicitly say 'heads/master' to tell git which one you mean.
 
+* A suffix '@' followed by a date specification enclosed in a brace
+  pair (e.g. '\{yesterday\}', '\{1 month 2 weeks 3 days 1 hour 1
+  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>).
+
 * 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}'
@@ -127,11 +156,6 @@ syntax.
   and dereference the tag recursively until a non-tag object is
   found.
 
-'git-rev-parse' also accepts a prefix '{caret}' to revision parameter,
-which is passed to 'git-rev-list'.  Two revision parameters
-concatenated with '..' is a short-hand for writing a range
-between them.  I.e. 'r1..r2' is equivalent to saying '{caret}r1 r2'
-
 Here is an illustration, by Jon Loeliger.  Both node B and C are
 a commit parents of commit node A.  Parent commits are ordered
 left-to-right.
@@ -139,9 +163,9 @@ left-to-right.
     G   H   I   J
      \ /     \ /
       D   E   F
-       \  |  /
-        \ | /
-         \|/
+       \  |  / \
+        \ | /   |
+         \|/    |
           B     C
            \   /
             \ /
@@ -159,6 +183,40 @@ left-to-right.
     J = F^2  = B^3^2   = A^^3^2
 
 
+SPECIFYING RANGES
+-----------------
+
+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
+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`).
+
+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)`".
+It it the set of commits that are reachable from either one of
+`r1` or `r2` but not from both.
+
+Here are a few examples:
+
+   D                A B D
+   D F              A B C D F
+   ^A G                    B D
+   ^A F             B C F
+   G...I            C D F G I
+   ^B G I          C D F G I
+
 Author
 ------
 Written by Linus Torvalds <torvalds@osdl.org> and