{"thread":{"id":"17938","subject":"[RFC/PATCH] revision.c: add --format option for 'git log'","startedAt":"2009-02-21T15:26:55Z","lastAt":"2009-02-24T09:34:24Z","messageCount":23,"participants":["Felipe Contreras","Junio C Hamano","Linus Torvalds","Jakub Narebski","Wincent Colaiuta","Nanako Shiraishi","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"105725","messageId":"1235230015-17641-1-git-send-email-felipe.contreras@gmail.com","threadId":"17938","inReplyTo":null,"subject":"[RFC/PATCH] revision.c: add --format option for 'git log'","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-02-21T15:26:55Z","receivedAt":"2009-02-21T15:26:55Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"--format=:foo is a shorthand for --pretty=tformat:foo, otherwise this\nnew option acts just like --pretty=foo, except it's more intuitive for\nusers of 'git log'.\n\nAs discussed in the mailing list, this is implemented as an undocumented\noption. The specifics of the implementation were suggested by Junio C\nHamano.\n\nSigned-off-by: Felipe Contreras \n---\n revision.c | 10 ++++++++++\n 1 files changed, 10 insertions(+), 0 deletions(-)\n\ndiff --git a/revision.c b/revision.c\nindex 286e416..6796e39 100644\n--- a/revision.c\n+++ b/revision.c\n@@ -1147,6 +1147,16 @@ static int handle_revision_opt(struct rev_info *revs, int argc, const char **arg\n \t} else if (!prefixcmp(arg, \"--pretty=\")) {\n \t\trevs->verbose_header = 1;\n \t\tget_commit_format(arg+9, revs);\n+\t} else if (!prefixcmp(arg, \"--format=\")) {\n+\t\tchar *modified = NULL;\n+\t\trevs->verbose_header = 1;\n+\t\tif (arg[9] == ':') {\n+\t\t\tmodified = xmalloc(strlen(arg+9) + 7 + 1);\n+\t\t\tstrcpy(modified, \"tformat\");\n+\t\t\tstrcat(modified, arg+9);\n+\t\t}\n+\t\tget_commit_format(modified ? modified : arg+9, revs);\n+\t\tfree(modified);\n \t} else if (!strcmp(arg, \"--graph\")) {\n \t\trevs->topo_order = 1;\n \t\trevs->rewrite_parents = 1;\n-- \n1.6.1.3\n"},{"id":"105782","messageId":"7vtz6m1knv.fsf@gitster.siamese.dyndns.org","threadId":"17938","inReplyTo":"1235230015-17641-1-git-send-email-felipe.contreras@gmail.com","subject":"Re: [RFC/PATCH] revision.c: add --format option for 'git log'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-02-22T16:49:40Z","receivedAt":"2009-02-22T16:49:40Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Felipe Contreras writes:\n\n> --format=:foo is a shorthand for --pretty=tformat:foo, otherwise this\n> new option acts just like --pretty=foo, except it's more intuitive for\n> users of 'git log'.\n\nIt's been quite a long time since the earlier discussion, but I wonder why\nyou need the colon before \"foo\" for this new shorthand. I *think* you are\nalso introducing \"--format=short\" as a synonym to \"--pretty=short\", but\nI do not think it is necessary.\n\n> As discussed in the mailing list, this is implemented as an undocumented\n> option.\n\nMaybe somebody wants to document it.\n\nNeeds trivial tests.\n\n> +\t} else if (!prefixcmp(arg, \"--format=\")) {\n> +\t\tchar *modified = NULL;\n> +\t\trevs->verbose_header = 1;\n> +\t\tif (arg[9] == ':') {\n> +\t\t\tmodified = xmalloc(strlen(arg+9) + 7 + 1);\n> +\t\t\tstrcpy(modified, \"tformat\");\n> +\t\t\tstrcat(modified, arg+9);\n> +\t\t}\n> +\t\tget_commit_format(modified ? modified : arg+9, revs);\n> +\t\tfree(modified);\n\n\tstruct strbuf fmt = STRBUF_INIT;\n revs->verbose_header = 1;\n strbuf_addf(&fmt, \"tformat:%s\", arg + 9);\n get_commit_format(fmt.buf, revs);\n strbuf_release(&fmt);\n\n> \t} else if (!strcmp(arg, \"--graph\")) {\n> \t\trevs->topo_order = 1;\n> \t\trevs->rewrite_parents = 1;\n> -- \n> 1.6.1.3\n"},{"id":"105787","messageId":"94a0d4530902220918oc6f8ab9vc1fd0b55cad014a2@mail.gmail.com","threadId":"17938","inReplyTo":"7vtz6m1knv.fsf@gitster.siamese.dyndns.org","subject":"Re: [RFC/PATCH] revision.c: add --format option for 'git log'","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-02-22T17:18:12Z","receivedAt":"2009-02-22T17:18:12Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Sun, Feb 22, 2009 at 6:49 PM, Junio C Hamano wrote:\n> Felipe Contreras writes:\n>\n>> --format=:foo is a shorthand for --pretty=tformat:foo, otherwise this\n>> new option acts just like --pretty=foo, except it's more intuitive for\n>> users of 'git log'.\n>\n> It's been quite a long time since the earlier discussion, but I wonder why\n> you need the colon before \"foo\" for this new shorthand.  I *think* you are\n> also introducing \"--format=short\" as a synonym to \"--pretty=short\", but\n> I do not think it is necessary.\n\nWell, my hope was to replace --pretty=short with --format=short, but\nyou said that would break other scripts.\n\n>> As discussed in the mailing list, this is implemented as an undocumented\n>> option.\n>\n> Maybe somebody wants to document it.\n\nAh, I would gladly add the documentation, shall I write that it's an\n'alternative' option similar to --pretty?\n\n> Needs trivial tests.\n\nAll right.\n\n>> +     } else if (!prefixcmp(arg, \"--format=\")) {\n>> +             char *modified = NULL;\n>> +             revs->verbose_header = 1;\n>> +             if (arg[9] == ':') {\n>> +                     modified = xmalloc(strlen(arg+9) + 7 + 1);\n>> +                     strcpy(modified, \"tformat\");\n>> +                     strcat(modified, arg+9);\n>> +             }\n>> +             get_commit_format(modified ? modified : arg+9, revs);\n>> +             free(modified);\n>\n>        struct strbuf fmt = STRBUF_INIT;\n>        revs->verbose_header = 1;\n>        strbuf_addf(&fmt, \"tformat:%s\", arg + 9);\n>        get_commit_format(fmt.buf, revs);\n>        strbuf_release(&fmt);\n\nAh, I felt there must be a utility like that but I couldn't find\nexamples of that. Thanks.\n\n-- \nFelipe Contreras\n"},{"id":"105793","messageId":"7v63j2z7bh.fsf@gitster.siamese.dyndns.org","threadId":"17938","inReplyTo":"94a0d4530902220918oc6f8ab9vc1fd0b55cad014a2@mail.gmail.com","subject":"Re: [RFC/PATCH] revision.c: add --format option for 'git log'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-02-22T17:53:54Z","receivedAt":"2009-02-22T17:53:54Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Felipe Contreras writes:\n\n> On Sun, Feb 22, 2009 at 6:49 PM, Junio C Hamano wrote:\n>> Felipe Contreras writes:\n>>\n>>> --format=:foo is a shorthand for --pretty=tformat:foo, otherwise this\n>>> new option acts just like --pretty=foo, except it's more intuitive for\n>>> users of 'git log'.\n>>\n>> It's been quite a long time since the earlier discussion, but I wonder why\n>> you need the colon before \"foo\" for this new shorthand.  I *think* you are\n>> also introducing \"--format=short\" as a synonym to \"--pretty=short\", but\n>> I do not think it is necessary.\n>\n> Well, my hope was to replace --pretty=short with --format=short, but\n> you said that would break other scripts.\n\nIt is not just scripts you break. You also break people's trained\nfingers.\n\nYou can specify the kind of canned pretty printing with --pretty=short,\nand it is not any longer to type than --format. For use in scripts that\nyou write once and forget, there is no need to even apply this patch.\n\nThe only reason why new --format= could be an useful addition is\nbecause --pretty=format: may be too long to type interactively.\n\n>>> As discussed in the mailing list, this is implemented as an undocumented\n>>> option.\n>>\n>> Maybe somebody wants to document it.\n>\n> Ah, I would gladly add the documentation, shall I write that it's an\n> 'alternative' option similar to --pretty?\n\nI do not think we want to introduce a new way to say the same thing for\nthe canned short options; \"alternative\" is not a good word for it.\n\nPutting it in another way...\n\nThe output format is controlled by --pretty, which knows a set of canned\noutput formats. You can specify --format= if you want something\ndifferent from any of the canned format. If your git does not support\nthis new notation, you can say --pretty=tformat: to get the same\neffect. The old --pretty=tformat: (and --pretty=format:) is not\ndeprecated in any way.\n"},{"id":"105794","messageId":"7vy6vyxs6j.fsf@gitster.siamese.dyndns.org","threadId":"17938","inReplyTo":"7v63j2z7bh.fsf@gitster.siamese.dyndns.org","subject":"Re: [RFC/PATCH] revision.c: add --format option for 'git log'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-02-22T18:06:12Z","receivedAt":"2009-02-22T18:06:12Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Felipe Contreras writes:\n> ...\n>> Well, my hope was to replace --pretty=short with --format=short, but\n>> you said that would break other scripts.\n>\n> It is not just scripts you break. You also break people's trained\n> fingers.\n> ...\n> The only reason why new --format= could be an useful addition is\n> because --pretty=format: may be too long to type interactively.\n\nAn obvious alternative with lessor impact than your patch would be not to\nintroduce an additional option --format, but just make \":\" as a synonym to\n\"tformat:\". Then you can say \"--pretty=:%h %s\". You would need to type\none colon more but that might conceptually be less confusing, when\nsomebody is starting to learn git *after* this change, without knowing\nthat we did not have --format in earlier versions, from the documentation\nand existing pages on various web sites.\n"},{"id":"105802","messageId":"94a0d4530902221014i46e52542j2380386405b559e2@mail.gmail.com","threadId":"17938","inReplyTo":"7v63j2z7bh.fsf@gitster.siamese.dyndns.org","subject":"Re: [RFC/PATCH] revision.c: add --format option for 'git log'","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-02-22T18:14:09Z","receivedAt":"2009-02-22T18:14:09Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Sun, Feb 22, 2009 at 7:53 PM, Junio C Hamano wrote:\n> Felipe Contreras writes:\n>\n>> On Sun, Feb 22, 2009 at 6:49 PM, Junio C Hamano wrote:\n>>> Felipe Contreras writes:\n>>>\n>>>> --format=:foo is a shorthand for --pretty=tformat:foo, otherwise this\n>>>> new option acts just like --pretty=foo, except it's more intuitive for\n>>>> users of 'git log'.\n>>>\n>>> It's been quite a long time since the earlier discussion, but I wonder why\n>>> you need the colon before \"foo\" for this new shorthand.  I *think* you are\n>>> also introducing \"--format=short\" as a synonym to \"--pretty=short\", but\n>>> I do not think it is necessary.\n>>\n>> Well, my hope was to replace --pretty=short with --format=short, but\n>> you said that would break other scripts.\n>\n> It is not just scripts you break.  You also break people's trained\n> fingers.\n>\n> You can specify the kind of canned pretty printing with --pretty=short,\n> and it is not any longer to type than --format.  For use in scripts that\n> you write once and forget, there is no need to even apply this patch.\n>\n> The only reason why new --format= could be an useful addition is\n> because --pretty=format: may be too long to type interactively.\n\nThat's not the main reason I suggested the change.\n\nAt least to me (and other people agreed on the original thread), when\nI want to see the output of 'git log' in a different format the first\nthing that pops into my mind is 'git log --format=foo'. The other\ncommand I can recall right now that has something similar is 'find',\nwhich has a 'printf' option, but 'find' can do much more than just\noutput stuff, like -delete, 'git log' on the other hand only prints\nstuff, so --printf would not make sense, so only the f (format)\nremains.\n\n'git log --pretty=foo' is very unintuitive, no one would ever find\nthat option by intuition. Are there different kinds of pretties? Is\nthe default behavior --ugly?\n\nMaybe 'git log --pretty' makes sense, but not 'git log --pretty=medium'.\n\n>>>> As discussed in the mailing list, this is implemented as an undocumented\n>>>> option.\n>>>\n>>> Maybe somebody wants to document it.\n>>\n>> Ah, I would gladly add the documentation, shall I write that it's an\n>> 'alternative' option similar to --pretty?\n>\n> I do not think we want to introduce a new way to say the same thing for\n> the canned short options; \"alternative\" is not a good word for it.\n>\n> Putting it in another way...\n>\n> The output format is controlled by --pretty, which knows a set of canned\n> output formats.  You can specify --format= if you want something\n> different from any of the canned format.  If your git does not support\n> this new notation, you can say --pretty=tformat: to get the same\n> effect.  The old --pretty=tformat: (and --pretty=format:) is not\n> deprecated in any way.\n\nAgain, I don't see why 'canned format' == 'pretty' while 'custom\nformat' == 'format'. All this wording seems to suggest the canned\nformats are pretty, while the custom formats are not.\n\nI understand the option should be kept for people that are used to it,\nbut I don't think new users should suffer because of historic reasons.\nAnd actually I believe many current users would not find\n--pretty=email more natural than --format=email.\n\nCheers.\n\n-- \nFelipe Contreras\n"},{"id":"105809","messageId":"7vbpsuxqpo.fsf@gitster.siamese.dyndns.org","threadId":"17938","inReplyTo":"94a0d4530902221014i46e52542j2380386405b559e2@mail.gmail.com","subject":"Re: [RFC/PATCH] revision.c: add --format option for 'git log'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-02-22T18:37:55Z","receivedAt":"2009-02-22T18:37:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Felipe Contreras writes:\n\n> I understand the option should be kept for people that are used to it,\n\nIt is not just that. New people should learn existing lingo, as that is\nthe word used in the existing documentation and various random web pages,\nso that they can use the same language when they teach people who are\nnewer than themselves.\n\nIf the existing word was not pretty (that came from \"pretty-formatting\")\nbut something unpronouncible like '--gzxfw=short\", then your argument\nmight make some sense, but there is no such \"breakage we need to fix\"\nhere.\n"},{"id":"105812","messageId":"94a0d4530902221055g4e815a78oc0aa094304588ab7@mail.gmail.com","threadId":"17938","inReplyTo":"7vbpsuxqpo.fsf@gitster.siamese.dyndns.org","subject":"Re: [RFC/PATCH] revision.c: add --format option for 'git log'","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2009-02-22T18:55:46Z","receivedAt":"2009-02-22T18:55:46Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Sun, Feb 22, 2009 at 8:37 PM, Junio C Hamano wrote:\n> Felipe Contreras writes:\n>\n>> I understand the option should be kept for people that are used to it,\n>\n> It is not just that.  New people should learn existing lingo, as that is\n> the word used in the existing documentation and various random web pages,\n> so that they can use the same language when they teach people who are\n> newer than themselves.\n\nYes, but the existing lingo is not perfect... I'm proposing this\nparticular lingo to be changed.\n\n> If the existing word was not pretty (that came from \"pretty-formatting\")\n> but something unpronouncible like '--gzxfw=short\", then your argument\n> might make some sense, but there is no such \"breakage we need to fix\"\n> here.\n\nIt's not breakage that needs to be fixed, it's UI improvement, and one\nguideline is that the interface needs to be intuitive and natural\n(when possible). IMO pretty > gzxfw, but format > pretty. Don't you\nthink that --format=email is more natural than --pretty=email? I think\nyou are holding a bit too tight on the code reason why it's called\n--pretty, but users shouldn't need to see the code in order to\nunderstand why the naming of the options in git commands make sense.\n\n-- \nFelipe Contreras\n"},{"id":"105821","messageId":"alpine.LFD.2.00.0902221225080.3111@localhost.localdomain","threadId":"17938","inReplyTo":"94a0d4530902221014i46e52542j2380386405b559e2@mail.gmail.com","subject":"Re: [RFC/PATCH] revision.c: add --format option for 'git log'","fromName":"Linus Torvalds","fromEmail":"torvalds@linux-foundation.org","sentAt":"2009-02-22T20:34:08Z","receivedAt":"2009-02-22T20:34:08Z","isPatch":true,"sender":{"key":"torvalds@linux-foundation.org","avatar":"https://avatars.githubusercontent.com/u/1024025?v=4"},"body":"\n\nOn Sun, 22 Feb 2009, Felipe Contreras wrote:\n>\n> 'git log --pretty=foo' is very unintuitive, no one would ever find\n> that option by intuition. Are there different kinds of pretties? Is\n> the default behavior --ugly?\n\nHistorically, the default behaviour _was_ indeed --ugly.\n\nThere was no native \"git log\" command per se, it was literally a script \nthat did something like\n\n\tgit-rev-list |\n\t\tgit-diff-tree --stdin --pretty |\n\t\t$(PAGER)\n\nand the \"--pretty\" option was to tell git to give human-readable output \nfrom git-diff-tree rather than the harsh raw stuff.\n\nSo yes, the default for git used to be \"low-level plumbing commands for \nscripting\", with some options to turn them pretty for the fleshies.\n\nThen we started having more options, so \"--pretty\" became \"--pretty=xyz\".\n\nBut I do realize that without the historical background, none of this \nmakes sense. And quite frankly, I do hate \"--pretty=xyz\" myself. I find \nmyself wishing I could just write\n\n\tgit log --oneline\n\ninstead of \"--pretty=oneline\", and I wish \"shortlog\" was a pretty format \ninstead of a command of its own.\n\nSo at least personally, I would not object AT ALL to\n\n - leave the \"--pretty=xyz\" parsing for historical reasons\n\n - support \"--format=xyz\" too, because it does make sense (and it's \n unambiguous: a format without a '%' sign in it makes no sense, so there \n is no reason to have \"--format=format:%s\"\n\n - if we see an unrecognized \"--