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

From: Sergey Organov <[email-masked]>
Date: Thu, 07 Sep 2023 01:11:37 +0300

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

> 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.

Sounds reasonable.

>
> 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.

Why? Worktree could be attached after the fact to any repository. I
don't see why we need to mention bareness here, as it's not special in
this regard.

>
> 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.

"shared among other worktrees" -> "shared among all worktrees"?

Also, if we do have "main worktree" and "linked worktree" as concepts,
they need to be at least mentioned in the glossary, I believe.

Finally, if we do have "linked worktrees", then the phrasing should
better use "linked" instead of "attached"? Alternatively, if "attached"
fits better, let's call them "attached worktrees"?

-- 
Sergey Organov