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

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

View File

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

View File

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