[PATCH] doc: consolidate extensions in git-config documentation

[PATCH] doc: consolidate extensions in git-config documentation

[Caleb White]

The `technical/repository-version.txt` document originally served as the
master list for extensions, requiring that any new extensions be defined
there. However, the `config/extensions.txt` file was introduced later
and has since become the de facto location for describing extensions,
with several extensions listed there but missing from
`repository-version.txt`.

This consolidates all extension definitions into `config/extensions.txt`,
making it the authoritative source for extensions. The references in
`repository-version.txt` are updated to point to `config/extensions.txt`,
and cross-references to related documentation such as
`gitrepository-layout[5]` and `git-config[1]` are added.

Suggested-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Caleb White <cdwhite3@pm.me>
---
This patch was based on v2.47.0.
---
 Documentation/config/core.txt                      |  2 +-
 Documentation/config/extensions.txt                | 73 ++++++++++++++++------
 Documentation/gitrepository-layout.txt             |  1 +
 .../technical/hash-function-transition.txt         |  4 +-
 Documentation/technical/partial-clone.txt          |  2 +-
 Documentation/technical/repository-version.txt     | 44 +------------
 6 files changed, 62 insertions(+), 64 deletions(-)

diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt
index 60ca9f2b6861063c0e78307edcbbd25a9104472f..8f6d8e77541261d67abac4f990f36ebb29b568c6 100644
--- a/Documentation/config/core.txt
+++ b/Documentation/config/core.txt
@@ -366,7 +366,7 @@ default in a bare repository.
 
 core.repositoryFormatVersion::
 	Internal variable identifying the repository format and layout
-	version.
+	version. See linkgit:gitrepository-layout[5].
 
 core.sharedRepository::
 	When 'group' (or 'true'), the repository is made shareable between
diff --git a/Documentation/config/extensions.txt b/Documentation/config/extensions.txt
index f0a784447db09856639ec43b443681f13c17c966..5dc569d1c9c77c15e32441493289f9c9dd5e7f0b 100644
--- a/Documentation/config/extensions.txt
+++ b/Documentation/config/extensions.txt
@@ -1,17 +1,13 @@
-extensions.objectFormat::
-	Specify the hash algorithm to use.  The acceptable values are `sha1` and
-	`sha256`.  If not specified, `sha1` is assumed.  It is an error to specify
-	this key unless `core.repositoryFormatVersion` is 1.
+extensions.*::
+	Unless otherwise stated, is an error to specify an extension if
+	`core.repositoryFormatVersion` is not `1`. See
+	linkgit:gitrepository-layout[5].
 +
-Note that this setting should only be set by linkgit:git-init[1] or
-linkgit:git-clone[1].  Trying to change it after initialization will not
-work and will produce hard-to-diagnose issues.
-
-extensions.compatObjectFormat::
-
+--
+compatObjectFormat::
 	Specify a compatibility hash algorithm to use.  The acceptable values
 	are `sha1` and `sha256`.  The value specified must be different from the
-	value of extensions.objectFormat.  This allows client level
+	value of `extensions.objectFormat`.  This allows client level
 	interoperability between git repositories whose objectFormat matches
 	this compatObjectFormat.  In particular when fully implemented the
 	pushes and pulls from a repository in whose objectFormat matches
@@ -19,18 +15,55 @@ extensions.compatObjectFormat::
 	compatObjectFormat in addition to oids encoded with objectFormat to
 	locally specify objects.
 
-extensions.refStorage::
+noop::
+	This extension does not change git's behavior at all. It is useful only
+	for testing format-1 compatibility.
++
+For historical reasons, this extension is respected regardless of the
+`core.repositoryFormatVersion` setting.
+
+noop-v1::
+	This extension does not change git's behavior at all. It is useful only
+	for testing format-1 compatibility.
+
+objectFormat::
+	Specify the hash algorithm to use.  The acceptable values are `sha1` and
+	`sha256`.  If not specified, `sha1` is assumed.
++
+Note that this setting should only be set by linkgit:git-init[1] or
+linkgit:git-clone[1].  Trying to change it after initialization will not
+work and will produce hard-to-diagnose issues.
+
+partialClone::
+	When enabled, indicates that the repo was created with a partial clone
+	(or later performed a partial fetch) and that the remote may have
+	omitted sending certain unwanted objects.  Such a remote is called a
+	"promisor remote" and it promises that all such omitted objects can
+	be fetched from it in the future.
++
+The value of this key is the name of the promisor remote.
++
+For historical reasons, this extension is respected regardless of the
+`core.repositoryFormatVersion` setting.
+
+preciousObjects::
+	If enabled, indicates that objects in the repository MUST NOT be deleted
+	(e.g., by `git-prune` or `git repack -d`).
++
+For historical reasons, this extension is respected regardless of the
+`core.repositoryFormatVersion` setting.
+
+refStorage::
 	Specify the ref storage format to use. The acceptable values are:
 +
 include::../ref-storage-format.txt[]
