# "git cat-file <sha1>" shows usage but should not?

8 messages from 2009-04-15 to 2009-04-15. Participants: Sebastian Pipping, Jeff King, Junio C Hamano, Julian Phillips.
Thread: https://gitlist.dev/t/18885

## Sebastian Pipping, 2009-04-15 16:50

Subject: "git cat-file <sha1>" shows usage but should not?
Message-ID: <49E61067.6060802@hartwork.org>
URL: https://gitlist.dev/e/49E61067.6060802%40hartwork.org

```
Here is what I did:


$ git cat-file -t b8c11fbbffbe171c4960058fa2d96f708e57a80c
commit

$ git cat-file b8c11fbbffbe171c4960058fa2d96f708e57a80c
usage: git cat-file [-t|-s|-e|-p|<type>] <sha1>
   or: git cat-file [--batch|--batch-check] < <list_of_sha1s>
[..]

$ git --version
git version 1.6.3.rc0.1.gf800.dirty



Sebastian

```

## Jeff King, 2009-04-15 16:54

Subject: Re: "git cat-file <sha1>" shows usage but should not?
Message-ID: <20090415165420.GB24528@coredump.intra.peff.net>
URL: https://gitlist.dev/e/20090415165420.GB24528%40coredump.intra.peff.net
In-Reply-To: <49E61067.6060802@hartwork.org>

```
On Wed, Apr 15, 2009 at 06:50:47PM +0200, Sebastian Pipping wrote:

> Here is what I did:
> 
> $ git cat-file -t b8c11fbbffbe171c4960058fa2d96f708e57a80c
> commit
> 
> $ git cat-file b8c11fbbffbe171c4960058fa2d96f708e57a80c
> usage: git cat-file [-t|-s|-e|-p|<type>] <sha1>
>    or: git cat-file [--batch|--batch-check] < <list_of_sha1s>
> [..]

That usage message is misleading. You need to use one of -t, -s, -e, -p,
or <type>. So it should perhaps just be:

  git cat-file -t|-s|-e|-p|<type> <sha1>

though that looks terribly ugly. Suggestions welcome.

-Peff

P.S. Depending on what you're trying to accomplish, "git show <sha1>"
     may be a better choice.

```

## Sebastian Pipping, 2009-04-15 16:56

Subject: Re: "git cat-file <sha1>" shows usage but should not?
Message-ID: <49E611A5.8090602@hartwork.org>
URL: https://gitlist.dev/e/49E611A5.8090602%40hartwork.org
In-Reply-To: <20090415165420.GB24528@coredump.intra.peff.net>

```
Jeff King wrote:
> That usage message is misleading. You need to use one of -t, -s, -e, -p,
> or <type>. So it should perhaps just be:
> 
>   git cat-file -t|-s|-e|-p|<type> <sha1>
> 
> though that looks terribly ugly. Suggestions welcome.

Thanks for making that clear.  How about round or curly brackets?



Sebastian

```

## Jeff King, 2009-04-15 17:04

Subject: Re: "git cat-file <sha1>" shows usage but should not?
Message-ID: <20090415170444.GA24717@coredump.intra.peff.net>
URL: https://gitlist.dev/e/20090415170444.GA24717%40coredump.intra.peff.net
In-Reply-To: <49E611A5.8090602@hartwork.org>

```
On Wed, Apr 15, 2009 at 06:56:05PM +0200, Sebastian Pipping wrote:

> Jeff King wrote:
> > That usage message is misleading. You need to use one of -t, -s, -e, -p,
> > or <type>. So it should perhaps just be:
> > 
> >   git cat-file -t|-s|-e|-p|<type> <sha1>
> > 
> > though that looks terribly ugly. Suggestions welcome.
> 
> Thanks for making that clear.  How about round or curly brackets?

I think curly makes the most sense for grouping, though I still think it
is a bit ugly. Patch is below.

-- >8 --
Subject: [PATCH] fix cat-file usage message and documentation

cat-file with an object on the command line requires an
option to tell it what to output (type, size, pretty-print,
etc). However, the square brackets in the usage imply that
those options are not required. This patch switches them to
curly braces to indicate "required but grouped-OR".

While we're at it, let's change the <sha1> specifier in the
usage to <object>. That's what the documentation uses, and
it does actually use the regular object lookup.
---
The curly braces seem to render fine via asciidoc (presumably because
there is no entity with that name), but I'm not sure if that will work
with all asciidoc versions.

 Documentation/git-cat-file.txt |    2 +-
 builtin-cat-file.c             |    4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt
index b191276..0856568 100644
--- a/Documentation/git-cat-file.txt
+++ b/Documentation/git-cat-file.txt
@@ -9,7 +9,7 @@ git-cat-file - Provide content or type and size information for repository objec
 SYNOPSIS
 --------
 [verse]
-'git cat-file' [-t | -s | -e | -p | <type>] <object>
+'git cat-file' {-t | -s | -e | -p | <type>} <object>
 'git cat-file' [--batch | --batch-check] < <list-of-objects>
 
 DESCRIPTION
diff --git a/builtin-cat-file.c b/builtin-cat-file.c
index 8fad19d..4e6ad73 100644
--- a/builtin-cat-file.c
+++ b/builtin-cat-file.c
@@ -201,8 +201,8 @@ static int batch_objects(int print_contents)
 }
 
 static const char * const cat_file_usage[] = {
-	"git cat-file [-t|-s|-e|-p|<type>] <sha1>",
-	"git cat-file [--batch|--batch-check] < <list_of_sha1s>",
+	"git cat-file {-t|-s|-e|-p|<type>} <object>",
+	"git cat-file [--batch|--batch-check] < <list_of_objects>",
 	NULL
 };
 
-- 
1.6.3.rc0.156.g19ef8

```

