rev-parse: document how --is-* options work outside a repository

When "git rev-parse" is run with the "--is-inside-work-tree" option
and friends outside a Git repository, the command exits with a
non-zero status and says "fatal: not a repository".  While it is not
wrong per-se, in the sense that it is useless to learn if we are
inside or outside a working tree in the first place when we are not
even in a repository, it could be argued that they should emit
"false" and exit with status 0, as they cannot possibly be "true".

As the current behaviour has been with us for a decade or more
since it was introduced in Git 1.5.3 timeframe, it is too late to
change it.

And arguably, the current behaviour is easier to use if you want to
distinguish among three states, i.e.,

 (1) the cwd is not controlled by Git at all
 (2) the cwd is inside a working tree
 (3) the cwd is not inside a working tree (e.g., .git/hooks/)

with a single invocation of the command by doing

    if inout=$(git rev-parse --is-inside-work-tree)
    then
        case "$inout" in
        true)   : in a working tree ;;
        false)  : not in a working tree ;;
        esac
    else
        : not in a repository
    fi

So, let's document clearly that the command will die() when run
outside a repository in general, unless in some special cases like
when the command is in the --parseopt mode.

While at it, update the introductory text that makes it sound as if
the primary operating mode is the only operating mode of the
command, which was written long before we added "--parseopt" and
"--sq-quote" modes.

Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 912fab9f5e00b6e286b1d80a8164d76224408682..9c6edf35c80e2fec9c649c2cf7c304dc4e4b56c1 100644 (file)
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -18,8 +18,15 @@ Many Git porcelainish commands take a mixture of flags
 (i.e. parameters that begin with a dash '-') and parameters
 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.
+downstream of 'git rev-list'.  The primary purpose of this command
+is to allow calling programs to distinguish between them.  There are
+a few other operation modes that have nothing to do with the above
+"help parse command line options".
+
+Unless otherwise specified, most of the options and operation modes
+require you to run this command inside a git repository or a working
+tree that is under the control of a git repository, and will give you
+a fatal error otherwise.
 
 
 OPTIONS
@@ -32,11 +39,15 @@ Each of these options must appear first on the command line.
 
 --parseopt::
        Use 'git rev-parse' in option parsing mode (see PARSEOPT section below).
+       The command in this mode can be used outside a repository or
+       a working tree controlled by a repository.
 
 --sq-quote::
        Use 'git rev-parse' in shell quoting mode (see SQ-QUOTE
        section below). In contrast to the `--sq` option below, this
        mode only does quoting. Nothing else is done to command input.
+       The command in this mode can be used outside a repository or
+       a working tree controlled by a repository.
 
 Options for --parseopt
 ~~~~~~~~~~~~~~~~~~~~~~