5c11c0d52c
The extensions.worktreeConfig extension was added in58b284a(worktree: add per-worktree config files, 2018-10-21) and was somewhat documented in Documentation/git-config.txt. However, the extensions.worktreeConfig value was not specified further in the list of possible config keys. The location of the config.worktree file is not specified, and there are some precautions that should be mentioned clearly, but are only mentioned in git-worktree.txt. Expand the documentation to help users discover the complexities of extensions.worktreeConfig by adding details and cross links in these locations (relative to Documentation/): - config/extensions.txt - git-config.txt - git-worktree.txt The updates focus on items such as * $GIT_DIR/config.worktree takes precedence over $GIT_COMMON_DIR/config. * The core.worktree and core.bare=true settings are incorrect to have in the common config file when extensions.worktreeConfig is enabled. * The sparse-checkout settings core.sparseCheckout[Cone] are recommended to be set in the worktree config. As documented in11664196ac("Revert "check_repository_format_gently(): refuse extensions for old repositories"", 2020-07-15), this extension must be considered regardless of the repository format version for historical reasons. A future change will update references to extensions.worktreeConfig within git-sparse-checkout.txt, but a behavior change is needed before making those updates. Helped-by: Elijah Newren <newren@gmail.com> Signed-off-by: Derrick Stolee <dstolee@microsoft.com> Reviewed-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
40 lines
1.8 KiB
Plaintext
40 lines
1.8 KiB
Plaintext
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.
|
|
+
|
|
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::
|
|
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
|
|
`$GIT_DIR` are the same for the main working tree, while other
|
|
working trees have `$GIT_DIR` equal to
|
|
`$GIT_COMMON_DIR/worktrees/<id>/`. The settings in the
|
|
`config.worktree` file will override settings from any other
|
|
config files.
|
|
+
|
|
When enabling `extensions.worktreeConfig`, you must be careful to move
|
|
certain values from the common config file to the main working tree's
|
|
`config.worktree` file, if present:
|
|
+
|
|
* `core.worktree` must be moved from `$GIT_COMMON_DIR/config` to
|
|
`$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
|
|
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.
|