# [RFC] 'git cat-file' needs a better design on its option interface 6 messages from 2009-09-24 to 2009-09-25. Participants: Li Hong, Jeff King, Linus Torvalds, Matthieu Moy, Nicolas Pitre. Thread: https://gitlist.dev/t/21046 ## Li Hong, 2009-09-24 15:04 Subject: [RFC] 'git cat-file' needs a better design on its option interface Message-ID: <3a3680030909240804w1399ed7fhd6367300544f34f@mail.gmail.com> URL: https://gitlist.dev/e/3a3680030909240804w1399ed7fhd6367300544f34f%40mail.gmail.com ``` 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 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. 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 ] [-e] ... -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 ``` ## Jeff King, 2009-09-24 16:48 Subject: Re: [RFC] 'git cat-file' needs a better design on its option interface Message-ID: <20090924164834.GB5655@coredump.intra.peff.net> URL: https://gitlist.dev/e/20090924164834.GB5655%40coredump.intra.peff.net In-Reply-To: <3a3680030909240804w1399ed7fhd6367300544f34f@mail.gmail.com> ``` 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 ``` ## Linus Torvalds, 2009-09-24 17:23 Subject: Re: [RFC] 'git cat-file' needs a better design on its option interface Message-ID: URL: https://gitlist.dev/e/alpine.LFD.2.01.0909241021120.3303%40localhost.localdomain In-Reply-To: <3a3680030909240804w1399ed7fhd6367300544f34f@mail.gmail.com> ``` 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 ``` ## Matthieu Moy, 2009-09-24 19:21 Subject: Re: [RFC] 'git cat-file' needs a better design on its option interface Message-ID: URL: https://gitlist.dev/e/vpqy6o4kv24.fsf%40bauges.imag.fr In-Reply-To: ``` Linus Torvalds 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/ ``` ## Nicolas Pitre, 2009-09-24 19:30 Subject: Re: [RFC] 'git cat-file' needs a better design on its option interface Message-ID: URL: https://gitlist.dev/e/alpine.LFD.2.00.0909241528110.4997%40xanadu.home In-Reply-To: ``` On Thu, 24 Sep 2009, Matthieu Moy wrote: > Linus Torvalds 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 ``` ## Li Hong, 2009-09-25 02:33 Subject: Re: [RFC] 'git cat-file' needs a better design on its option interface Message-ID: <3a3680030909241933g5ac48496ic9673030de81898c@mail.gmail.com> URL: https://gitlist.dev/e/3a3680030909241933g5ac48496ic9673030de81898c%40mail.gmail.com In-Reply-To: ``` 2009/9/25 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 > 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 ```