[RFC] 'git cat-file' needs a better design on its option interface

[RFC] 'git cat-file' needs a better design on its option interface

[Li Hong]

Hi All,

When using 'git cat-file' recently, I find its option interface is somewhat
inconvenient or mistakenly-designed.

	1. There is no default action. You have to use -p or <type> option,
	even for a simple look at the content of an object. It is better if
	we can provide a default action just like 'cat' does.
	
	2. Can't control the output. Several output options can't be used at
	the same time. Can't control what to output and how to output. I
	suggest here we use a simple format string to let the human being
	and other batch scripts happy.

	3. Batch mode is handled seperately and differently.

	4. <type> option has a mix meaning (raw print and object dereference)
	and is also inconsistent with -x style option.

	  * for raw print, an format char such as 'r' should be a good choice.
	  * for dereference, should use the uniform rev-naming. (e.g.
	    v0.99.8^{commit})


So I propose to amend the interface as follow:

	git cat-file [-b] [-f <fmt>] [-e] <args> ...

	-b	read more objects from stdin
	-f	provide a output format string
	-e	silent, exit with zero when there's no error

	the default action is to pretty-print the content when there is no
	other options except -b.

A format string example can be formed as follow (this needs more discuss):

	"blabla %t\s%s\t%h\n%p\n%r\n\n"

	%t: type
	%s: size
	%h: sha1
	%p: pretty-print
	%r: raw-print

However, this change will give a heavy impact on many documents and scripts
depending on this command. There are 233 references in source code according
to a trivial count 'grep -r "cat-file" * | wc -l', not to mention many
private usage of this command.

So this is just a RFC. If I can get a very positive feedback from the
community, I may start to do the real code change.

Any ideas?

- Li Hong

Re: [RFC] 'git cat-file' needs a better design on its option interface

[Jeff King]

On Thu, Sep 24, 2009 at 11:04:31PM +0800, Li Hong wrote:

> When using 'git cat-file' recently, I find its option interface is somewhat
> inconvenient or mistakenly-designed.

Yes, the current interface has grown over time and kind of sucks. I
agree with all of your complaints.

That being said, the reason it has grown in that way is that as a
plumbing command, cat-file must retain backwards compatibility so as not
to break existing scripts which make use of it. And it is not enough to
look through git.git and fix all of our scripts; the interface to
cat-file is a public one, and we must take care not to break other
people's custom scripts.

I'm not quite sure where your complaints are coming from. Do you want:

  1. Something more sane to type in your terminal for everyday use? Then
     you probably want to use (or invent) some sort of user-facing
     porcelain that does a similar thing. This is mostly covered by "git
     show" these days, but if there is something lacking, proposals
     describing your use case would be welcome.

  2. To script around cat-file, but there is some action you want to do
     that is missing from the interface? In that case, can you describe
     your use case in more detail, and exactly what addition you want to
     make to the cat-file interface to accomodate it?

  3. To just clean up cruft from the interface for your scripts? I am
     somewhat sympathetic to wanting a nicer interface. But keep in
     mind that we have to keep the old interface around to support
     historical scripts. So while your new interface may be more
     flexible and less complex, you have to consider whether having
     _both_ interfaces will actually be less complex in the long run.

-Peff

Re: [RFC] 'git cat-file' needs a better design on its option interface

[Linus Torvalds]

On Thu, 24 Sep 2009, Li Hong wrote:
> 
> When using 'git cat-file' recently, I find its option interface is somewhat
> inconvenient or mistakenly-designed.

You likely shouldn't use 'cat-file' at all. Have you looked at 'git show'? 
That's the command meant for human beings.

'git cat-file' is really really low-level plumbing. Humans should 
generally never use it. It's one of the original git commands (it was 
literally in the original git commit), and it does some really low-level 
stuff that is good for scripting but not for any normal use.

		Linus

Re: [RFC] 'git cat-file' needs a better design on its option interface

[Matthieu Moy]

Linus Torvalds <torvalds@linux-foundation.org> writes:

> 'git cat-file' is really really low-level plumbing. Humans should 
> generally never use it.

... except to understand Git better ;-). I enjoyed being able to to a
'git cat-file' on a tree or commit object when I started with Git.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: [RFC] 'git cat-file' needs a better design on its option interface

[Nicolas Pitre]

On Thu, 24 Sep 2009, Matthieu Moy wrote:

> Linus Torvalds <torvalds@linux-foundation.org> writes:
> 
> > 'git cat-file' is really really low-level plumbing. Humans should 
> > generally never use it.
> 
> ... except to understand Git better ;-). I enjoyed being able to to a
> 'git cat-file' on a tree or commit object when I started with Git.

In the context of learning git at that level, the current option 
interface for cat-file shouldn't look too strange though.


Nicolas

Re: [RFC] 'git cat-file' needs a better design on its option interface

[Li Hong]

2009/9/25 Linus Torvalds <torvalds@linux-foundation.org>:
>
>
> On Thu, 24 Sep 2009, Li Hong wrote:
>>
>> When using 'git cat-file' recently, I find its option interface is somewhat
>> inconvenient or mistakenly-designed.
>
> You likely shouldn't use 'cat-file' at all. Have you looked at 'git show'?
> That's the command meant for human beings.
>
> 'git cat-file' is really really low-level plumbing. Humans should
> generally never use it. It's one of the original git commands (it was
> literally in the original git commit), and it does some really low-level
> stuff that is good for scripting but not for any normal use.
>
>                Linus
>

Yes, I know 'git show' and use it mostly. I just think the interface
of 'cat-file'
is not well designed even used by other scripts or porcelains. But from another
respect, it doesn't really annoy normal users much and we should retain
backwards compatibility. So I give up.

Thanks for all your feedbacks.

-Li Hong