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:
@ -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
|
||||
|
@ -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.
|
||||
--
|
||||
|
Reference in New Issue
Block a user