# [PATCH] Documentation/log: fix description of format.pretty 5 messages from 2012-11-11 to 2012-11-12. Participants: Ramkumar Ramachandra, Jonathan Nieder, Junio C Hamano. Thread: https://gitlist.dev/t/32068 ## Ramkumar Ramachandra, 2012-11-11 11:27 Subject: [PATCH] Documentation/log: fix description of format.pretty Message-ID: URL: https://gitlist.dev/e/CALkWK0%3DhdmYF2VoOZY4F7%2ByPD8D0rBnPY-tvp5pryRWp-0WBeg%40mail.gmail.com ``` 59893a88 (Documentation/log: add a CONFIGURATION section, 2010-05-08) mentioned that `format.pretty` is the default for the `--format` option. Such an option never existed, and the author meant `--pretty`. Make this correction. Signed-off-by: Ramkumar Ramachandra --- Documentation/git-log.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 585dac4..4b07ad4 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -148,7 +148,7 @@ See linkgit:git-config[1] for core variables and linkgit:git- for settings related to diff generation. format.pretty:: - Default for the `--format` option. (See "PRETTY FORMATS" above.) + Default for the `--pretty` option. (See "PRETTY FORMATS" above.) Defaults to "medium". i18n.logOutputEncoding:: -- 1.7.12.1.428.g652398a.dirty ``` ## Jonathan Nieder, 2012-11-12 08:05 Subject: Re: [PATCH] Documentation/log: fix description of format.pretty Message-ID: <20121112080527.GB3581@elie.Belkin> URL: https://gitlist.dev/e/20121112080527.GB3581%40elie.Belkin In-Reply-To: ``` Hi Ram, Ramkumar Ramachandra wrote: > 59893a88 (Documentation/log: add a CONFIGURATION section, 2010-05-08) > mentioned that `format.pretty` is the default for the `--format` > option. Such an option never existed, False. Have you tried it? Thanks, Jonathan ``` ## Ramkumar Ramachandra, 2012-11-12 09:39 Subject: Re: [PATCH] Documentation/log: fix description of format.pretty Message-ID: URL: https://gitlist.dev/e/CALkWK0nR_9mWDKzKygR379x3L%3Dd4bGKKo27AP-2Y%3D%2Bcoc7H%2BsQ%40mail.gmail.com In-Reply-To: <20121112080527.GB3581@elie.Belkin> ``` Hi Jonathan, Jonathan Nieder wrote: > Hi Ram, > > Ramkumar Ramachandra wrote: > >> 59893a88 (Documentation/log: add a CONFIGURATION section, 2010-05-08) >> mentioned that `format.pretty` is the default for the `--format` >> option. Such an option never existed, > > False. Have you tried it? Oops, I read about `--pretty` in pretty-formats.txt and didn't realize that `--format` existed. However, your patch is still wrong because there seems to be a subtle (and confusing) difference between `--pretty` and `--format`. In the latter, you can't omit the format, and expect it to be picked up from format.pretty: $ git log --format fatal: unrecognized argument: --format Instead, you have to specify the format explicitly: $ git log --format=medium So, we should change the commit message in my patch? Ram ``` ## Jonathan Nieder, 2012-11-12 15:38 Subject: Re: [PATCH] Documentation/log: fix description of format.pretty Message-ID: <20121112153855.GA3546@elie.Belkin> URL: https://gitlist.dev/e/20121112153855.GA3546%40elie.Belkin In-Reply-To: ``` Ramkumar Ramachandra wrote: > Oops, I read about `--pretty` in pretty-formats.txt and didn't realize > that `--format` existed. However, your patch is still wrong because > there seems to be a subtle (and confusing) difference between > `--pretty` and `--format`. In the latter, you can't omit the format, > and expect it to be picked up from format.pretty: > > $ git log --format > fatal: unrecognized argument: --format You can do $ git log and format.pretty will still take effect. In other words, setting format.pretty to "foo" is somewhat like making $ git log do $ git log --format=foo which is what the text is supposed to explain. It is based on the following text from Documentation/config.txt: format.pretty:: The default pretty format for log/show/whatchanged command, See linkgit:git-log[1], linkgit:git-show[1], linkgit:git-whatchanged[1]. I do imagine it can be made clearer. s/--format/--pretty/ does not go far enough --- it only replaces one confusing explanation with another. Hoping that clarifies, Jonathan ``` ## Junio C Hamano, 2012-11-12 17:42 Subject: Re: [PATCH] Documentation/log: fix description of format.pretty Message-ID: <7vwqxqk99g.fsf@alter.siamese.dyndns.org> URL: https://gitlist.dev/e/7vwqxqk99g.fsf%40alter.siamese.dyndns.org In-Reply-To: <20121112153855.GA3546@elie.Belkin> ``` Jonathan Nieder writes: > Ramkumar Ramachandra wrote: > >> Oops, I read about `--pretty` in pretty-formats.txt and didn't realize >> that `--format` existed. However, your patch is still wrong because >> there seems to be a subtle (and confusing) difference between >> `--pretty` and `--format`. In the latter, you can't omit the format, >> and expect it to be picked up from format.pretty: >> >> $ git log --format >> fatal: unrecognized argument: --format We probably should say "--format needs an argument" here. > ... It is based on the > following text from Documentation/config.txt: > > format.pretty:: > The default pretty format for log/show/whatchanged command, > See linkgit:git-log[1], linkgit:git-show[1], > linkgit:git-whatchanged[1]. > > I do imagine it can be made clearer. s/--format/--pretty/ does not go > far enough --- it only replaces one confusing explanation with > another. The --format and --pretty are more or less the same thing since 3a4c1a5 (Add --format that is a synonym to --pretty, 2009-02-24). The --format option was added as a synonym because majority of new users who have never heard of --pretty found it more natural; in that sense, Ram's patch goes backwards. The entry in config.txt came from 94c22a5 (log/show/whatchanged: introduce format.pretty configuration, 2008-03-02) that predates the synonym, and originally it was to allow [format] pretty = fuller to make "git log" by default use "git log --pretty=fuller" in the configuration; back then there wasn't a support for custom formats like [format] pretty = "%h %s" until 3640754 (Give short-hands to --pretty=tformat:%formatstring, 2009-02-24) introduced it. "The default pretty format" in the description was written to refer to the original "raw/medium/short/email/full/fuller" set, but these days, we accept anything that you can write after "--pretty=" (or its synonym "--format=") on the command line. This is one of the reasons why I do not want to see abbreviated descriptions for configuration variables duplicated in the manual pages of individual commands, as the practice tends to lead to this kind of confusion. ```