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