Re: [GSoC PATCH v10 4/5] repo: add the field layout.shallow

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 15, 2025, 19:36 UTC
Message-ID: <xmqqzfc0peaw.fsf@gitster.g>
In-Reply-To: <20250815135521.44044-5-lucasseikioshiro@gmail.com>

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

Show 10 quoted lines

> @@ -41,6 +41,9 @@ values that they return:
>  `layout.bare`::
>  `true` if this is a bare repository, otherwise `false`.
>  
> +`layout.shallow`::
> +`true` if this is a shallow repository, otherwise `false`.
> +
>  `references.format`::
>  The reference storage format. The valid values are:
>  +

Common to all three patches that adds each of these three, but I think we want to see these definition list like so:

	`layout.bare`::
		`true` if this is a bare...

	`layout.shallow`::
		'true` if this is a shallow...

	`reference.format`::
		The reference storage format.

It should not make any difference in the rendered result. The existing documentation pages follow this style because it makes the layout of the text in the source file resemble the formatted output more closely.

Also, I wonder if it makes the document structure (from the point of view of mark-up) more apparent if we make the listing of two possible values for the "--format=" option a nested definition list, inside the definition list with a single element "info" in it.

Something like the following on top of your series, that is.

The first hunk does make the result rendered differently; the second hunk should produce the identical rendition as your version.

Thanks.

 Documentation/git-repo.adoc | 24 +++++++++++++-----------
 1 file changed, 13 insertions(+), 11 deletions(-)

diff --git c/Documentation/git-repo.adoc w/Documentation/git-repo.adoc
index cb22f7ef65..5424deea69 100644
--- c/Documentation/git-repo.adoc
+++ w/Documentation/git-repo.adoc
@@ -29,15 +29,17 @@ requested.
 The output format can be chosen through the flag `--format`. Two formats are
 supported:
 +
-* `keyvalue`: output key-value pairs one per line using the `=` character as
-the delimiter between the key and the value. Values containing "unusual"
-characters are quoted as explained for the configuration variable
-`core.quotePath` (see linkgit:git-config[1]). This is the default.
+`keyvalue`;;
+	output key-value pairs one per line using the `=` character as
+	the delimiter between the key and the value. Values containing "unusual"
+	characters are quoted as explained for the configuration variable
+	`core.quotePath` (see linkgit:git-config[1]). This is the default.
 
-* `nul`: similar to `keyvalue`, but using a newline character as the delimiter
-between the key and the value and using a null character after each value.
-This format is better suited for being parsed by another applications than
-`keyvalue`. Unlike in the `keyvalue` format, the values are never quoted.
+`nul`;;
+	similar to `keyvalue`, but using a newline character as the delimiter
+	between the key and the value and using a null character after each value.
+	This format is better suited for being parsed by another applications than
+	`keyvalue`. Unlike in the `keyvalue` format, the values are never quoted.
 
 INFO KEYS
 ---------
@@ -46,13 +48,13 @@ the keys that identify them. Here's a list of the available keys and the
 values that they return:
 
 `layout.bare`::
-`true` if this is a bare repository, otherwise `false`.
+	`true` if this is a bare repository, otherwise `false`.
 
 `layout.shallow`::
-`true` if this is a shallow repository, otherwise `false`.
+	`true` if this is a shallow repository, otherwise `false`.
 
 `references.format`::
-The reference storage format. The valid values are:
+	The reference storage format. The valid values are:
 +
 include::ref-storage-format.adoc[]