On 2/8/2022 5:20 PM, Junio C Hamano wrote: > "Derrick Stolee via GitGitGadget" <gitgitgadget@xxxxxxxxx> writes: > >> diff --git a/Documentation/config/extensions.txt b/Documentation/config/extensions.txt >> index 4e23d73cdca..bccaec7a963 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 working tree, while other >> + working trees have `$GIT_DIR` equal to >> + `$GIT_COMMON_DIR/worktrees/<id>/`. The settings in the > > The mixed use of "worktree" and "working tree" in this paragraph > might confuse readers into thinking that the paragraph is being > careful to make distinction between the two. All references to > "working tree" in the above paragraph should actually be "worktree", > I would think. I generally agree. This was changed in the most-recent re-roll based on a request by Eric [1]. I'm happy to take whichever version the two of you settle on. [1] https://lore.kernel.org/git/CAPig+cS-3CxxyPGcy_vkeN_WYTRo1b-ZhJNdPy8ARZSNKkF1Xg@xxxxxxxxxxxxxx/ > Side note: "working tree" is in the glossary-content.txt, > but "worktree", which is one "working tree" + repository > metadata (i.e. ".git/") that may be partially shared with > other "worktree"s of a single repository, is not defined. > > This is a tangent, but I wonder why we chose to use a different > filename (i.e. not "config" but "config.worktree") for this. If we > were redoing multi-worktree support from scratch, we would not reuse > the $GIT_DIR used by the primary worktree as $GIT_COMMON_DIR, so > that all worktrees would share a single $GIT_COMMON_DIR and > $GIT_COMMON_DIR/config that has stuff that is shared among all the > worktrees, while per worktree stuff is in $GIT_DIR/config even for > the primary worktree. But that is all water under the bridge now. Right. I think that since the primary worktree uses $GIT_COMMON_DIR as its location for base information (like HEAD) it also means that its worktree-specific config file cannot be called "config". Perhaps there could have been a way to split the worktrees so the primary worktree got its own directory within ".git/worktrees/", but my guess is that the design optimized for backwards compatibility: Git clients that don't understand worktrees could still interact with the primary worktree. > Other than the terminology gotcha, looked sensible. Migrating > automatically and/or noticing a suspicious setting may be needed to > help end users, but that would not be within the scope of this step. > > Attached is a "how about this?" glossary update suggestion. Most of > the existing mention of "working tree" are fine as-is because they > only care about what is in the "working tree", but some should be > changed to "worktree" to stress the fact that they care not just the > "working tree" part but also the repository metadata part that is > associated with that single "working tree". The first hunk says > worktree but it is clear that it is interested only in the "working > tree" files. > > Documentation/glossary-content.txt | 13 +++++++++++-- > 1 file changed, 11 insertions(+), 2 deletions(-) > > diff --git c/Documentation/glossary-content.txt w/Documentation/glossary-content.txt > index c077971335..d816512c6a 100644 > --- c/Documentation/glossary-content.txt > +++ w/Documentation/glossary-content.txt > @@ -312,7 +312,7 @@ Pathspecs are used on the command line of "git ls-files", "git > ls-tree", "git add", "git grep", "git diff", "git checkout", > and many other commands to > limit the scope of operations to some subset of the tree or > -worktree. See the documentation of each command for whether > +working tree. See the documentation of each command for whether > paths are relative to the current directory or toplevel. The > pathspec syntax is as follows: > + > @@ -446,7 +446,7 @@ exclude;; > interface than the <<def_plumbing,plumbing>>. > > [[def_per_worktree_ref]]per-worktree ref:: > - Refs that are per-<<def_working_tree,worktree>>, rather than > + Refs that are per-<<def_worktree,worktree>>, rather than > global. This is presently only <<def_HEAD,HEAD>> and any refs > that start with `refs/bisect/`, but might later include other > unusual refs. > @@ -669,3 +669,12 @@ The most notable example is `HEAD`. > The tree of actual checked out files. The working tree normally > contains the contents of the <<def_HEAD,HEAD>> commit's tree, > plus any local changes that you have made but not yet committed. > + > +[[def_work_tree]]worktree:: > + A repository can have zero (i.e. bare repository) or one or > + more worktrees attached to it. One "worktree" consists of a > + "working tree" and repository metadata, most of which are > + shared among other worktrees of a single repository, and > + some of which are maintained separately per worktree > + (e.g. the index, HEAD, per-worktree refs and per-worktree > + configuration file) I like this addition, except that I don't understand the "per-worktree refs" (other than HEAD). Are there other thins used by features such as merge and rebase that would appear as worktree-specific? Of course, some state for these operations is stored per-worktree, I just didn't know if any were actually "refs". Other than that technicality, which could be completely correct, this is a good idea to include. Thanks, -Stolee
