[11/11] worktree: use 'worktree' over 'working tree'

Commit Message

Derrick Stolee Feb. 20, 2022, 5:54 p.m. UTC

From: Derrick Stolee <[e-mail]>

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 last of multiple changes to git-worktree.txt, starting at
the LIST OUTPUT FORMAT section.

Signed-off-by: Derrick Stolee <[e-mail]>
---
 Documentation/git-worktree.txt | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

Comments

Taylor Blau Feb. 20, 2022, 10:37 p.m. UTC | #1

On Sun, Feb 20, 2022 at 05:54:27PM +0000, Derrick Stolee via GitGitGadget wrote:
> @@ -404,14 +404,14 @@ $ git worktree list --verbose
>  /path/to/linked-worktree              abcd1234 [master]
>  /path/to/locked-worktree-no-reason    abcd5678 (detached HEAD) locked
>  /path/to/locked-worktree-with-reason  1234abcd (brancha)
> -	locked: working tree path is mounted on a portable device
> +	locked: worktree path is mounted on a portable device

I thought this might have been an over-zealous find-and-replace, since I
had assumed that the "locked: working tree path ..." message came from
Git. But my assumption was wrong, and this is the `<reason>` in `git
worktree --reason=<reason> <worktree>`.

So it makes sense to update here along with the rest of these other
instances.

