Re: [PATCH 1/2] cat-file doc: document that -e will return some output

[Junio C Hamano]

Junio C Hamano  writes:

> Ævar Arnfjörð Bjarmason   writes:
>
>> The -e option added in 7950571ad7 ("A few more options for
>> git-cat-file", 2005-12-03) has always errored out with message on
>> stderr saying that the provided object is malformed, currently:
>>
>> $ git cat-file -e malformed; echo $?
>> fatal: Not a valid object name malformed
>> 128
>>
>> A careful reader of this documentation would be mislead into thinking
>> the could write:
>>
>> if ! git cat-file -e "$object" [...]
>
> It is arguable if such a reader is careful or careless.  I'd rather drop
> s/careful // there ;-)

Actually the phrasing around here was a bit strange, and I ended up
rewriting a bit more.

cat-file doc: document that -e will return some output

The -e option added in 7950571ad7 ("A few more options for
git-cat-file", 2005-12-03) has always errored out with message on
stderr saying that the provided object is malformed, like this:

$ git cat-file -e malformed; echo $?
fatal: Not a valid object name malformed
128

A reader of this documentation may be misled into thinking that

if ! git cat-file -e "$object" [...]

as opposed to:

if ! git cat-file -e "$object" 2>/dev/null [...]

is sufficient to implement a truly silent test that checks whether
some arbitrary $object string was both valid, and pointed to an
object that exists.

Signed-off-by: Ævar Arnfjörð Bjarmason 
Signed-off-by: Junio C Hamano 

Re: [PATCH 1/2] cat-file doc: document that -e will return some output

[Junio C Hamano]

Ævar Arnfjörð Bjarmason   writes:

> The -e option added in 7950571ad7 ("A few more options for
> git-cat-file", 2005-12-03) has always errored out with message on
> stderr saying that the provided object is malformed, currently:
>
> $ git cat-file -e malformed; echo $?
> fatal: Not a valid object name malformed
> 128
>
> A careful reader of this documentation would be mislead into thinking
> the could write:
>
> if ! git cat-file -e "$object" [...]

It is arguable if such a reader is careful or careless.  I'd rather drop
s/careful // there ;-)

> As opposed to:
>
> if ! git cat-file -e "$object" 2>/dev/null [...]
>
> To check whether some arbitrary $object string was both valid, and
> pointed to an object that exists.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason 
> ---
>  Documentation/git-cat-file.txt | 7 ---
>  1 file changed, 4 insertions(+), 3 deletions(-)

[PATCH 1/2] cat-file doc: document that -e will return some output

[Ævar Arnfjörð Bjarmason]

The -e option added in 7950571ad7 ("A few more options for
git-cat-file", 2005-12-03) has always errored out with message on
stderr saying that the provided object is malformed, currently:

$ git cat-file -e malformed; echo $?
fatal: Not a valid object name malformed
128

A careful reader of this documentation would be mislead into thinking
the could write:

if ! git cat-file -e "$object" [...]

As opposed to:

if ! git cat-file -e "$object" 2>/dev/null [...]

To check whether some arbitrary $object string was both valid, and
pointed to an object that exists.

Signed-off-by: Ævar Arnfjörð Bjarmason 
---
 Documentation/git-cat-file.txt | 7 ---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt
index fb09cd69d6..f90f09b03f 100644
--- a/Documentation/git-cat-file.txt
+++ b/Documentation/git-cat-file.txt
@@ -42,8 +42,9 @@ OPTIONS
.
 
 -e::
-   Suppress all output; instead exit with zero status if 
-   exists and is a valid object.
+   Exit with zero status if  exists and is a valid
+   object. If  is of an invalid format exit with non-zero and
+   emits an error on stderr.
 
 -p::
Pretty-print the contents of  based on its type.
@@ -168,7 +169,7 @@ If `-t` is specified, one of the .
 
 If `-s` is specified, the size of the  in bytes.
 
-If `-e` is specified, no output.
+If `-e` is specified, no output, unless the  is malformed.
 
 If `-p` is specified, the contents of  are pretty-printed.
 
-- 
2.15.1.424.g9478a66081