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

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 20, 2022, 20:42 UTC
Message-ID: <xmqq7d9puv6l.fsf@gitster.g>
In-Reply-To: <a6a8eb8e7bb4520bfe37d3a79329cce7886af59c.1645379667.git.gitgitgadget@gmail.com>

"Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> writes:

Show 8 quoted lines

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

Show 5 quoted lines

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

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

Show 10 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 ;-)