On Tue, Feb 8, 2022 at 2:20 PM Junio C Hamano <gitster@xxxxxxxxx> 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. > > 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. > > 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) We could also add pseudorefs to the list of things maintained separately in the final parenthetical comment, but otherwise looks good.
