# [RFC/PATCH] revision.c: add --format option for 'git log' 23 messages from 2009-02-21 to 2009-02-24. Participants: Felipe Contreras, Junio C Hamano, Linus Torvalds, Jakub Narebski, Wincent Colaiuta, Nanako Shiraishi, Jeff King. Thread: https://gitlist.dev/t/17938 ## Felipe Contreras, 2009-02-21 15:26 Subject: [RFC/PATCH] revision.c: add --format option for 'git log' Message-ID: <1235230015-17641-1-git-send-email-felipe.contreras@gmail.com> URL: https://gitlist.dev/e/1235230015-17641-1-git-send-email-felipe.contreras%40gmail.com ``` --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'. As discussed in the mailing list, this is implemented as an undocumented option. The specifics of the implementation were suggested by Junio C Hamano. Signed-off-by: Felipe Contreras --- revision.c | 10 ++++++++++ 1 files changed, 10 insertions(+), 0 deletions(-) diff --git a/revision.c b/revision.c index 286e416..6796e39 100644 --- a/revision.c +++ b/revision.c @@ -1147,6 +1147,16 @@ static int handle_revision_opt(struct rev_info *revs, int argc, const char **arg } else if (!prefixcmp(arg, "--pretty=")) { revs->verbose_header = 1; get_commit_format(arg+9, revs); + } else if (!prefixcmp(arg, "--format=")) { + char *modified = NULL; + revs->verbose_header = 1; + if (arg[9] == ':') { + modified = xmalloc(strlen(arg+9) + 7 + 1); + strcpy(modified, "tformat"); + strcat(modified, arg+9); + } + get_commit_format(modified ? modified : arg+9, revs); + free(modified); } else if (!strcmp(arg, "--graph")) { revs->topo_order = 1; revs->rewrite_parents = 1; -- 1.6.1.3 ``` ## Junio C Hamano, 2009-02-22 16:49 Subject: Re: [RFC/PATCH] revision.c: add --format option for 'git log' Message-ID: <7vtz6m1knv.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7vtz6m1knv.fsf%40gitster.siamese.dyndns.org In-Reply-To: <1235230015-17641-1-git-send-email-felipe.contreras@gmail.com> ``` Felipe Contreras 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. > As discussed in the mailing list, this is implemented as an undocumented > option. Maybe somebody wants to document it. Needs trivial tests. > + } else if (!prefixcmp(arg, "--format=")) { > + char *modified = NULL; > + revs->verbose_header = 1; > + if (arg[9] == ':') { > + modified = xmalloc(strlen(arg+9) + 7 + 1); > + strcpy(modified, "tformat"); > + strcat(modified, arg+9); > + } > + get_commit_format(modified ? modified : arg+9, revs); > + free(modified); struct strbuf fmt = STRBUF_INIT; revs->verbose_header = 1; strbuf_addf(&fmt, "tformat:%s", arg + 9); get_commit_format(fmt.buf, revs); strbuf_release(&fmt); > } else if (!strcmp(arg, "--graph")) { > revs->topo_order = 1; > revs->rewrite_parents = 1; > -- > 1.6.1.3 ``` ## Felipe Contreras, 2009-02-22 17:18 Subject: Re: [RFC/PATCH] revision.c: add --format option for 'git log' Message-ID: <94a0d4530902220918oc6f8ab9vc1fd0b55cad014a2@mail.gmail.com> URL: https://gitlist.dev/e/94a0d4530902220918oc6f8ab9vc1fd0b55cad014a2%40mail.gmail.com In-Reply-To: <7vtz6m1knv.fsf@gitster.siamese.dyndns.org> ``` On Sun, Feb 22, 2009 at 6:49 PM, Junio C Hamano wrote: > Felipe Contreras 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. >> 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? > Needs trivial tests. All right. >> +     } else if (!prefixcmp(arg, "--format=")) { >> +             char *modified = NULL; >> +             revs->verbose_header = 1; >> +             if (arg[9] == ':') { >> +                     modified = xmalloc(strlen(arg+9) + 7 + 1); >> +                     strcpy(modified, "tformat"); >> +                     strcat(modified, arg+9); >> +             } >> +             get_commit_format(modified ? modified : arg+9, revs); >> +             free(modified); > >        struct strbuf fmt = STRBUF_INIT; >        revs->verbose_header = 1; >        strbuf_addf(&fmt, "tformat:%s", arg + 9); >        get_commit_format(fmt.buf, revs); >        strbuf_release(&fmt); Ah, I felt there must be a utility like that but I couldn't find examples of that. Thanks. -- Felipe Contreras ``` ## Junio C Hamano, 2009-02-22 17:53 Subject: Re: [RFC/PATCH] revision.c: add --format option for 'git log' Message-ID: <7v63j2z7bh.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7v63j2z7bh.fsf%40gitster.siamese.dyndns.org In-Reply-To: <94a0d4530902220918oc6f8ab9vc1fd0b55cad014a2@mail.gmail.com> ``` Felipe Contreras writes: > On Sun, Feb 22, 2009 at 6:49 PM, Junio C Hamano wrote: >> Felipe Contreras 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= could be an useful addition is because --pretty=format: may be too long to type interactively. >>> 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= 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: to get the same effect. The old --pretty=tformat: (and --pretty=format:) is not deprecated in any way. ``` ## Junio C Hamano, 2009-02-22 18:06 Subject: Re: [RFC/PATCH] revision.c: add --format option for 'git log' Message-ID: <7vy6vyxs6j.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7vy6vyxs6j.fsf%40gitster.siamese.dyndns.org In-Reply-To: <7v63j2z7bh.fsf@gitster.siamese.dyndns.org> ``` Junio C Hamano writes: > Felipe Contreras writes: > ... >> 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. > ... > The only reason why new --format= could be an useful addition is > because --pretty=format: may be too long to type interactively. An obvious alternative with lessor impact than your patch would be not to introduce an additional option --format, but just make ":" as a synonym to "tformat:". Then you can say "--pretty=:%h %s". You would need to type one colon more but that might conceptually be less confusing, when somebody is starting to learn git *after* this change, without knowing that we did not have --format in earlier versions, from the documentation and existing pages on various web sites. ``` ## Felipe Contreras, 2009-02-22 18:14 Subject: Re: [RFC/PATCH] revision.c: add --format option for 'git log' Message-ID: <94a0d4530902221014i46e52542j2380386405b559e2@mail.gmail.com> URL: https://gitlist.dev/e/94a0d4530902221014i46e52542j2380386405b559e2%40mail.gmail.com In-Reply-To: <7v63j2z7bh.fsf@gitster.siamese.dyndns.org> ``` On Sun, Feb 22, 2009 at 7:53 PM, Junio C Hamano wrote: > Felipe Contreras writes: > >> On Sun, Feb 22, 2009 at 6:49 PM, Junio C Hamano wrote: >>> Felipe Contreras 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= could be an useful addition is > because --pretty=format: 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'. >>>> 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= 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: to get the same > effect.  The old --pretty=tformat: (and --pretty=format:) 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 ``` ## Junio C Hamano, 2009-02-22 18:37 Subject: Re: [RFC/PATCH] revision.c: add --format option for 'git log' Message-ID: <7vbpsuxqpo.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7vbpsuxqpo.fsf%40gitster.siamese.dyndns.org In-Reply-To: <94a0d4530902221014i46e52542j2380386405b559e2@mail.gmail.com> ``` Felipe Contreras writes: > I understand the option should be kept for people that are used to it, It is not just that. New people should learn existing lingo, as that is the word used in the existing documentation and various random web pages, so that they can use the same language when they teach people who are newer than themselves. If the existing word was not pretty (that came from "pretty-formatting") but something unpronouncible like '--gzxfw=short", then your argument might make some sense, but there is no such "breakage we need to fix" here. ``` ## Felipe Contreras, 2009-02-22 18:55 Subject: Re: [RFC/PATCH] revision.c: add --format option for 'git log' Message-ID: <94a0d4530902221055g4e815a78oc0aa094304588ab7@mail.gmail.com> URL: https://gitlist.dev/e/94a0d4530902221055g4e815a78oc0aa094304588ab7%40mail.gmail.com In-Reply-To: <7vbpsuxqpo.fsf@gitster.siamese.dyndns.org> ``` On Sun, Feb 22, 2009 at 8:37 PM, Junio C Hamano wrote: > Felipe Contreras writes: > >> I understand the option should be kept for people that are used to it, > > It is not just that.  New people should learn existing lingo, as that is > the word used in the existing documentation and various random web pages, > so that they can use the same language when they teach people who are > newer than themselves. Yes, but the existing lingo is not perfect... I'm proposing this particular lingo to be changed. > If the existing word was not pretty (that came from "pretty-formatting") > but something unpronouncible like '--gzxfw=short", then your argument > might make some sense, but there is no such "breakage we need to fix" > here. It's not breakage that needs to be fixed, it's UI improvement, and one guideline is that the interface needs to be intuitive and natural (when possible). IMO pretty > gzxfw, but format > pretty. Don't you think that --format=email is more natural than --pretty=email? I think you are holding a bit too tight on the code reason why it's called --pretty, but users shouldn't need to see the code in order to understand why the naming of the options in git commands make sense. -- Felipe Contreras ``` ## Linus Torvalds, 2009-02-22 20:34 Subject: Re: [RFC/PATCH] revision.c: add --format option for 'git log' Message-ID: URL: https://gitlist.dev/e/alpine.LFD.2.00.0902221225080.3111%40localhost.localdomain In-Reply-To: <94a0d4530902221014i46e52542j2380386405b559e2@mail.gmail.com> ``` On Sun, 22 Feb 2009, Felipe Contreras wrote: > > '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? Historically, the default behaviour _was_ indeed --ugly. There was no native "git log" command per se, it was literally a script that did something like git-rev-list | git-diff-tree --stdin --pretty | $(PAGER) and the "--pretty" option was to tell git to give human-readable output from git-diff-tree rather than the harsh raw stuff. So yes, the default for git used to be "low-level plumbing commands for scripting", with some options to turn them pretty for the fleshies. Then we started having more options, so "--pretty" became "--pretty=xyz". But I do realize that without the historical background, none of this makes sense. And quite frankly, I do hate "--pretty=xyz" myself. I find myself wishing I could just write git log --oneline instead of "--pretty=oneline", and I wish "shortlog" was a pretty format instead of a command of its own. So at least personally, I would not object AT ALL to - leave the "--pretty=xyz" parsing for historical reasons - support "--format=xyz" too, because it does make sense (and it's unambiguous: a format without a '%' sign in it makes no sense, so there is no reason to have "--format=format:%s" - if we see an unrecognized "--