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

From: Junio C Hamano <gitster@pobox.com>
Date: May 1, 2024, 17:22 UTC
Message-ID: <xmqqplu54fbg.fsf@gitster.g>

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
+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
 ~~~~~~~~~~~~~~~~~~~~~~

-- 
2.45.0-31-gd4cc1ec35f