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

From: Derrick Stolee <derrickstolee@github.com>
Date: Feb 20, 2022, 20:48 UTC
Message-ID: <fcaac95c-013a-f82b-f359-b9b58dc7d2a9@github.com>
In-Reply-To: <xmqq7d9puv6l.fsf@gitster.g>

On 2/20/2022 3:42 PM, Junio C Hamano wrote:

Show 25 quoted lines

> "Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 
>> 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.
>>
>> 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.

Good point. I agree. There is some similar discussion in the COMMANDS
section around moving/renaming/repairing worktrees, so likely similar
thoughts apply there, too.

Show 19 quoted lines

>> -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).

I think the wordy way you say it here is the most correct way.

Another way to approach this is to start at the definition by saying "We will refer to the location of a worktree to be its associated working directory, even though its metadata is stored in another location."

That could allow us to use "worktree" even in these cases, but does create some overloading of the word.

Show 19 quoted lines

>>  add <path> [<commit-ish>]::
>>  
>> -Create `<path>` and checkout `<commit-ish>` 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,
>> -`<commit-ish>` may be a bare "`-`", which is synonymous with `@{-1}`.
>> +Create `<path>` and checkout `<commit-ish>` 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, `<commit-ish>` may
>> +be a bare "`-`", which is synonymous with `@{-1}`.
> 
> The original has the problem, too, but it is unclear what is created
> at <path> 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 <path> and ...
> 
> perhaps?  This clarification is not even part of one and a half ;-)

This is a good change.

Thanks, -Stolee