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

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Nov 12, 2012, 15:38 UTC
Message-ID: <20121112153855.GA3546@elie.Belkin>
In-Reply-To: <CALkWK0nR_9mWDKzKygR379x3L=d4bGKKo27AP-2Y=+coc7H+sQ@mail.gmail.com>

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