Re: [GSoC RFC PATCH v4 1/4] repo: declare the repo command

From: Karthik Nayak <karthik.188@gmail.com>
Date: Jul 15, 2025, 11:52 UTC
Message-ID: <CAOLa=ZSgmRK_59BBj4UMhKmksP0WARneOzpLxfMytbeXNzoqug@mail.gmail.com>
In-Reply-To: <20250714235231.10137-2-lucasseikioshiro@gmail.com>

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

Show 10 quoted lines

> Currently, `git rev-parse` covers a wide range of functionality not
> directly related to parsing revisions, as its name says. Over time,
> many features like parsing datestrings, options, paths, and others
> were added to it because there wasn't a more appropriated command
> to place them.
>
> Create a new Git command called `repo`. `git repo` will be the main
> command for obtaining the information about a repository (such as
> metadata and metrics), returning them in a machine readable format
> following the syntax "field<LF>value<NUL>".

I don't think we should enforce a syntax on the command level, but rather we should enforce it on the sub-command level. This way any new command, let's say `git repo stats` can provide a more suitable output. Which could be a more human readable format mimicking 'git-sizer'.

By not enforcing on a command level, we leave it extendable.

Show 14 quoted lines

>
> Also declare a subcommand for `repo` called `info`. `git repo info`
> will bring the functionality of retrieving repository-related
> information currently returned by `rev-parse`.
>
> Also add entries for this new command in:
>
> - the build files (Makefile, meson.build, Documentation/meson.build)
> - builtin.h
> - git.c
> - .gitignore
> - command-list.txt
> - Documentation
>

Nit: While it is good to state what this patch does, this list is
similar to the diffstat below. Is there additional information it is
providing?

Perhaps:

  We add the required tests, documentation and build changes to enable
  usage of this subcommand.

would suffice?

Show 54 quoted lines

> Helped-by: Phillip Wood <phillip.wood@dunelm.org.uk>
> Helped-by: Junio C Hamano <gitster@pobox.com>
> Helped-by: Justin Tobler <jltobler@gmail.com>
> Mentored-by: Karthik Nayak <karthik.188@gmail.com>
> Mentored-by: Patrick Steinhardt <ps@pks.im>
> Signed-off-by: Lucas Seiki Oshiro <lucasseikioshiro@gmail.com>
> ---
>  .gitignore                  |  1 +
>  Documentation/git-repo.adoc | 54 +++++++++++++++++++++++++++++++++++++
>  Documentation/meson.build   |  1 +
>  Makefile                    |  1 +
>  builtin.h                   |  1 +
>  builtin/repo.c              | 38 ++++++++++++++++++++++++++
>  command-list.txt            |  1 +
>  git.c                       |  1 +
>  meson.build                 |  1 +
>  9 files changed, 99 insertions(+)
>  create mode 100644 Documentation/git-repo.adoc
>  create mode 100644 builtin/repo.c
>
> diff --git a/.gitignore b/.gitignore
> index 04c444404e..1803023427 100644
> --- a/.gitignore
> +++ b/.gitignore
> @@ -139,6 +139,7 @@
>  /git-repack
>  /git-replace
>  /git-replay
> +/git-repo
>  /git-request-pull
>  /git-rerere
>  /git-reset
> diff --git a/Documentation/git-repo.adoc b/Documentation/git-repo.adoc
> new file mode 100644
> index 0000000000..6f8fe3f6ea
> --- /dev/null
> +++ b/Documentation/git-repo.adoc
> @@ -0,0 +1,54 @@
> +git-repo(1)
> +===========
> +
> +NAME
> +----
> +git-repo - Retrieve information about a repository
> +
> +SYNOPSIS
> +--------
> +[synopsis]
> +git repo info [<key>...]
> +
> +DESCRIPTION
> +-----------
> +Retrieve information about the current repository in a machine-readable format.
> +

I would keep the description of the command short, to:

  This command retrieve repository level information.

The `machine-readable` format is a implementation detail of the 'git-repo info' subcommand.

Show 16 quoted lines

> +`git repo` will be the primary tool to query repository-specific information,
> +such as metadata that currently can also be done by calling `git rev-parse` (see
> +linkgit:git-rev-parse[1]). `git repo` doesn't query information unrelated to the
> +current repository or that is already retrieved by a specialized command, for
> +example, `git config` (see linkgit:git-config[1]) or `git var` (see
> +linkgit:git-var[1]).
> +
> +This command returns the retrieved data following a null-terminated format with
> +this syntax:
> ++
> +----------------
> +key1<LF>value1<NUL>
> +key2<LF>value2<NUL>
> +...
> +----------------
>

Shouldn't this whole section be below the 'info' subcommand?

Show 23 quoted lines

> ++
> +THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.
> +
> +COMMANDS
> +--------
> +info [<key>...]::
> +	Retrieve metadata-related information about the current repository. Only
> +	the requested data will be returned based on their keys (see "INFO KEYS"
> +	section below).
> +
> +INFO KEYS
> +---------
> +
> +The set of data that `git repo` can return is grouped into the following
> +categories:
> +
> +SEE ALSO
> +--------
> +linkgit:git-rev-parse[1]
> +
> +GIT
> +---
> +Part of the linkgit:git[1] suite

[snip]