Search code examples
gitgit-log

Why must `git log --pretty` be followed by an equal mark?

Why does:

$ git log --pretty "format:%h %s"
fatal: invalid object name 'format'.

fail but both:

git log --pretty="format:%h %s"
git log --author bob

succeed? Why is the first line wrong? The first just looks like the third one, but it doesn't work.

Solution

  • That’s the inherent ambiguity of command-line options with optional values. --pretty is one, unfortunately:

    --pretty[=<format>]

    […] When =<format> part is omitted, it defaults to medium.

    git log --pretty "format:%h %s" treats format:%h %s as a non-option argument (the revision range). git log --pretty="format:%h %s" unambiguously gives --pretty a value and has no non-option arguments.

    gitcli(7) convention: “stuck form”

    According to man gitcli (git version 2.46.1):

    When a command-line option takes an argument, use the stuck form. In other words, write git foo -oArg instead of git foo -o Arg for short options, and git foo --long-opt=Arg instead of git foo --long-opt Arg for long options. An option that takes optional option-argument must be written in the stuck form.