Feature Request: Document the log format string equivalent of built-in formats

Hi folks,

I think it is useful to be able to take any of the pre-existing formats offered by `git log --format=<format>` and tweak it a little bit.

In order to do this efficiently, it's helpful to have the format string equivalent of each pretty format documented explicitly, together with any limitations in being able to replicate them using a format string..

The documentation in `man git-log` under PRETTY FORMATS is helpful but insufficient.

For example, I tried to reproduce the format `medium` and have the following:

git log --format='%C(auto)commit %H%d%nAuthor: %an <%ae>%nDate: %ad%n%n%w(0,4,4)%s%n%n%-b%-C()%n'

There are two differences I have observed, and I have not yet been able to determine whether it's even possible to correct them.

1. In my output, the ref names output by %d are added unconditionally,
while git log will suppress them when the output is a file, and shows
them when the output is a terminal.
2. In my output, I sometimes see a raw ^M symbol in commit messages,
but git log output does not show raw CR characters in its output even
when CRLF is in the commit message.

Thanks, ~Henry

Backlink:

https://stackoverflow.com/questions/79089206/is-it-possible-to-fully-replicate-the-default-behavior-of-git-log-with-a-format

I took a look at the code before today with search terms like

    CMIT_FMT_DEFAULT
    CMIT_FMT_MEDIUM,

And it looked to me that at least parts of it were implemented using regular code branching. I was thinking that maybe the built-in formats were defined just using the formatting primitives. But it didn’t look like that to me.

Thanks for backlinking! I had intended to link my SO question and then forgot.

That matches what I saw from reading the code as well. As far as I could tell, the `pretty_print_commit` function only calls `repo_format_commit_message` when `pp->fmt == CMIT_FMT_USERFORMAT`, and not at all the built-in formats.

Thus, we cannot infer the correct format string equivalent by simply reading the code, which is another reason why I think it's worth documenting the closest format string equivalent and its limitations. Ideally, the format string is powerful enough to replicate the built-in formats, but if it is not, then that is also worth documenting explicitly.

References: https://github.com/git/git/blob/ef8ce8f3d4344fd3af049c17eeba5cd20d98b69f/pretty.c#L2282 https://github.com/git/git/blob/ef8ce8f3d4344fd3af049c17eeba5cd20d98b69f/pretty.c#L2294

On Tue, Oct 15, 2024 at 11:06 AM Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com> wrote: