Subject: [GSoC RFC PATCH 0/5] repo-info: add new command for retrieving repository info

From: Lucas Seiki Oshiro <[email-masked]>
Date: Tue, 10 Jun 2025 12:21:12 -0300

Hi!

This is the first RFC for my GSoC project: the new command `repo-info`.

## Motivation

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.

This way, many of these features would be better placed in new and dedicated
commands. This kind of movement had other precedents in Git, for example, `git
switch` and `git restore` were created after `git checkout` became too
overloaded.

## Proposal

This patchset introduces a new command `git repo-info`. Its goal is to bring the
functionality of retrieving repository-related information currently returned by
`rev-parse`, displaying them in machine-readable formats (like JSON or plaintext).

Under `rev-parse`, these information is retrieved by using these flags
(described in the section "Options for Files" of `rev-parse`'s documentation):

- `--show-object-format`: the hashing algorithm (i.e. `sha1` or `sha256`)

- `--git-dir`: The Git directory of the repository

- `--git-common-dir`: The common Git directory

- `--show-toplevel`: the top level directory of the repository

- `--show-ref-format`: the reference database format (`files` or `reftable`),

- `--show-superproject-working-tree`: the absolute path of the superproject

- `--is-bare-repository`: whether this is a bare repository

- `--is-shallow-repository` whether this is a shallow repository

## Command design

The retrieved data will be presented as in a JSON format, like this:

~~~
$ git repo-info
{
  "objects": {
    "format": "sha1"
  },
  "references": {
    "format": "files"
  },
  "path": {
    "git-dir": "/git/dir"
    "git-commom-dir": "/git/common-dir",
    "toplevel": "/git/toplevel",
    "superproject-working-tree": "/super/working/tree",
  }
  "layout": {
    "bare": false,
    "shallow": false
  }
}
~~~

Or in a plaintext format, like this:

~~~
$ git repo-info --format=plaintext
sha1
files
/git/dir
/git/common-dir
/git/toplevel
/super/working/tree
false
false
~~~

It will also allow the user to get only the desired fields, like this:

~~~
$ git repo-info --format=plaintext objects.format references.format
sha1
files
~~~

or:

~~~
$ git repo-info objects.format references.format
{
  "objects": {
    "format": "sha1"
  },
  "references": {
    "format": "files"
  }
}
~~~

Currently this RFC only implements "objects.format", "layout.bare" and
"layout.shallow", but I'm making it flexible to add other fields, following
this format.

## Feedback

I would like to ask for your feedback on this proprosal, specially:

- on deciding if the JSON and linewise plaintext formats are the really the best,
  or if I should consider others (e.g. gitconfig syntax, NUL-terminated, etc)

- on deciding how the fields will be specified. This "<category>.<format>" was
  a first idea based on the JSON structure

- about the JSON schema

- about information that may be nice to include in the output of this command,
  even if they are not currently retrieved by `rev-parse`

Thanks!

Lucas Seiki Oshiro (5):
  repo-info: declare the repo-info command
  repo-info: add the --format flag
  repo-info: add the field references.format
  repo-info: add field layout.bare
  repo-info: add field layout.shallow

 .gitignore           |   1 +
 Makefile             |   1 +
 builtin.h            |   1 +
 builtin/repo-info.c  | 233 +++++++++++++++++++++++++++++++++++++++++++
 git.c                |   1 +
 meson.build          |   1 +
 t/meson.build        |   1 +
 t/t1518-repo-info.sh | 123 +++++++++++++++++++++++
 8 files changed, 362 insertions(+)
 create mode 100644 builtin/repo-info.c
 create mode 100755 t/t1518-repo-info.sh

-- 
2.39.5 (Apple Git-154)