On Tue, Sep 5, 2023, at 02:38, Eric Sunshine wrote:
> Speaking as a person involved in the implementation of worktrees,
> including support for them in combination with bare repositories, my
> reading of this is perhaps biased so that I understand its intent.
> However, if I squint hard, I suppose I can see how you could read it
> as meaning that a bare repository can't have any worktrees associated
> with it. So, perhaps, the documentation could use a bit of touch up.
My interpretation of the documentation leads to contradictions. So I
thought of another one: A bare repository *can* have worktrees, but if it
does will in that case only have *linked* worktrees, since the
`repository.git` directory by definition does not have a working tree and
it therefore cannot be considered a worktree itself. By extension, a
linked worktree might be linked to a bare repository. Thus there is no
contradiction.
For example: there are four directory trees associated with the `repo`
repository:
1. `repo.git`: the directory tree with the bare repository; no worktree in
*that* directory tree
2. `a`: worktree with a gitfile that points to `repo.git`
3. `b`: worktree with a gitfile that points to `repo.git`
4. `c`: worktree with a gitfile that points to `repo.git`
So you have:
• One repository
• Four directory trees
• Three worktrees
This interpretation seems completely in line with “bare repository” in the
glossary:
“ A bare repository is normally an appropriately named directory with a
.git suffix that does not have a locally checked-out copy of any of
the files under revision control. That is, all of the Git
administrative and control files that would normally be present in the
hidden .git sub-directory are directly present in the repository.git
directory instead, and no other files are present and checked
out. Usually publishers of public repositories make bare repositories
available.
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.
Nothwithstanding any implementation/documentation disagreement, I think
that this interpretation at least is coherent.
But note how (for me) it is a bit awkward to refer to a “bare repository”
in this context since I need to add “the directory tree” in order to
emphasize that we are talking about `repo.git`; normally you can kind of
loosely talk about “the repository” and still get the precise meaning that
you intend across, but in this case we have four directory trees which are
all *the same repository*. (Right?) So just saying “the bare repository”
can be misleading since it might hint that the three worktrees are not
part of the repository. (Perhaps there isn't enough nomenclature to
clearly talk about this particular case/setup?)
But with all of that in mind, perhaps the glossary could read something
like this instead (no reflowing):[1][2]
(`man git-worktree` might also need to be updated.)
† 1: Applied onto 1fc548b2d6 (The sixth batch, 2023-09-05)
🔗 2: https://github.com/git/git/compare/master...LemmingAvalanche:git:bare-and-worktrees?expand=1
Cheers
Kristoffer
-- >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.
--
2.42.0
