Subject: Re: Is "bare"ness in the context of multiple worktrees weird? Bitmap error in git gc.

From: Junio C Hamano <[email-masked]>
Date: Wed, 06 Sep 2023 12:10:26 -0700

Junio C Hamano <[email-masked]> writes:

> "Kristoffer Haugsbakk" <[email-masked]> writes:
>
>> But not with “worktree”:
>>
>>   “ A repository can have zero (i.e. bare repository) or one or more
>>     worktrees attached to it. ...
>>
>> Since this entry claims that “bare repository” and “zero worktrees” are
>> equivalent.
>
> I wrote that "(i.e. bare repository)" in 2df5387e (glossary:
> describe "worktree", 2022-02-09) but did not mean that way.  
>
> A non-bare repository can reduce the number of its worktrees, but it
> cannot go below one, because the directory with working tree files
> and the .git/ subdirectory, i.e. its primary worktree, must exist
> for it to be a non-bare repository.  Consequently a repository with
> zero worktree is by definition a bare repository.
>
> But that does not have to mean all bare repositories can have no
> worktrees.

I re-read the glossary entry and I think the current text is mostly
OK, except that it does not even have to mention "bare" at that
position in the sentence.  A bare repository with zero worktrees is
totally uninteresting in the explanation of the worktree.

We need to say that the repository data (configuration, refs and
objecs) are mostly shared among worktrees while some data are kept
per-worktree, which the current text adequately covers, and what is
missing with respect to a bare repository is that we do not say
worktrees can be attached after the fact to a repository that was
created bare.

So, perhaps something along this line?

 Documentation/glossary-content.txt | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git c/Documentation/glossary-content.txt w/Documentation/glossary-content.txt
index 5a537268e2..6dba68ffc0 100644
--- c/Documentation/glossary-content.txt
+++ w/Documentation/glossary-content.txt
@@ -694,10 +694,12 @@ 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
-	"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).
+	A repository can have zero 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 worktrees can be attached to an existing bare repository.