patchrepo: add -z as an alias for --format=nul to git-repo-structure

Other Git commands that have nul-terminated output, such as git-config, git-status, git-ls-files, and git-repo-info have a flag `-z` for using the null character as the record separator.

Add the `-z` flag to git-repo-structure as an alias for `--format=nul`, making it consistent with the behavior of the other commands.

Signed-off-by: Lucas Seiki Oshiro <lucasseikioshiro@gmail.com>
---

Hello, again!

Since git-repo-info and git-repo-structure share the same format parser, this could be done by only copying the OPT_CALLBACK_F from repo_info.

I'm cc'ing Justin here, as he was the author of git-repo-structure.

This patch is based on top of master b31ab939fe (The fourth batch, 2025-11-26) with lo/repo-info-all merged.

 Documentation/git-repo.adoc | 5 +++--
 builtin/repo.c              | 6 +++++-
 t/t1901-repo-structure.sh   | 6 ++++++
 3 files changed, 14 insertions(+), 3 deletions(-)

Lucas Seiki Oshiro <lucasseikioshiro@gmail.com> writes:

It's a minor thing but I wonder if this should be more like

    git repo structure [--format=(table|keyvalue|nul) | -z]

Didn't you want to check "-z", not "--format=nul"? In addition, perhaps test

	# "-z", as a synonym to "--format=nul", participates in the
	# usual "last one wins" rule.
	git repo structure --format=table -z >out 2>err &&

as well, or is it too obvious (by knowing how parse-options API is used) that it is pointless to test?

On Sun, Nov 30, 2025 at 06:21:21PM -0800, Junio C Hamano wrote:

This discussion rings a bell -- didn't we already discuss this for `git repo info`? Yup, indeed [1]. Initial versions of `git repo info `-z` also had it formatted like the above, but the discussion eventually led to a version that is the same as the one proposed in this patch here.

I think this ultimately stems from [2], where you argue that it _is_ possible to say `git repo info --format=table -z`, and the last option wins. It's the same for `git repo structure`, so I'd argue we should be consistent.

[1]: <20250820144247.79197-1-lucasseikioshiro@gmail.com> [2]: <xmqqcy8frqn2.fsf@gitster.g>

I think it wouldn't be pointless given the above -- we should verify that the last one wins, regardless of whether you use the alias or the long option.

Patrick

Yeah, I agree. I'm also ok with `[--format ... | -z]`, but given that this argument parsing git-repo-stucture is the same from git-repo-info, it wouldn't make sense that their synopses differ.

Patrick Steinhardt <ps@pks.im> writes:

I do not think so; [2] was about the explicit "--format=nul and -z are incompatible" code. Even without this '-z" thing, if you have

    [--opt=(a|b|c)]

I _think_ our intention is to allow "git cmd --opt=a --opt=b" from the user and let the last one win. If you add "-z",

    [--format=(table|keyvalue|nul)] [-z]
    [--format=(table|keyvalue|nul) | -z]

I think both would mean the same thing; I just was wonering if grouping them together in one bracket makes it more obvious that these are all options to control the output format.

There was also an inquiry about writing it like

    [(--format=(table|keyvalue|nul) | -z)]

or even

    [(--format=(table|keyvalue|nul) | -z)...]

as these can be repeated and let the last-one-wins rule decide the final outcome, but we do not do that. I thought the final comment on this was in

https://lore.kernel.org/git/6186055.lOV4Wx5bFT@cayenne/

where the message said

    In fact the correct formatting is:

    [--format=(keyvalue|nul) | -z] [<key>...]

    As stated in "CodingGuidelines:

     Use spacing around "|" token(s), but not immediately after opening or
     before closing a [] or () pair:
       Do: [-q | --quiet]
       Don't: [-q|--quiet]

     Don't use spacing around "|" tokens when they're used to separate the
     alternate arguments of an option:
        Do: --track[=(direct|inherit)]
        Don't: --track[=(direct | inherit)]

and that was where the thread ended, I think.

Actually, the final comment was [1], after the version where I use `[--format=...] [-z]`.

But actually, I don't have a strong opinion on using `| -z` vs using `[-z]`, since both work here, but if `| -z` looks clearer, I can change it in the next version. However, I'll do that for both repo-info and repo-structure, since --format is parsed by the same function in both of them.

[1]: <xmqqms7cltak.fsf@gitster.g <mailto:xmqqms7cltak.fsf@gitster.g>>

On 25/11/30 04:59PM, Lucas Seiki Oshiro wrote:

Thanks Lucas, looks like you beat me to this change. :)

Any reason this isn't just based on master? It looks like this patch should apply just fine as I don't see any dependencies.

If we want to match the format in the section prior, we should add a '+' character on the prior line to separate the sections. With how it is written now, this line will just be appeneded to the previous section.

Reusing the same `parse_format_cb()` makes sense and also matches what we do with git-repo-info. Looks good.

Did you mean to use the -z option here?

-Justin

Hi!

Yesterday, lo/repo-info-all wasn't merged yet to master :-)

Yes, this callback is used by both subcommands, this was a really straightforward change.

Ooops, yes, sorry. I'll fix it.

Hi!

The main objective of this patchset is to add -z to git-repo-structure as an alias for --format=nul. I'm including two other related patches here:

- a patch removing an extra line in the documentation, which was leaking an + to
  the generated files

- a patch replacing `[--format=...] [-z]` by `[--format=... | -z]` in
  git-repo-info's synopsis

Lucas Seiki Oshiro (3):
  repo: remove blank line from Documentation/git-repo.adoc
  repo: use [--format=... | -z] instead of [-z] in git-repo-info
    synopsis
  repo: add -z as an alias for --format=nul to git-repo-structure

 Documentation/git-repo.adoc | 11 ++++++-----
 builtin/repo.c              |  8 ++++++--
 t/t1901-repo-structure.sh   |  7 +++++++
 3 files changed, 19 insertions(+), 7 deletions(-)