## Junio C Hamano, 2009-04-15 17:18

Subject: Re: "git cat-file <sha1>" shows usage but should not?
Message-ID: <7vprfdvnrj.fsf@gitster.siamese.dyndns.org>
URL: https://gitlist.dev/e/7vprfdvnrj.fsf%40gitster.siamese.dyndns.org
In-Reply-To: <20090415170444.GA24717@coredump.intra.peff.net>

```
Jeff King <peff@peff.net> writes:

> On Wed, Apr 15, 2009 at 06:56:05PM +0200, Sebastian Pipping wrote:
>
>> Jeff King wrote:
>> > That usage message is misleading. You need to use one of -t, -s, -e, -p,
>> > or <type>. So it should perhaps just be:
>> > 
>> >   git cat-file -t|-s|-e|-p|<type> <sha1>
>> > 
>> > though that looks terribly ugly. Suggestions welcome.
>> 
>> Thanks for making that clear.  How about round or curly brackets?
>
> I think curly makes the most sense for grouping, though I still think it
> is a bit ugly. Patch is below.

Thanks.  Doesn't this remind us of $gmane/72243, by the way?

```

## Julian Phillips, 2009-04-15 17:33

Subject: Re: "git cat-file <sha1>" shows usage but should not?
Message-ID: <alpine.LNX.2.00.0904151827530.14321@reaper.quantumfyre.co.uk>
URL: https://gitlist.dev/e/alpine.LNX.2.00.0904151827530.14321%40reaper.quantumfyre.co.uk
In-Reply-To: <20090415170444.GA24717@coredump.intra.peff.net>

```
On Wed, 15 Apr 2009, Jeff King wrote:

> static const char * const cat_file_usage[] = {
> -	"git cat-file [-t|-s|-e|-p|<type>] <sha1>",
> -	"git cat-file [--batch|--batch-check] < <list_of_sha1s>",
> +	"git cat-file {-t|-s|-e|-p|<type>} <object>",
> +	"git cat-file [--batch|--batch-check] < <list_of_objects>",

Shouldn't that read:

+	"git cat-file {--batch|--batch-check} < <list_of_objects>",

since, like the previous line, you are required to supply one of the two 
options?

-- 
Julian

  ---
DPRINTK("FAILURE, CAPUT\n");
         linux-2.6.6/drivers/net/tokenring/ibmtr.c

```

## Jeff King, 2009-04-15 17:34

Subject: Re: "git cat-file <sha1>" shows usage but should not?
Message-ID: <20090415173440.GA25480@coredump.intra.peff.net>
URL: https://gitlist.dev/e/20090415173440.GA25480%40coredump.intra.peff.net
In-Reply-To: <7vprfdvnrj.fsf@gitster.siamese.dyndns.org>

```
On Wed, Apr 15, 2009 at 10:18:40AM -0700, Junio C Hamano wrote:

> > I think curly makes the most sense for grouping, though I still think it
> > is a bit ugly. Patch is below.
> 
> Thanks.  Doesn't this remind us of $gmane/72243, by the way?

Ah, yes. I felt like we had dealt with this before, but I couldn't
remember for what.

That message indicates that {} is preferred to (). Interestingly,
though, the stash usage and documentation still uses ().

-Peff

```

## Jeff King, 2009-04-15 17:36

Subject: Re: "git cat-file <sha1>" shows usage but should not?
Message-ID: <20090415173640.GB25480@coredump.intra.peff.net>
URL: https://gitlist.dev/e/20090415173640.GB25480%40coredump.intra.peff.net
In-Reply-To: <alpine.LNX.2.00.0904151827530.14321@reaper.quantumfyre.co.uk>

```
On Wed, Apr 15, 2009 at 06:33:10PM +0100, Julian Phillips wrote:

> On Wed, 15 Apr 2009, Jeff King wrote:
>
>> static const char * const cat_file_usage[] = {
>> -	"git cat-file [-t|-s|-e|-p|<type>] <sha1>",
>> -	"git cat-file [--batch|--batch-check] < <list_of_sha1s>",
>> +	"git cat-file {-t|-s|-e|-p|<type>} <object>",
>> +	"git cat-file [--batch|--batch-check] < <list_of_objects>",
>
> Shouldn't that read:
>
> +	"git cat-file {--batch|--batch-check} < <list_of_objects>",
>
> since, like the previous line, you are required to supply one of the two  
> options?

Oops, yes, it should.

-Peff

```