Documentation: be consistent about "git-" versus "git "

[thirdparty/git.git] / Documentation / git-rev-parse.txt

diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 110e7ba71f48c54cb94f35e819583826e123a8b1..e9fb2b15795e213580ee78230d3db0b28dddc698 100644 (file)
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -8,7 +8,7 @@ git-rev-parse - Pick out and massage parameters
 
 SYNOPSIS
 --------
-'git-rev-parse' [ --option ] <args>...
+'git rev-parse' [ --option ] <args>...
 
 DESCRIPTION
 -----------
@@ -52,7 +52,8 @@ OPTIONS
        The parameter given must be usable as a single, valid
        object name.  Otherwise barf and abort.
 
--q, --quiet::
+-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.
@@ -119,16 +120,19 @@ OPTIONS
 --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::
+--since=datestring::
+--after=datestring::
        Parses the date string, and outputs corresponding
        --max-age= parameter for git-rev-list command.
 
---until=datestring, --before=datestring::
+--until=datestring::
+--before=datestring::
        Parses the date string, and outputs corresponding
        --min-age= parameter for git-rev-list command.
 
@@ -180,7 +184,10 @@ blobs contained in a commit.
   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
@@ -243,16 +250,18 @@ Here is an illustration, by Jon Loeliger.  Both commit nodes B
 and C are parents of commit node A.  Parent commits are ordered
 left-to-right.
 
-    G   H   I   J
-     \ /     \ /
-      D   E   F
-       \  |  / \ 
-        \ | /   |
-         \|/    |
-          B     C
-           \   /
-            \ /
-             A
+........................................
+G   H   I   J
+ \ /     \ /
+  D   E   F
+   \  |  / \
+    \ | /   |
+     \|/    |
+      B     C
+       \   /
+        \ /
+         A
+........................................
 
     A =      = A^0
     B = A^   = A^1     = A~1
@@ -287,7 +296,7 @@ reachable from `r1` from the set of commits reachable from
 
 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.
 
@@ -347,7 +356,7 @@ Each line of options has this format:
 
        * 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.
 
@@ -375,9 +384,34 @@ 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
+--------
+
+* 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
 ------
@@ -390,4 +424,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 
 GIT
 ---
-Part of the linkgit:git[7] suite
+Part of the linkgit:git[1] suite