Re: [PATCH 0/4] rev-list: introduce NUL-delimited output mode
- From
D. Ben Knoble <ben.knoble@gmail.com>
- Date
- Mar 10, 2025, 22:38 UTC
- Message-ID
- <CALnO6CBh_pYiU0p6pSndJ8rdDiykqBkRgosyrO1QhaQ55BKrkQ@mail.gmail.com>
- In-Reply-To
- <20250310192829.661692-1-jltobler@gmail.com>
On Mon, Mar 10, 2025 at 3:32 PM Justin Tobler <jltobler@gmail.com> wrote:
Show 47 quoted lines
>
> When walking objects, git-rev-list(1) prints each object entry on a
> separate line in the form:
>
> <oid> LF
>
> Some options, such as `--objects`, may print additional information
> about the object on the same line:
>
> <oid> SP [<path>] LF
>
> In this mode, if the object path contains a newline it is truncated at
> the newline.
>
> When the `--missing={print,print-info}` option is provided, information
> about any missing objects encountered during the object walk are also
> printed in the form:
>
> ?<oid> [SP <token>=<value>]... LF
>
> where values containing LF or SP are printed in a token specific fashion
> so that the resulting encoded value does not contain either of these two
> problematic bytes. For example, missing object paths are quoted in the C
> style so they contain LF or SP.
>
> To make machine parsing easier, this series introduces a NUL-delimited
> output mode for git-rev-list(1) via a `-z` option following a suggestion
> from Junio in a previous thread[1]. In this mode, instead of LF, each
> object is delimited with two NUL bytes and any object metadata is
> separated with a single NUL byte. Examples:
>
> <oid> NUL NUL
> <oid> [NUL <path>] NUL NUL
> ?<oid> [NUL <token>=<value>]... NUL NUL
>
> In this mode, path and value info are printed as-is without any special
> encoding or truncation.
>
> For now this series only adds support for use with the `--objects` and
> `--missing` options. Usage of `-z` with other options is rejected, so it
> can potentially be added in the future.
>
> One idea I had, but did not implement in this version, was to also use
> the `<token>=<value>` format for regular non-missing object info while
> in the NUL-delimited mode. I could see this being a bit more flexible
> instead of relying strictly on order. Interested if anyone has thoughts
> on this. :)Without taking a deeper look, I think token=value has the benefit of being self-describing at the cost of more output bytes (which might matter over the wire, for example). Generally I like the idea; sometimes I find it troublesome having to parse prose manuals for the specifics of output formats like field order, especially when I end up coding a parser for the format. If the field order doesn’t matter to the consumer, then perhaps using ordered fields AWK-style is inappropriately terse?
OTOH, the -z format is for machines, and they don’t need human labels ;) [I think token labels would be a great parser-writing and debugging aid]
Best, Ben
Show 37 quoted lines
> > This series is structured as follows: > > - Patches 1 and 2 do some minor preparatory refactors. > > - Patch 3 adds the `-z` option to git-rev-list(1) to print > objects in a NUL-delimited fashion. Printed object paths with > the `--objects` option are also handled. > > - Patch 4 teaches the `--missing` option how to print info in a > NUL-delimited fashion. > > Thanks for taking a look, > -Justin > > [1]: <xmqq5xlor0la.fsf@gitster.g> > > Justin Tobler (4): > rev-list: inline `show_object_with_name()` in `show_object()` > rev-list: refactor early option parsing > rev-list: support delimiting objects with NUL bytes > rev-list: support NUL-delimited --missing option > > Documentation/rev-list-options.adoc | 26 +++++++++ > builtin/rev-list.c | 86 ++++++++++++++++++++++------- > revision.c | 8 --- > revision.h | 2 - > t/t6000-rev-list-misc.sh | 34 ++++++++++++ > t/t6022-rev-list-missing.sh | 30 ++++++++++ > 6 files changed, 155 insertions(+), 31 deletions(-) > > > base-commit: 87a0bdbf0f72b7561f3cd50636eee33dcb7dbcc3 > -- > 2.49.0.rc2 > >
-- D. Ben Knoble