>  /path/to/prunable-worktree            5678abc1 (detached HEAD)
>  	prunable: gitdir file points to non-existent location
>  ------------
>
>  Note that the annotation is moved to the next line if the additional
>  information is available, otherwise it stays on the same line as the
> -working tree itself.
> +worktree itself.
>
>  Porcelain Format
>  ~~~~~~~~~~~~~~~~
> @@ -420,7 +420,7 @@ label and value separated by a single space.  Boolean attributes (like `bare`
>  and `detached`) are listed as a label only, and are present only
>  if the value is true.  Some attributes (like `locked`) can be listed as a label
>  only or with a value depending upon whether a reason is available.  The first
> -attribute of a working tree is always `worktree`, an empty line indicates the
> +attribute of a worktree is always `worktree`, an empty line indicates the
>  end of the record.  For example:
>
>  ------------
> @@ -470,9 +470,9 @@ EXAMPLES
>  You are in the middle of a refactoring session and your boss comes in and
>  demands that you fix something immediately. You might typically use
>  linkgit:git-stash[1] to store your changes away temporarily, however, your
> -working tree is in such a state of disarray (with new, moved, and removed
> +worktree is in such a state of disarray (with new, moved, and removed

This one should probably remain as "working tree", since the example
being given here is focused on disarray in the working tree itself, not
in the worktree's metadata.

>  files, and other bits and pieces strewn around) that you don't want to risk
> -disturbing any of it. Instead, you create a temporary linked working tree to
> +disturbing any of it. Instead, you create a temporary linked worktree to
>  make the emergency fix, remove it when done, and then resume your earlier
>  refactoring session.

But this one is in the context of "create a _worktree_", which makes
sense and should probably be updated as you have done here.

Thanks,
Taylor

Derrick Stolee Feb. 21, 2022, 2:11 a.m. UTC | #2

On 2/20/2022 5:37 PM, Taylor Blau wrote:
> On Sun, Feb 20, 2022 at 05:54:27PM +0000, Derrick Stolee via GitGitGadget wrote:
>> @@ -404,14 +404,14 @@ $ git worktree list --verbose
>>  /path/to/linked-worktree              abcd1234 [master]
>>  /path/to/locked-worktree-no-reason    abcd5678 (detached HEAD) locked
>>  /path/to/locked-worktree-with-reason  1234abcd (brancha)
>> -	locked: working tree path is mounted on a portable device
>> +	locked: worktree path is mounted on a portable device
> 
> I thought this might have been an over-zealous find-and-replace, since I
> had assumed that the "locked: working tree path ..." message came from
> Git. But my assumption was wrong, and this is the `<reason>` in `git
> worktree --reason=<reason> <worktree>`.
> 
> So it makes sense to update here along with the rest of these other
> instances.

This is a good catch. It could have easily been over-zealous.

>>  /path/to/prunable-worktree            5678abc1 (detached HEAD)
>>  	prunable: gitdir file points to non-existent location
>>  ------------
>>
>>  Note that the annotation is moved to the next line if the additional
>>  information is available, otherwise it stays on the same line as the
>> -working tree itself.
>> +worktree itself.
>>
>>  Porcelain Format
>>  ~~~~~~~~~~~~~~~~
>> @@ -420,7 +420,7 @@ label and value separated by a single space.  Boolean attributes (like `bare`
>>  and `detached`) are listed as a label only, and are present only
>>  if the value is true.  Some attributes (like `locked`) can be listed as a label
>>  only or with a value depending upon whether a reason is available.  The first
>> -attribute of a working tree is always `worktree`, an empty line indicates the
>> +attribute of a worktree is always `worktree`, an empty line indicates the
>>  end of the record.  For example:
>>
>>  ------------
>> @@ -470,9 +470,9 @@ EXAMPLES
>>  You are in the middle of a refactoring session and your boss comes in and
>>  demands that you fix something immediately. You might typically use
>>  linkgit:git-stash[1] to store your changes away temporarily, however, your
>> -working tree is in such a state of disarray (with new, moved, and removed
>> +worktree is in such a state of disarray (with new, moved, and removed
> 
> This one should probably remain as "working tree", since the example
> being given here is focused on disarray in the working tree itself, not
> in the worktree's metadata.

You're right. Thanks for catching this one.

>>  files, and other bits and pieces strewn around) that you don't want to risk
>> -disturbing any of it. Instead, you create a temporary linked working tree to
>> +disturbing any of it. Instead, you create a temporary linked worktree to
>>  make the emergency fix, remove it when done, and then resume your earlier
>>  refactoring session.
> 
> But this one is in the context of "create a _worktree_", which makes
> sense and should probably be updated as you have done here.

Thanks,
-Stolee

Patch

diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index 923b44d3fb2..1d5111ddba5 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -382,11 +382,11 @@  $ git worktree list
 /path/to/other-linked-worktree  1234abc  (detached HEAD)
 ------------
 
-The command also shows annotations for each working tree, according to its state.
+The command also shows annotations for each worktree, according to its state.
 These annotations are:
 
- * `locked`, if the working tree is locked.
- * `prunable`, if the working tree can be pruned via `git worktree prune`.
+ * `locked`, if the worktree is locked.
+ * `prunable`, if the worktree can be pruned via `git worktree prune`.
 
 ------------
 $ git worktree list
@@ -404,14 +404,14 @@  $ git worktree list --verbose
 /path/to/linked-worktree              abcd1234 [master]
 /path/to/locked-worktree-no-reason    abcd5678 (detached HEAD) locked
 /path/to/locked-worktree-with-reason  1234abcd (brancha)
-	locked: working tree path is mounted on a portable device
+	locked: worktree path is mounted on a portable device
 /path/to/prunable-worktree            5678abc1 (detached HEAD)
 	prunable: gitdir file points to non-existent location
 ------------
 
 Note that the annotation is moved to the next line if the additional
 information is available, otherwise it stays on the same line as the
-working tree itself.
+worktree itself.
 
 Porcelain Format
 ~~~~~~~~~~~~~~~~
@@ -420,7 +420,7 @@  label and value separated by a single space.  Boolean attributes (like `bare`
 and `detached`) are listed as a label only, and are present only
 if the value is true.  Some attributes (like `locked`) can be listed as a label
 only or with a value depending upon whether a reason is available.  The first
-attribute of a working tree is always `worktree`, an empty line indicates the
+attribute of a worktree is always `worktree`, an empty line indicates the
 end of the record.  For example:
 
 ------------
@@ -470,9 +470,9 @@  EXAMPLES
 You are in the middle of a refactoring session and your boss comes in and
 demands that you fix something immediately. You might typically use
 linkgit:git-stash[1] to store your changes away temporarily, however, your
-working tree is in such a state of disarray (with new, moved, and removed
+worktree is in such a state of disarray (with new, moved, and removed
 files, and other bits and pieces strewn around) that you don't want to risk
-disturbing any of it. Instead, you create a temporary linked working tree to
+disturbing any of it. Instead, you create a temporary linked worktree to
 make the emergency fix, remove it when done, and then resume your earlier
 refactoring session.