On Wed, Feb 9, 2022 at 6:19 PM Junio C Hamano <gitster@xxxxxxxxx> wrote: > > We have description on "per worktree ref", but "worktree" is not > described in the glossary. We do have "working tree", though. > > Casually put, a "working tree" is what your editor and compiler > interacts with. "worktree" is a mechanism to allow one or more > "working tree"s to be attached to a repository and used to check out > different commits and branches independently, which includes not > just a "working tree" but also repository metadata like HEAD, the > index to support simultaneous use of them. Historically, we used > these terms interchangeably but we have been trying to use "working > tree" when we mean it, instead of "worktree". > > Most of the existing references to "working tree" in the glossary do > refer primarily to the working tree portion, except for one that > said refs like HEAD and refs/bisect/* are per "working tree", but it > is more precise to say they are per "worktree". > > Signed-off-by: Junio C Hamano <gitster@xxxxxxxxx> > --- > > * Mostly unchanged from the version in the original discussion > https://lore.kernel.org/git/xmqqo83hatm1.fsf@gitster.g/ except > that we now mention that pseudorefs are also per worktree. > > One thing that makes me worried somewhat is what I did not touch, > namely, how pseudo refs are defined. I know MERGE_HEAD is very > special and it may be impossible to coax it into refs API for > writing, so the text there makes sense for it, but there are > other all-caps-and-directly-under-dot-git-directory files like > ORIG_HEAD and CHERRY_PICK_HEAD that are written using the refs > API, so the description would have to be updated there. I'm not quite following; why would the description need to be updated? Sure MERGE_HEAD is written without using the refs API, but we didn't mention how the pseduorefs were written in the description, and all of MERGE_HEAD, CHERRY_PICK_HEAD, ORIG_HEAD, REVERT_HEAD get written per-worktree so doesn't "pseudorefs like MERGE_HEAD" cover it as far as the reader is concerned? > Documentation/glossary-content.txt | 13 +++++++++++-- > 1 file changed, 11 insertions(+), 2 deletions(-) > > diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt > index c077971335..9eb8920552 100644 > --- a/Documentation/glossary-content.txt > +++ b/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 and pseudorefs like MERGE_HEAD, > + per-worktree refs and per-worktree configuration file). > -- > 2.35.1-102-g2b9c120970 The text looks good to me.
