| Message ID | 459e09dedd71fcb64b9796bac52c3812d78f2405.1643136134.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Sparse checkout: fix bug with worktree of bare repo | expand |
On 26/01/22 01.42, Derrick Stolee via GitGitGadget wrote: > 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. > ... > +For historical reasons, `extensions.worktreeConfig` is respected > +regardless of the `core.repositoryFormatVersion` setting. This implies `extensions.worktreeConfig` become integral part of every repository format version, from the past until now and to the future, right?
On Tue, Jan 25, 2022 at 10:42 AM Derrick Stolee via GitGitGadget <gitgitgadget@gmail.com> wrote: > > From: Derrick Stolee <dstolee@microsoft.com> > > 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@microsoft.com> > --- > 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.
On 1/26/2022 1:59 AM, Bagas Sanjaya wrote: > On 26/01/22 01.42, Derrick Stolee via GitGitGadget wrote: >> 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. >> > ... >> +For historical reasons, `extensions.worktreeConfig` is respected >> +regardless of the `core.repositoryFormatVersion` setting. > > This implies `extensions.worktreeConfig` become integral part of every > repository format version, from the past until now and to the future, > right? Right. What I'm saying is that this is already the case. I'm not changing it. The commit message in 116664196ac discusses this in depth. I'm pointing it out carefully because it is news to me (hence why the sparse-checkout builtin updates the repository format version before this series). Thanks, -Stolee
On 1/27/2022 1:43 AM, Elijah Newren wrote: > On Tue, Jan 25, 2022 at 10:42 AM Derrick Stolee via GitGitGadget > <gitgitgadget@gmail.com> wrote: >> --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. Thanks. I tried to catch all of these, but I missed one. >> + 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? Yes. Thanks. >> 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` > ? That is cleaner. Excellent. >> - `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. Thanks for your recommended improvements. -Stolee
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 + 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. 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`. - `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