Re: [PATCH v4 5/5] format-rev: introduce builtin for on-demand pretty formatting

["Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com>]

On Thu, May 7, 2026, at 21:34, me myself wrote:
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>[snip]
> +[[io]]
> +INPUT AND OUTPUT FORMAT
> +-----------------------
> +
> +The command uses newlines for both input and output termination by
> +default. See the `-z`, `--null-output`, and `--null-input` options for
> +using _NUL_ character as the terminator.
> +
> +The mode `--stdin-mode=revs` outputs one formatted commit followed by
> +the terminator. This could either be called a _line_ or a _record_ in
> +case "line" is too suggestive of newline termination.
> +
> +Note that this means that the terminator character (newline or _NUL_)
> +acts as a _terminator_, not a _separator_. In other words, the final
> +line or record is also terminated by the terminator character.
> +
> +The mode `--stdin-mode=text` replaces each object name with the
> +formatted commit, i.e. the format `%s` would transform the object name
> +`abcdef012...` to `<subject>` without any termination. Like this:
> +
> +----
> +Did we not fix this in "<subject>"?
> +----
> +
> +Regarding input in this mode: using `-z` or `--null-input` makes sure
> +that _NUL_ characters in the input are passed through correctly.

This was the paragraph that I was unhappy with (see cover letter).

We’re supposed to be dealing with text here. So on second thought I
don’t think we need to fuzz about passing through NUL characters.

Instead I could mention that `-z` for this mode allows you to further
transform running text from other commands that use NUL
termination. Like `git last-modified -z` (see the Examples section).

> +
> +It is safe to interactively read and write from this command since each
> +record is immediately flushed.
> +
> +[[examples]]
> +EXAMPLES
> +--------
> +
> +The command linkgit:git-last-modified[1] shows the commit that each file
> +was last modified in.
>[snip]