Re: [PATCH] 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>
> ---
>  This time with a properly formatted, proposed log message.
> 
>  * Doc update.
> 
>  Documentation/git-rev-parse.txt | 15 +++++++++++++--
>  1 file changed, 13 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
> index f9d5a35fa0..04fe7b941c 100644
> --- 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 noting 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 control of a git repository, and will give you a