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
Taylor Blau
parent
34b6ce9b30
commit
19f5ce0bc2
@ -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.
|
||||
--
|
||||
|
||||
@ -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],
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user