On 2/24/2022 9:33 AM, Philip Oakley wrote: > On 20/02/2022 17:54, Derrick Stolee via GitGitGadget wrote: >> From: Derrick Stolee <derrickstolee@xxxxxxxxxx> >> >> 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. > Doesn't this need a clear call-out in the text to highlight the > distinction, so that it is obvious at first glance to the casual reader? > > I'd ended up with something like: > - worktree > A directory whose files and sub-directories are (selectively) under > Git revision management. > - working tree > The working tree comprises Git revision management meta-data for the > worktree, > and the worktree itself. > The meta-data may be independently located away from the worktree's > data. > > The key feature is to have a layout structure that shows the distinction. See below where I mention that the first paragraph points out this distinction. Your use of bullets makes it even more clear, and I think that would be more valuable if this wasn't the very first thing in the document. > Or are we trying to remove all references to "working tree"? Or have I > misunderstood? ... >> A git repository can support multiple working trees, allowing you to check > Are we removing the above "working trees" phrases as well? This one is important to keep. The worktree feature is how Git manages multiple working trees. The reason for switching most of the other references is because the discussion applies specifically to worktrees, not working trees. >> out more than one branch at a time. With `git worktree add` a new working >> -tree is associated with the repository. This new working tree is called a >> -"linked working tree" as opposed to the "main working tree" prepared by >> -linkgit:git-init[1] or linkgit:git-clone[1]. >> -A repository has one main working tree (if it's not a >> -bare repository) and zero or more linked working trees. When you are done >> -with a linked working tree, remove it with `git worktree remove`. >> +tree is associated with the repository, along with additional metadata >> +that differentiates that working tree from others in the same repository. >> +The working tree, along with this metada, is called a "worktree". This first paragraph is all about the distinction between working tree and worktree, so it hopefully handles the concerns you had above. Thanks, -Stolee
