Re* Unexpected behavior with the rev-parse operation

[Junio C Hamano <gitster@pobox.com>]

Eric Sunshine <sunshine@sunshineco.com> writes:

> On Mon, Apr 15, 2024 at 9:58 AM Toru Okugawa <castor.4bit@gmail.com> wrote:
>> I have encountered some unexpected behavior with the rev-parse operation.
>> ---
>> $ ls -a
>> .  ..
>> $ git rev-parse --is-inside-work-tree
>> fatal: not a git repository (or any of the parent directories): .git
>> ...
> ... This
> means it is your responsibility, as a script writer, to suppress or
> capture the error message (whichever is appropriate for your case).
> For instance:
>
>     if test git rev-parse >/dev/null 2>&1
>     then
>         echo "in a Git directory or repository"
>     else
>         echo "not in a Git directory or repository"
>     fi

All true.  It may however need some documentation updates, though,
something along this line, perhaps?

 Documentation/git-rev-parse.txt | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git c/Documentation/git-rev-parse.txt w/Documentation/git-rev-parse.txt
index f9d5a35fa0..a62d798744 100644
--- c/Documentation/git-rev-parse.txt
+++ w/Documentation/git-rev-parse.txt
@@ -18,8 +18,16 @@ 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'.  One 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" added to the command.
+
+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
+fatal error otherwise.
 
 
 OPTIONS
@@ -32,11 +40,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
 ~~~~~~~~~~~~~~~~~~~~~~