Range-diff against v1:
-:  ---------- > 1:  bfd4ff5db0 repo: remove blank line from Documentation/git-repo.adoc
-:  ---------- > 2:  e5eac8713c repo: use [--format=... | -z] instead of [-z] in git-repo-info synopsis
1:  f051cd41de ! 3:  0ccec7037d repo: add -z as an alias for --format=nul to git-repo-structure
    @@ Documentation/git-repo.adoc
     @@ Documentation/git-repo.adoc: SYNOPSIS
      --------
      [synopsis]
    - git repo info [--format=(keyvalue|nul)] [-z] [--all | <key>...]
    + git repo info [--format=(keyvalue|nul) | -z] [--all | <key>...]
     -git repo structure [--format=(table|keyvalue|nul)]
    -+git repo structure [--format=(table|keyvalue|nul)] [-z]
    ++git repo structure [--format=(table|keyvalue|nul) | -z]
      
      DESCRIPTION
      -----------
    @@ Documentation/git-repo.adoc: supported:
      `-z` is an alias for `--format=nul`.
      
     -`structure [--format=(table|keyvalue|nul)]`::
    -+`structure [--format=(table|keyvalue|nul)] [-z]`::
    ++`structure [--format=(table|keyvalue|nul) | -z]`::
      	Retrieve statistics about the current repository structure. The
      	following kinds of information are reported:
      +
    @@ Documentation/git-repo.adoc: supported:
      	the delimiter between the key and value instead of '='. Unlike the
      	`keyvalue` format, values containing "unusual" characters are never
      	quoted.
    +++
     +`-z` is an alias for `--format=nul`.
      
      INFO KEYS
    @@ builtin/repo.c
     @@
      
      static const char *const repo_usage[] = {
    - 	"git repo info [--format=(keyvalue|nul)] [-z] [--all | <key>...]",
    + 	"git repo info [--format=(keyvalue|nul) | -z] [--all | <key>...]",
     -	"git repo structure [--format=(table|keyvalue|nul)]",
    -+	"git repo structure [--format=(table|keyvalue|nul)] [-z]",
    ++	"git repo structure [--format=(table|keyvalue|nul) | -z]",
      	NULL
      };
      
    @@ t/t1901-repo-structure.sh: test_expect_success 'keyvalue and nul format' '
     +		test_cmp expect_nul out &&
     +		test_line_count = 0 err &&
     +
    -+		# Check -z
    -+		git repo structure --format=nul >out 2>err &&
    ++		# "-z", as a synonym to "--format=nul", participates in the
    ++		# usual "last one wins" rule.
    ++		git repo structure --format=table -z >out 2>err &&
     +
      		test_cmp expect_nul out &&
      		test_line_count = 0 err

There was an extra blank line in git-repo-structure documentation, which led to an unwawnted '+' character after generating an HTML or PDF from that page. This can be seen, for example, in Git 2.52.0 online docs [1].

Remove that extra line.

[1] https://git-scm.com/docs/git-repo/2.52.0

Signed-off-by: Lucas Seiki Oshiro <lucasseikioshiro@gmail.com>
---
 Documentation/git-repo.adoc | 1 -
 1 file changed, 1 deletion(-)

The flag -z is only an alias for --format=null and even though --format and -z can be used together and repeated, only the last one is considered.

Replace `[-z]` in the synopsis of git-repo-info by `[--format=... | -z]`, expliciting that the use of one of those flags replace the other.

Signed-off-by: Lucas Seiki Oshiro <lucasseikioshiro@gmail.com>
---
 Documentation/git-repo.adoc | 4 ++--
 builtin/repo.c              | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

Other Git commands that have nul-terminated output, such as git-config, git-status, git-ls-files, and git-repo-info have a flag `-z` for using the null character as the record separator.

Add the `-z` flag to git-repo-structure as an alias for `--format=nul`, making it consistent with the behavior of the other commands.

Signed-off-by: Lucas Seiki Oshiro <lucasseikioshiro@gmail.com>
---
 Documentation/git-repo.adoc | 6 ++++--
 builtin/repo.c              | 6 +++++-
 t/t1901-repo-structure.sh   | 7 +++++++
 3 files changed, 16 insertions(+), 3 deletions(-)

Lucas Seiki Oshiro <lucasseikioshiro@gmail.com> writes:

Not limited to this step, but I have a couple of comments.

 * Instead of munging the expected file so that it contains a NUL,
   and compare the actual output with it, munge the NUL terminated
   outout to make it text and compare with the expected file in text
   format.  This matters when tests start to fail as test_cmp will
   show the "diff" output when it fails, and comparing NUL
   terminated files, which are "binary" in the eyes of the "diff"
   utility.

 * I see your -z output is "<key> LF <value> NUL", but was there a
   particular reason why "<key> NUL <value> NUL" was not chosen?
   Unless there is a compelling reason not to, it would be a lot
   more future-proof to use NUL for both, primarily because it would
   allow future developers to include arbitrary non-NUL bytes in the
   <key> part in the future (and we wouldn't know what end-user
   controlled substring they may want to add).

Hi, Junio!

Ok! I'll do that in the next version.

This was a suggestions by Phillip Wood [1]. We've chosen this format following the format of git-config.

[1] https://lore.kernel.org/git/223c7cbd-610e-49e2-90e2-5914cbc0f1d7@gmail.com/

On Thu, Dec 04, 2025 at 05:10:09PM -0300, Lucas Seiki Oshiro wrote:

This version looks good to me, thanks!

Patrick