From: Junio C Hamano Date: Sun, 20 Feb 2022 20:42:10 GMT Subject: Re: [PATCH 05/11] worktree: use 'worktree' over 'working tree' Message-ID: In-Reply-To: "Derrick Stolee via GitGitGadget" writes: > From: Derrick Stolee > > It is helpful to distinguish between a 'working tree' and a 'worktree'. > A worktree contains a working tree plus additional metadata. This > metadata includes per-worktree refs and worktree-specific config. > > This is the first of multiple changes to git-worktree.txt, restricted to > the DESCRIPTION section. Looked almost perfect, except for one and a half iffy parts. > -If a working tree is deleted without using `git worktree remove`, then > ... > +If a worktree is deleted without using `git worktree remove`, then > its associated administrative files, which reside in the repository > (see "DETAILS" below), will eventually be removed automatically (see I think this one should be "working tree". The administrative files are integral part of a worktree, but from the point of view of a working tree, it is "associated" with it and not part of it. If you delete without using "git worktree remove", that would be done with a command like "rm -f", which removes the working tree but not the worktree. > -If a linked working tree is stored on a portable device or network share > -which is not always mounted, you can prevent its administrative files from > -being pruned by issuing the `git worktree lock` command, optionally > -specifying `--reason` to explain why the working tree is locked. > +If a linked worktree is stored on a portable device or network share which > +is not always mounted, you can prevent its administrative files from being > +pruned by issuing the `git worktree lock` command, optionally specifying > +`--reason` to explain why the worktree is locked. This one, because what is on a removal device is the working tree half of a worktree that leaves the "administrative files" half still on the mothership when it is removed, I think it is OK to call it a working tree, but because we defined "a linked worktree" and removed the definition of "a linked working tree" earlier, the original as-is won't work well. "If the working tree portion of a linked worktree is stored on ..." may be more correct, but it is a bit mouthful. I dunno (hence this is not even a full "iffy" part, just halfway iffy). > add []:: > > -Create `` and checkout `` into it. The new working directory > -is linked to the current repository, sharing everything except working > -directory specific files such as `HEAD`, `index`, etc. As a convenience, > -`` may be a bare "`-`", which is synonymous with `@{-1}`. > +Create `` and checkout `` into it. The new worktree > +is linked to the current repository, sharing everything except per-worktree > +files such as `HEAD`, `index`, etc. As a convenience, `` may > +be a bare "`-`", which is synonymous with `@{-1}`. The original has the problem, too, but it is unclear what is created at by reading only the first sentence, even though the mention of "The new worktree" that immediately follows strongly hints that we are creating a worktree. Create a new worktree at and ... perhaps? This clarification is not even part of one and a half ;-)