On Tue, Jan 25, 2022 at 10:42 AM Derrick Stolee via GitGitGadget
<gitgitgadget@xxxxxxxxx> wrote:
>
> From: Derrick Stolee <dstolee@xxxxxxxxxxxxx>
>
> 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.
>
> Signed-off-by: Derrick Stolee <dstolee@xxxxxxxxxxxxx>
> ---
> Documentation/config/extensions.txt | 31 +++++++++++++++++++++++++++++
> Documentation/git-config.txt | 8 ++++++--
> Documentation/git-worktree.txt | 11 +++++++---
> 3 files changed, 45 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/config/extensions.txt b/Documentation/config/extensions.txt
> index 4e23d73cdca..5999dcb2a1f 100644
> --- a/Documentation/config/extensions.txt
> +++ b/Documentation/config/extensions.txt
> @@ -6,3 +6,34 @@ extensions.objectFormat::
> 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 worktree, while other
> + worktrees have `$GIT_DIR` equal to
> + `$GIT_COMMON_DIR/worktrees/<worktree-name>/`. 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 worktree'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.
> diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
> index 2285effb363..95cefd5e399 100644
> --- a/Documentation/git-config.txt
> +++ b/Documentation/git-config.txt
> @@ -141,9 +141,13 @@ from all available files.
> See also <<FILES>>.
>
> --worktree::
> - Similar to `--local` except that `.git/config.worktree` is
> + Similar to `--local` except that `$GIT_DIR/config.worktree` is
> read from or written to if `extensions.worktreeConfig` is
> - present. If not it's the same as `--local`.
> + enabled. If not it's the same as `--local`. Note that `$GIT_DIR`
> + is equal to `$GIT_COMMON_DIR` for the main worktree, but is of the
> + form `.git/worktrees/<worktree-name>/` for other worktrees. See
is of the form `$GIT_DIR/worktrees/<worktree-name>/`; .git isn't even
a directory in other worktrees.
> + linkgit:git-worktree[1] to learn how to enable
> + `extensions.worktreeConfig`.
>
> -f <config-file>::
> --file <config-file>::
> diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
> index 9e862fbcf79..ea0ee9f8bb5 100644
> --- a/Documentation/git-worktree.txt
> +++ b/Documentation/git-worktree.txt
> @@ -286,8 +286,8 @@ CONFIGURATION FILE
> ------------------
> By default, the repository `config` file is shared across all working
> trees. If the config variables `core.bare` or `core.worktree` are
> -already present in the config file, they will be applied to the main
> -working trees only.
> +present in the common config file and `extensions.worktreeConfig` is
> +disabled, then they will be applied to the main working trees only.
"main working trees"? Is that an accidental plural?
> In order to have configuration specific to working trees, you can turn
> on the `worktreeConfig` extension, e.g.:
> @@ -307,11 +307,16 @@ them to the `config.worktree` of the main working tree. You may also
> take this opportunity to review and move other configuration that you
> do not want to share to all working trees:
>
> - - `core.worktree` and `core.bare` should never be shared
> + - `core.worktree` should never be shared.
> +
> + - `core.bare` should not be shared unless the value is `core.bare=false`.
The double negative makes for harder parsing. Perhaps
- `core.bare` should not be shared if the value is `core.bare=true`
?
> - `core.sparseCheckout` is recommended per working tree, unless you
> are sure you always use sparse checkout for all working trees.
>
> +See the documentation of `extensions.worktreeConfig` in
> +linkgit:git-config[1] for more details.
> +
> DETAILS
> -------
> Each linked working tree has a private sub-directory in the repository's
> --
> gitgitgadget
Thanks for documenting these details; I had some very minor comments
but this is well written and very helpful.
