Re: [RFC/PATCH] revision.c: add --format option for 'git log'

On Sun, Feb 22, 2009 at 7:53 PM, Junio C Hamano [off-list ref] wrote:

Felipe Contreras [off-list ref] writes:

quoted

On Sun, Feb 22, 2009 at 6:49 PM, Junio C Hamano [off-list ref] wrote:

quoted

Felipe Contreras [off-list ref] writes:

quoted

--format=:foo is a shorthand for --pretty=tformat:foo, otherwise this
new option acts just like --pretty=foo, except it's more intuitive for
users of 'git log'.

It's been quite a long time since the earlier discussion, but I wonder why
you need the colon before "foo" for this new shorthand.  I *think* you are
also introducing "--format=short" as a synonym to "--pretty=short", but
I do not think it is necessary.

Well, my hope was to replace --pretty=short with --format=short, but
you said that would break other scripts.

It is not just scripts you break.  You also break people's trained
fingers.

You can specify the kind of canned pretty printing with --pretty=short,
and it is not any longer to type than --format.  For use in scripts that
you write once and forget, there is no need to even apply this patch.

The only reason why new --format=<fmt> could be an useful addition is
because --pretty=format:<fmt> may be too long to type interactively.

That's not the main reason I suggested the change.

At least to me (and other people agreed on the original thread), when
I want to see the output of 'git log' in a different format the first
thing that pops into my mind is 'git log --format=foo'. The other
command I can recall right now that has something similar is 'find',
which has a 'printf' option, but 'find' can do much more than just
output stuff, like -delete, 'git log' on the other hand only prints
stuff, so --printf would not make sense, so only the f (format)
remains.

'git log --pretty=foo' is very unintuitive, no one would ever find
that option by intuition. Are there different kinds of pretties? Is
the default behavior --ugly?

Maybe 'git log --pretty' makes sense, but not 'git log --pretty=medium'.

quoted

quoted

quoted

As discussed in the mailing list, this is implemented as an undocumented
option.

Maybe somebody wants to document it.

Ah, I would gladly add the documentation, shall I write that it's an
'alternative' option similar to --pretty?

I do not think we want to introduce a new way to say the same thing for
the canned short options; "alternative" is not a good word for it.

Putting it in another way...

The output format is controlled by --pretty, which knows a set of canned
output formats.  You can specify --format=<fmt> if you want something
different from any of the canned format.  If your git does not support
this new notation, you can say --pretty=tformat:<fmt> to get the same
effect.  The old --pretty=tformat:<fmt> (and --pretty=format:<fmt>) is not
deprecated in any way.

Again, I don't see why 'canned format' == 'pretty' while 'custom
format' == 'format'. All this wording seems to suggest the canned
formats are pretty, while the custom formats are not.

I understand the option should be kept for people that are used to it,
but I don't think new users should suffer because of historic reasons.
And actually I believe many current users would not find
--pretty=email more natural than --format=email.

Cheers.

-- 
Felipe Contreras