| Message ID | xmqqplu54fbg.fsf@gitster.g (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | rev-parse: document how --is-* options work outside a repository | expand |
On 24/05/01 10:22AM, Junio C Hamano wrote: > 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 s/repository ,/repository,/ > "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 s/noting/nothing/ > +"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 s/control/the control/ > +fatal error otherwise. Thanks for the clarification. Noticed a couple small grammar/spelling issues but otherwise looks good :) -Justin
Justin Tobler <jltobler@gmail.com> writes: > Thanks for the clarification. Noticed a couple small grammar/spelling > issues but otherwise looks good :) Thanks for reading carefully.
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 ~~~~~~~~~~~~~~~~~~~~~~
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(-)