Re: [PATCH 05/11] worktree: use 'worktree' over 'working tree'

[Philip Oakley <philipoakley@iee.email>]

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@github.com>
>>>
>>> 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