Merge accumulated fixes to prepare for 1.7.0.3

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

diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index d375f1af1025698f73900d7eacdf8dc314a87278..8db600f6ba01bcb7f85be6c6606795a0034822b2 100644 (file)
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -33,7 +33,7 @@ OPTIONS
 --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 themself.
+       that take options themselves.
 
 --sq-quote::
        Use 'git rev-parse' in shell quoting mode (see SQ-QUOTE
@@ -101,16 +101,25 @@ OPTIONS
        abbreviation mode.
 
 --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`.
+       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 `/\*`.
 
---remotes::
-       Show tag refs found in `$GIT_DIR/refs/remotes`.
+--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 `/\*`.
 
 --show-toplevel::
        Show the absolute path of the top-level directory.
@@ -139,6 +148,12 @@ OPTIONS
 --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
@@ -179,7 +194,7 @@ blobs contained in a commit.
   `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
@@ -188,15 +203,15 @@ blobs contained in a commit.
   . if `$GIT_DIR/<name>` exists, that is what you mean (this is usually
     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
@@ -207,6 +222,9 @@ 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
@@ -234,6 +252,10 @@ when you run 'git merge'.
 * 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}'