@matheusbsbs / matheus-bagliano / commits / 5c11c0d52c

Documentation: add extensions.worktreeConfig details

The extensions.worktreeConfig extension was added in 58b284a (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 in 11664196ac ("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>

Derrick Stolee committed Feb 7, 2022 at 21:32 UTC 5c11c0d52c398af65f19bcf65a46304552083214
3 files changed +45 -5
Documentation/config/extensions.txt
+31
@@ -6,3 +6,34 @@ extensions.objectFormat::
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.worktreeConfig::
11 + If enabled, then worktrees will load config settings from the
12 + `$GIT_DIR/config.worktree` file in addition to the
13 + `$GIT_COMMON_DIR/config` file. Note that `$GIT_COMMON_DIR` and
14 + `$GIT_DIR` are the same for the main working tree, while other
15 + working trees have `$GIT_DIR` equal to
16 + `$GIT_COMMON_DIR/worktrees/<id>/`. The settings in the
17 + `config.worktree` file will override settings from any other
18 + config files.
19 ++
20 +When enabling `extensions.worktreeConfig`, you must be careful to move
21 +certain values from the common config file to the main working tree's
22 +`config.worktree` file, if present:
23 ++
24 +* `core.worktree` must be moved from `$GIT_COMMON_DIR/config` to
25 + `$GIT_COMMON_DIR/config.worktree`.
26 +* If `core.bare` is true, then it must be moved from `$GIT_COMMON_DIR/config`
27 + to `$GIT_COMMON_DIR/config.worktree`.
28 ++
29 +It may also be beneficial to adjust the locations of `core.sparseCheckout`
30 +and `core.sparseCheckoutCone` depending on your desire for customizable
31 +sparse-checkout settings for each worktree. By default, the `git
32 +sparse-checkout` builtin enables `extensions.worktreeConfig`, assigns
33 +these config values on a per-worktree basis, and uses the
34 +`$GIT_DIR/info/sparse-checkout` file to specify the sparsity for each
35 +worktree independently. See linkgit:git-sparse-checkout[1] for more
36 +details.
37 ++
38 +For historical reasons, `extensions.worktreeConfig` is respected
39 +regardless of the `core.repositoryFormatVersion` setting.
Documentation/git-config.txt
+6 -2
@@ -141,9 +141,13 @@ from all available files.
141 See also <<FILES>>.
142
143 --worktree::
144 - Similar to `--local` except that `.git/config.worktree` is
144 + Similar to `--local` except that `$GIT_DIR/config.worktree` is
145 read from or written to if `extensions.worktreeConfig` is
146 - present. If not it's the same as `--local`.
146 + enabled. If not it's the same as `--local`. Note that `$GIT_DIR`
147 + is equal to `$GIT_COMMON_DIR` for the main working tree, but is of
148 + the form `$GIT_DIR/worktrees/<id>/` for other working trees. See
149 + linkgit:git-worktree[1] to learn how to enable
150 + `extensions.worktreeConfig`.
151
152 -f <config-file>::
153 --file <config-file>::
Documentation/git-worktree.txt
+8 -3
@@ -286,8 +286,8 @@ CONFIGURATION FILE
286 ------------------
287 By default, the repository `config` file is shared across all working
288 trees. If the config variables `core.bare` or `core.worktree` are
289 -already present in the config file, they will be applied to the main
290 -working trees only.
289 +present in the common config file and `extensions.worktreeConfig` is
290 +disabled, then they will be applied to the main working tree only.
291
292 In order to have configuration specific to working trees, you can turn
293 on the `worktreeConfig` extension, e.g.:
@@ -307,11 +307,16 @@ them to the `config.worktree` of the main working tree. You may also
307 take this opportunity to review and move other configuration that you
308 do not want to share to all working trees:
309
310 - - `core.worktree` and `core.bare` should never be shared
310 + - `core.worktree` should never be shared.
311 +
312 + - `core.bare` should not be shared if the value is `core.bare=true`.
313
314 - `core.sparseCheckout` is recommended per working tree, unless you
315 are sure you always use sparse checkout for all working trees.
316
317 +See the documentation of `extensions.worktreeConfig` in
318 +linkgit:git-config[1] for more details.
319 +
320 DETAILS
321 -------
322 Each linked working tree has a private sub-directory in the repository's