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

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

[Henry Qin]

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

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

[Kristoffer Haugsbakk]

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.

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

[Henry Qin]

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:
>
> 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.