threads / patch / 32068

patchDocumentation/log: fix description of format.pretty

Subject: [PATCH] Documentation/log: fix description of format.pretty

## tl;dr

5 messages between Nov 11, 2012 and Nov 12, 2012. Diffs are folded; open one to read it.

replies: 4people: 3as markdown or json

Ramkumar Ramachandra· Nov 11, 2012, 11:27 UTC · lore

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 <artagnon@gmail.com>
---
 Documentation/git-log.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Show changes to Documentation/git-log.txt +1 −1
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· Nov 12, 2012, 08:05 UTC · re: Ramkumar Ramachandra · lore

Re: [PATCH] Documentation/log: fix description of format.pretty

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· Nov 12, 2012, 09:39 UTC · re: Jonathan Nieder · lore

Re: [PATCH] Documentation/log: fix description of format.pretty

Hi Jonathan,
Jonathan Nieder wrote:
Show 9 quoted lines
> 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· Nov 12, 2012, 15:38 UTC · re: Ramkumar Ramachandra · lore

Re: [PATCH] Documentation/log: fix description of format.pretty

Ramkumar Ramachandra wrote:
Show 8 quoted lines
> 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· Nov 12, 2012, 17:42 UTC · re: Jonathan Nieder · lore

Re: [PATCH] Documentation/log: fix description of format.pretty

Jonathan Nieder <jrnieder@gmail.com> writes:
Show 10 quoted lines
> 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.
Show 11 quoted lines
> ... 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.

← back to recent threads