-+
-It is an error to specify this key unless `core.repositoryFormatVersion` is 1.
+
 +
 Note that this setting should only be set by linkgit:git-init[1] or
 linkgit:git-clone[1]. Trying to change it after initialization will not
 work and will produce hard-to-diagnose issues.
 
-extensions.worktreeConfig::
+worktreeConfig::
 	If enabled, then worktrees will load config settings from the
 	`$GIT_DIR/config.worktree` file in addition to the
 	`$GIT_COMMON_DIR/config` file. Note that `$GIT_COMMON_DIR` and
@@ -40,7 +73,7 @@ extensions.worktreeConfig::
 	`config.worktree` file will override settings from any other
 	config files.
 +
-When enabling `extensions.worktreeConfig`, you must be careful to move
+When enabling this extension, you must be careful to move
 certain values from the common config file to the main working tree's
 `config.worktree` file, if present:
 +
@@ -48,15 +81,17 @@ certain values from the common config file to the main working tree's
   `$GIT_COMMON_DIR/config.worktree`.
 * If `core.bare` is true, then it must be moved from `$GIT_COMMON_DIR/config`
   to `$GIT_COMMON_DIR/config.worktree`.
+
 +
 It may also be beneficial to adjust the locations of `core.sparseCheckout`
 and `core.sparseCheckoutCone` depending on your desire for customizable
 sparse-checkout settings for each worktree. By default, the `git
-sparse-checkout` builtin enables `extensions.worktreeConfig`, assigns
+sparse-checkout` builtin enables this extension, assigns
 these config values on a per-worktree basis, and uses the
 `$GIT_DIR/info/sparse-checkout` file to specify the sparsity for each
 worktree independently. See linkgit:git-sparse-checkout[1] for more
 details.
 +
-For historical reasons, `extensions.worktreeConfig` is respected
-regardless of the `core.repositoryFormatVersion` setting.
+For historical reasons, this extension is respected regardless of the
+`core.repositoryFormatVersion` setting.
+--
diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt
index 949cd8a31e9a9e896ccec63d5c7e2f23f740973a..fa8b51daf08775f3d666a910d9b00486627e02af 100644
--- a/Documentation/gitrepository-layout.txt
+++ b/Documentation/gitrepository-layout.txt
@@ -298,6 +298,7 @@ SEE ALSO
 --------
 linkgit:git-init[1],
 linkgit:git-clone[1],
+linkgit:git-config[1],
 linkgit:git-fetch[1],
 linkgit:git-pack-refs[1],
 linkgit:git-gc[1],
diff --git a/Documentation/technical/hash-function-transition.txt b/Documentation/technical/hash-function-transition.txt
index ed574810891cad1024658920e0fa8ac550231534..7102c7c8f5d66de5574de459a0e1136131a53004 100644
--- a/Documentation/technical/hash-function-transition.txt
+++ b/Documentation/technical/hash-function-transition.txt
@@ -148,8 +148,8 @@ Detailed Design
 Repository format extension
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 A SHA-256 repository uses repository format version `1` (see
-Documentation/technical/repository-version.txt) with extensions
-`objectFormat` and `compatObjectFormat`:
+linkgit:gitrepository-layout[5]) with `extensions.objectFormat` and
+`extensions.compatObjectFormat` (see linkgit:git-config[1]) set to:
 
 	[core]
 		repositoryFormatVersion = 1
diff --git a/Documentation/technical/partial-clone.txt b/Documentation/technical/partial-clone.txt
index cd948b00722cba5ae9f01b31f6a226f8d4497ea8..bf5ec5c82d9e0f2fedfec517a6a86d9973f4f312 100644
--- a/Documentation/technical/partial-clone.txt
+++ b/Documentation/technical/partial-clone.txt
@@ -102,7 +102,7 @@ or commits that reference missing trees.
 - On the client a repository extension is added to the local config to
   prevent older versions of git from failing mid-operation because of
   missing objects that they cannot handle.
-  See "extensions.partialClone" in Documentation/technical/repository-version.txt"
+  See `extensions.partialClone` in linkgit:git-config[1].
 
 
 Handling Missing Objects
diff --git a/Documentation/technical/repository-version.txt b/Documentation/technical/repository-version.txt
index 47281420fc4a0c901d60b2854a8f0a6e8f70587a..b9bb81a81f9ea16830290dfabd0839f1f05b1992 100644
--- a/Documentation/technical/repository-version.txt
+++ b/Documentation/technical/repository-version.txt
@@ -65,44 +65,6 @@ Note that if no extensions are specified in the config file, then
 provides no benefit, and makes the repository incompatible with older
 implementations of git).
 
-This document will serve as the master list for extensions. Any
-implementation wishing to define a new extension should make a note of
-it here, in order to claim the name.
-
-The defined extensions are:
-
-==== `noop`
-
-This extension does not change git's behavior at all. It is useful only
-for testing format-1 compatibility.
-
-==== `preciousObjects`
-
-When the config key `extensions.preciousObjects` is set to `true`,
-objects in the repository MUST NOT be deleted (e.g., by `git-prune` or
-`git repack -d`).
-
-==== `partialClone`
-
-When the config key `extensions.partialClone` is set, it indicates
-that the repo was created with a partial clone (or later performed
-a partial fetch) and that the remote may have omitted sending
-certain unwanted objects.  Such a remote is called a "promisor remote"
-and it promises that all such omitted objects can be fetched from it
-in the future.
-
-The value of this key is the name of the promisor remote.
-
-==== `worktreeConfig`
-
-If set, by default "git config" reads from both "config" and
-"config.worktree" files from GIT_DIR in that order. In
-multiple working directory mode, "config" file is shared while
-"config.worktree" is per-working directory (i.e., it's in
-GIT_COMMON_DIR/worktrees/<id>/config.worktree)
-
-==== `refStorage`
-
-Specifies the file format for the ref database. The valid values are
-`files` (loose references with a packed-refs file) and `reftable` (see
-Documentation/technical/reftable.txt).
+The defined extensions are given in the `extensions.*` section of
+linkgit:git-config[1]. Any implementation wishing to define a new
+extension should make a note of it there, in order to claim the name.

---
base-commit: 777489f9e09c8d0dd6b12f9d90de6376330577a2
change-id: 20241020-cleanup-extension-docs-f365868711bf

Best regards,
-- 
Caleb White <cdwhite3@pm.me>

Re: [PATCH] doc: consolidate extensions in git-config documentation

[Taylor Blau]

On Tue, Oct 22, 2024 at 12:08:49AM +0000, Caleb White wrote:
> diff --git a/Documentation/config/extensions.txt b/Documentation/config/extensions.txt
> index f0a784447db09856639ec43b443681f13c17c966..5dc569d1c9c77c15e32441493289f9c9dd5e7f0b 100644
> --- a/Documentation/config/extensions.txt
> +++ b/Documentation/config/extensions.txt
> @@ -1,17 +1,13 @@
> -extensions.objectFormat::
> -	Specify the hash algorithm to use.  The acceptable values are `sha1` and
> -	`sha256`.  If not specified, `sha1` is assumed.  It is an error to specify
> -	this key unless `core.repositoryFormatVersion` is 1.
> +extensions.*::
> +	Unless otherwise stated, is an error to specify an extension if
> +	`core.repositoryFormatVersion` is not `1`. See
> +	linkgit:gitrepository-layout[5].
>  +
> -Note that this setting should only be set by linkgit:git-init[1] or
> -linkgit:git-clone[1].  Trying to change it after initialization will not
> -work and will produce hard-to-diagnose issues.
> -
> -extensions.compatObjectFormat::
> -
> +--
> +compatObjectFormat::

Should this be `extensions.compatObjectFormat` instead of
`compatObjectFormat`? I think the latter will produce awkward headings
when these all get merged into git-config(1).

Otherwise, looking good. Thanks for working on this!

Thanks,
Taylor

Re: [PATCH] doc: consolidate extensions in git-config documentation

[Caleb White]

On Tue Oct 22, 2024 at 12:13 PM CDT, Taylor Blau wrote:
> On Tue, Oct 22, 2024 at 12:08:49AM +0000, Caleb White wrote:
>> -Note that this setting should only be set by linkgit:git-init[1] or
>> -linkgit:git-clone[1].  Trying to change it after initialization will not
>> -work and will produce hard-to-diagnose issues.
>> -
>> -extensions.compatObjectFormat::
>> -
>> +--
>> +compatObjectFormat::
>
> Should this be `extensions.compatObjectFormat` instead of
> `compatObjectFormat`? I think the latter will produce awkward headings
> when these all get merged into git-config(1).

No, I built the man pages and visually inspected the changes to ensure
they were formatted correctly. This is modeled after the `advice.*`
config section which has the sub-sections listed as an indented block
under the main `advice` section. It looks like the following:

    extensions.*
        <description>

        compatObjectFormat
            <description>

        <next extension>

One thing we might could do is bold the sub-sections, but the `advice.*`
section doesn't do that so I didn't do it here.

> Otherwise, looking good. Thanks for working on this!

Sure thing!

Best,