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

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

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

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

On Thu, 24 Sep 2009, Li Hong wrote:

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

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

... 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.

On Thu, 24 Sep 2009, Matthieu Moy wrote:

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

Nicolas

2009/9/25 Linus Torvalds <torvalds@linux-foundation.org>:

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