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

    [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
More majordomo info at

Reply via email to