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

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: Feb 22, 2009, 18:14 UTC
Message-ID: <94a0d4530902221014i46e52542j2380386405b559e2@mail.gmail.com>
In-Reply-To: <7v63j2z7bh.fsf@gitster.siamese.dyndns.org>

On Sun, Feb 22, 2009 at 7:53 PM, Junio C Hamano <gitster@pobox.com> wrote:

Show 26 quoted lines

> Felipe Contreras <felipe.contreras@gmail.com> writes:
>
>> On Sun, Feb 22, 2009 at 6:49 PM, Junio C Hamano <gitster@pobox.com> wrote:
>>> Felipe Contreras <felipe.contreras@gmail.com> writes:
>>>
>>>> --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'.

Show 19 quoted lines

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