doc: consolidate extensions in git-config documentation

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>
Signed-off-by: Taylor Blau <me@ttaylorr.com>
This commit is contained in:
Caleb White
2024-10-22 00:08:49 +00:00
committed by Taylor Blau
parent 34b6ce9b30
commit 19f5ce0bc2
6 changed files with 62 additions and 64 deletions

View File

@ -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

View File

@ -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.
--