@matheusbsbs / matheus-bagliano / commits / 19f5ce0bc2

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>

Caleb White committed Oct 22, 2024 at 00:08 UTC 19f5ce0bc23b04401acd6f838fae4c6a23f09ecf
6 files changed +62 -64
Documentation/config/core.txt
+1 -1
@@ -366,7 +366,7 @@ default in a bare repository.
366
367 core.repositoryFormatVersion::
368 Internal variable identifying the repository format and layout
369 - version.
369 + version. See linkgit:gitrepository-layout[5].
370
371 core.sharedRepository::
372 When 'group' (or 'true'), the repository is made shareable between
Documentation/config/extensions.txt
+54 -19
@@ -1,17 +1,13 @@
1 -extensions.objectFormat::
2 - Specify the hash algorithm to use. The acceptable values are `sha1` and
3 - `sha256`. If not specified, `sha1` is assumed. It is an error to specify
4 - this key unless `core.repositoryFormatVersion` is 1.
1 +extensions.*::
2 + Unless otherwise stated, is an error to specify an extension if
3 + `core.repositoryFormatVersion` is not `1`. See
4 + linkgit:gitrepository-layout[5].
5 +
6 -Note that this setting should only be set by linkgit:git-init[1] or
7 -linkgit:git-clone[1]. Trying to change it after initialization will not
8 -work and will produce hard-to-diagnose issues.
9 -
10 -extensions.compatObjectFormat::
11 -
6 +--
7 +compatObjectFormat::
8 Specify a compatibility hash algorithm to use. The acceptable values
9 are `sha1` and `sha256`. The value specified must be different from the
14 - value of extensions.objectFormat. This allows client level
10 + value of `extensions.objectFormat`. This allows client level
11 interoperability between git repositories whose objectFormat matches
12 this compatObjectFormat. In particular when fully implemented the
13 pushes and pulls from a repository in whose objectFormat matches
@@ -19,18 +15,55 @@ extensions.compatObjectFormat::
15 compatObjectFormat in addition to oids encoded with objectFormat to
16 locally specify objects.
17
22 -extensions.refStorage::
18 +noop::
19 + This extension does not change git's behavior at all. It is useful only
20 + for testing format-1 compatibility.
21 ++
22 +For historical reasons, this extension is respected regardless of the
23 +`core.repositoryFormatVersion` setting.
24 +
25 +noop-v1::
26 + This extension does not change git's behavior at all. It is useful only
27 + for testing format-1 compatibility.
28 +
29 +objectFormat::
30 + Specify the hash algorithm to use. The acceptable values are `sha1` and
31 + `sha256`. If not specified, `sha1` is assumed.
32 ++
33 +Note that this setting should only be set by linkgit:git-init[1] or
34 +linkgit:git-clone[1]. Trying to change it after initialization will not
35 +work and will produce hard-to-diagnose issues.
36 +
37 +partialClone::
38 + When enabled, indicates that the repo was created with a partial clone
39 + (or later performed a partial fetch) and that the remote may have
40 + omitted sending certain unwanted objects. Such a remote is called a
41 + "promisor remote" and it promises that all such omitted objects can
42 + be fetched from it in the future.
43 ++
44 +The value of this key is the name of the promisor remote.
45 ++
46 +For historical reasons, this extension is respected regardless of the
47 +`core.repositoryFormatVersion` setting.
48 +
49 +preciousObjects::
50 + If enabled, indicates that objects in the repository MUST NOT be deleted
51 + (e.g., by `git-prune` or `git repack -d`).
52 ++
53 +For historical reasons, this extension is respected regardless of the
54 +`core.repositoryFormatVersion` setting.
55 +
56 +refStorage::
57 Specify the ref storage format to use. The acceptable values are:
58 +
59 include::../ref-storage-format.txt[]
26 -+
27 -It is an error to specify this key unless `core.repositoryFormatVersion` is 1.
60 +
61 +
62 Note that this setting should only be set by linkgit:git-init[1] or
63 linkgit:git-clone[1]. Trying to change it after initialization will not
64 work and will produce hard-to-diagnose issues.
65
33 -extensions.worktreeConfig::
66 +worktreeConfig::
67 If enabled, then worktrees will load config settings from the
68 `$GIT_DIR/config.worktree` file in addition to the
69 `$GIT_COMMON_DIR/config` file. Note that `$GIT_COMMON_DIR` and
@@ -40,7 +73,7 @@ extensions.worktreeConfig::
73 `config.worktree` file will override settings from any other
74 config files.
75 +
43 -When enabling `extensions.worktreeConfig`, you must be careful to move
76 +When enabling this extension, you must be careful to move
77 certain values from the common config file to the main working tree's
78 `config.worktree` file, if present:
79 +
@@ -48,15 +81,17 @@ certain values from the common config file to the main working tree's
81 `$GIT_COMMON_DIR/config.worktree`.
82 * If `core.bare` is true, then it must be moved from `$GIT_COMMON_DIR/config`
83 to `$GIT_COMMON_DIR/config.worktree`.
84 +
85 +
86 It may also be beneficial to adjust the locations of `core.sparseCheckout`
87 and `core.sparseCheckoutCone` depending on your desire for customizable
88 sparse-checkout settings for each worktree. By default, the `git
55 -sparse-checkout` builtin enables `extensions.worktreeConfig`, assigns
89 +sparse-checkout` builtin enables this extension, assigns
90 these config values on a per-worktree basis, and uses the
91 `$GIT_DIR/info/sparse-checkout` file to specify the sparsity for each
92 worktree independently. See linkgit:git-sparse-checkout[1] for more
93 details.
94 +
61 -For historical reasons, `extensions.worktreeConfig` is respected
62 -regardless of the `core.repositoryFormatVersion` setting.
95 +For historical reasons, this extension is respected regardless of the
96 +`core.repositoryFormatVersion` setting.
97 +--
Documentation/gitrepository-layout.txt
+1
@@ -298,6 +298,7 @@ SEE ALSO
298 --------
299 linkgit:git-init[1],
300 linkgit:git-clone[1],
301 +linkgit:git-config[1],
302 linkgit:git-fetch[1],
303 linkgit:git-pack-refs[1],
304 linkgit:git-gc[1],
Documentation/technical/hash-function-transition.txt
+2 -2
@@ -148,8 +148,8 @@ Detailed Design
148 Repository format extension
149 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
150 A SHA-256 repository uses repository format version `1` (see
151 -Documentation/technical/repository-version.txt) with extensions
152 -`objectFormat` and `compatObjectFormat`:
151 +linkgit:gitrepository-layout[5]) with `extensions.objectFormat` and
152 +`extensions.compatObjectFormat` (see linkgit:git-config[1]) set to:
153
154 [core]
155 repositoryFormatVersion = 1
Documentation/technical/partial-clone.txt
+1 -1
@@ -102,7 +102,7 @@ or commits that reference missing trees.
102 - On the client a repository extension is added to the local config to
103 prevent older versions of git from failing mid-operation because of
104 missing objects that they cannot handle.
105 - See "extensions.partialClone" in Documentation/technical/repository-version.txt"
105 + See `extensions.partialClone` in linkgit:git-config[1].
106
107
108 Handling Missing Objects
Documentation/technical/repository-version.txt
+3 -41
@@ -65,44 +65,6 @@ Note that if no extensions are specified in the config file, then
65 provides no benefit, and makes the repository incompatible with older
66 implementations of git).
67
68 -This document will serve as the master list for extensions. Any
69 -implementation wishing to define a new extension should make a note of
70 -it here, in order to claim the name.
71 -
72 -The defined extensions are:
73 -
74 -==== `noop`
75 -
76 -This extension does not change git's behavior at all. It is useful only
77 -for testing format-1 compatibility.
78 -
79 -==== `preciousObjects`
80 -
81 -When the config key `extensions.preciousObjects` is set to `true`,
82 -objects in the repository MUST NOT be deleted (e.g., by `git-prune` or
83 -`git repack -d`).
84 -
85 -==== `partialClone`
86 -
87 -When the config key `extensions.partialClone` is set, it indicates
88 -that the repo was created with a partial clone (or later performed
89 -a partial fetch) and that the remote may have omitted sending
90 -certain unwanted objects. Such a remote is called a "promisor remote"
91 -and it promises that all such omitted objects can be fetched from it
92 -in the future.
93 -
94 -The value of this key is the name of the promisor remote.
95 -
96 -==== `worktreeConfig`
97 -
98 -If set, by default "git config" reads from both "config" and
99 -"config.worktree" files from GIT_DIR in that order. In
100 -multiple working directory mode, "config" file is shared while
101 -"config.worktree" is per-working directory (i.e., it's in
102 -GIT_COMMON_DIR/worktrees/<id>/config.worktree)
103 -
104 -==== `refStorage`
105 -
106 -Specifies the file format for the ref database. The valid values are
107 -`files` (loose references with a packed-refs file) and `reftable` (see
108 -Documentation/technical/reftable.txt).
68 +The defined extensions are given in the `extensions.*` section of
69 +linkgit:git-config[1]. Any implementation wishing to define a new
70 +extension should make a note of it there, in order to claim the name.