Sorry for the delay in replying. I had some family matters to attend to. On 24/02/2022 15:53, Derrick Stolee wrote: > 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. I don't really buy the "first paragraph points out this distinction" because it's still part of a wall of text, so not easy to locate. It's not helped by the top line NAME which uses both `worktree` and `working tree` as if they are equivalent. Though that could be easily solved by making it: git-worktree - Manage multiple working trees and their meta-data which would highlight the two distinct parts. (could also add the `git/user` distinction as below) You'll probably also have noticed how even in my original suggestion, I'd still misread the partition and got worktree/working-tree swapped over, so it is easily done. If we are trying to have clarity on the worktree/working-tree distinction, I still think it needs to be made very obvious, with perhaps even the naming of the _git_ meta data part, or at least calling it out as being the independent of the _users_ working tree . Philip > >> 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
