Jonathan Nieder <jrnieder@xxxxxxxxx> 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.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html