On Wed, Sep 6, 2023, at 18:39, Sergey Organov wrote: >> -- >8 -- >> Subject: [PATCH] Try to reword what a worktree is >> >> --- >> Documentation/glossary-content.txt | 6 +++++- >> 1 file changed, 5 insertions(+), 1 deletion(-) >> >> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt >> index 5a537268e2..5e192fb5dc 100644 >> --- a/Documentation/glossary-content.txt >> +++ b/Documentation/glossary-content.txt >> @@ -694,10 +694,14 @@ The most notable example is `HEAD`. >> plus any local changes that you have made but not yet committed. >> >> [[def_worktree]]worktree:: >> - A repository can have zero (i.e. bare repository) or one or >> + A repository can have zero 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). >> ++ >> +Note that the directory tree of a <<def_bare_repository,bare_repository>> >> +may have linked worktrees, but cannot itself be a worktree since it has no >> +working tree. > > Reading this with a fresh eye, I wonder if we'd better distinguish > between "inline" worktree and "attached" worktrees? > > As I see it, in fact a repository can have zero (i.e. bare repository) > or one inline worktree, as well as zero or more attached worktrees. Ah, thank you. I felt like the glossary/nomenclature was missing a few words and these ones seem to fill things in nicely. Now I'm just skeptical of the other wording issue about “bare repository”, which might be somewhat out of place in the face of zero-to-multiple worktrees. Going back to my example in the previous email: • `repository.git` is a *bare repository* which has no *inline worktree* and three *attached worktrees* [I really like how inline/attached work here] • `a` is an *attached worktree* of `repository.git` • `a`, `b`, `c` are all the *worktrees* of the *bare repository* `repository.git` [“bare” here just emphasizes that `repository.git` does not have a worktree (“what about the worktree in `repository.git`?”)] Does that sound right? (Asking no one in particular.) Personally I think that it sounds more coherent than before I wrote it (than I thought it would). -- Kristoffer Haugsbakk
