Merge branch 'cw/config-extensions'
Centralize documentation for repository extensions into a single place.
* cw/config-extensions:
doc: consolidate extensions in git-config documentation
diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt
index 60ca9f2..8f6d8e7 100644
--- a/Documentation/config/core.txt
+++ b/Documentation/config/core.txt
@@ -366,7 +366,7 @@
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
diff --git a/Documentation/config/extensions.txt b/Documentation/config/extensions.txt
index f0a7844..5dc569d 100644
--- a/Documentation/config/extensions.txt
+++ b/Documentation/config/extensions.txt
@@ -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 @@
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 @@
`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 @@
`$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.
+--
diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt
index 949cd8a..fa8b51d 100644
--- a/Documentation/gitrepository-layout.txt
+++ b/Documentation/gitrepository-layout.txt
@@ -298,6 +298,7 @@
--------
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],
diff --git a/Documentation/technical/hash-function-transition.txt b/Documentation/technical/hash-function-transition.txt
index ed57481..7102c7c 100644
--- a/Documentation/technical/hash-function-transition.txt
+++ b/Documentation/technical/hash-function-transition.txt
@@ -148,8 +148,8 @@
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
diff --git a/Documentation/technical/partial-clone.txt b/Documentation/technical/partial-clone.txt
index cd948b0..bf5ec5c 100644
--- a/Documentation/technical/partial-clone.txt
+++ b/Documentation/technical/partial-clone.txt
@@ -102,7 +102,7 @@
- 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
diff --git a/Documentation/technical/repository-version.txt b/Documentation/technical/repository-version.txt
index 4728142..b9bb81a 100644
--- a/Documentation/technical/repository-version.txt
+++ b/Documentation/technical/repository-version.txt
@@ -65,44 +65,6 @@
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.
