On Wed, Sep 6, 2023 at 10:26 PM Junio C Hamano <gitster@xxxxxxxxx> wrote: > > Tao Klerks <tao@xxxxxxxxxx> writes: > > > I like the nomenclature, I like the simple "zero (i.e. bare) or one > > inline worktree, zero or more attached worktrees" explanation. > > We have used "main worktree" to refer to the working tree part (plus > the repository) of a non-bare repository. And it makes sense to > explain it together with the concept of "worktree", as the primary > one is very much special in that it cannot be removed. You can see > that "git worktree remove" would stop you from removing it with an > error message: > > fatal: '../there' is a main working tree. > > It probably does not add much value to introduce a new term > "inline". Here is what "git worktree --help" has to say about it. > > A repository has one main worktree (if it's not a bare repository) and > zero or more linked worktrees. I've definitely changed my mind about "inline", I agree "main" is better. I'm not convinced it's the best word we could come up with, but if it's well-established, I'm happy with it. The problem I (now) see with "inline" is that it seems to imply a spatial proximity that doesn't necessarily hold true, with "--separate-git-dir" or other ways to separate the main worktree from its usual "just above the .git directory" location. "Inline" is still a reasonable qualification of the main worktree's *metadata* in that situation (index, etc), but I think the word would not be sufficiently clear/representative overall. > > I applaud whoever wrote this sentence for packing so much good > information in a concise and easy-to-understand description. I also like this sentence, it's basically equivalent to Sergey's sentence above. > > We can read that (1) a non-bare repository itself is considered > its "main worktree", (2) a bare repository, by inference, has no > main worktree (otherwise we wouldn't have said "if it's not"), and > (3) both bare and non-bare repositories can have linked worktrees > (again, otherwise we wouldn't have brought up a bare repository in > the description). > > Perhaps we should borrow it to update the glossary, like so? > Looks good to me, but that leaves me with a different nitpick: we say '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' This claims that the *shared metadata* (presumably the refs, the branch reflogs, the objects, the config, etc) are *part of the worktree* (a worktree "consists of" them and other things). That seems like a very strange way to conceive of things, to me. I would find it reasonable to state that the main worktree is part of the repo - certainly that's now most everyday users would think of it, if they were made to think of the worktree concept at all - but not that the shared repo metadata is part of the worktree, and especially not that the shared repo metadata is part of the attached worktrees. I imagine that this weird phrasing intends to allude to the fact that a worktree is "broken" without the repository metadata folder that contains both its worktree-specific metadata and the shared metadata that it depends just as much on... but can we come up with better "relationship words here? * A repository "has" zero or more worktrees * If it "has" a "main" worktree it is not a bare repository, otherwise it is. * It can have any number of "attached" worktrees If a repo "has" these worktrees, is it in the sense that I "have" arms and legs, and I "consist of" a person with arms and legs and other body parts, or is it in the sense that I "have" a lifetime, opinions, legal rights, and other things that I have as a consequence of being a person, but are not "part of" me? Similarly, do we have a term for "the directory that contains the 'refs' and 'objects' folders and stuff", regardless of whether it is in fact the entire bare repository, typically with a name other than ".git", or it is nested in a main worktree in the usual fashion as ".git", or it is separated (and again, typically differently-named) in a "--separate-git-dir" topology? I called it a "repository metadata folder" above, but I'm not sure whether there is a correct, succinct term for it. Wrt to the "shared among other worktrees" bit specifically, I agree with Sergey that "shared among all" would be clearer, but it's still weird, because all of that shared metadata is "inherent to the repo" beyond any and all worktrees. If this happens to be a bare repo, and we remove all the attached worktrees, the metadata is still just as meaningful - so saying that it was "shared among the worktrees", while true, seems to be unnecessarily implying a smaller purpose/meaning than appropriate. Sorry to continue nitpicking - I would love to see a clear nomenclature and description of these parts and their relationships for people (with less git experience) to "get it" more easily. > > Documentation/glossary-content.txt | 4 ++-- > 1 file changed, 2 insertions(+), 2 deletions(-) > > diff --git c/Documentation/glossary-content.txt w/Documentation/glossary-content.txt > index 5a537268e2..d9ba3bab88 100644 > --- c/Documentation/glossary-content.txt > +++ w/Documentation/glossary-content.txt > @@ -694,8 +694,8 @@ 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 > - more worktrees attached to it. One "worktree" consists of a > + A repository has one main worktree (if it's not a bare > + repository) and zero or more linked worktrees. 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
