[v2,05/11] worktree: use 'worktree' over 'working tree'

Commit Message

Derrick Stolee Feb. 22, 2022, 12:17 a.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 first of multiple changes to git-worktree.txt, restricted to
the DESCRIPTION section.

Helped-by: Junio C Hamano <[e-mail]>
Signed-off-by: Derrick Stolee <[e-mail]>
---
 Documentation/git-worktree.txt | 50 ++++++++++++++++++----------------
 1 file changed, 27 insertions(+), 23 deletions(-)

Comments

Junio C Hamano Feb. 22, 2022, 7:22 a.m. UTC | #1

"Derrick Stolee via GitGitGadget" <[e-mail]> writes:

> +If the working tree for a a linked worktree is stored on a portable device

a a.

I've prepared the following to be squashed locally.  I also have
another small one for 06/11.

Since 05/11-11/11 all share exactly the same subject, I am not sure
how well "git rebase -i --autosquash" would work, though.  I suspect
it would so very poorly.

Subject: [PATCH] fixup! worktree: use 'worktree' over 'working tree'

---
 Documentation/git-worktree.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index 1243332d72..46afc7224f 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -54,7 +54,7 @@ its associated administrative files, which reside in the repository
 `git worktree prune` in the main or any linked worktree to clean up any
 stale administrative files.
 
-If the working tree for a a linked worktree is stored on a portable device
+If the working tree for 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

Elijah Newren Feb. 23, 2022, 6:47 a.m. UTC | #2

On Mon, Feb 21, 2022 at 4:18 PM Derrick Stolee via GitGitGadget
<[e-mail]> wrote:
>
> 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 first of multiple changes to git-worktree.txt, restricted to
> the DESCRIPTION section.
>
> Helped-by: Junio C Hamano <[e-mail]>
> Signed-off-by: Derrick Stolee <[e-mail]>
> ---
>  Documentation/git-worktree.txt | 50 ++++++++++++++++++----------------
>  1 file changed, 27 insertions(+), 23 deletions(-)
>
> diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
> index b8d53c48303..27437615436 100644
> --- a/Documentation/git-worktree.txt
> +++ b/Documentation/git-worktree.txt
> @@ -25,45 +25,49 @@ Manage multiple working trees attached to the same repository.
>
>  A git repository can support multiple working trees, allowing you to check
>  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".

Looks like the "metada" typo still persisted.

> +This new worktree is called a "linked worktree" as opposed to the "main
> +worktree" prepared by linkgit:git-init[1] or linkgit:git-clone[1].
> +A repository has one main worktree (if it's not a bare repository) and
> +zero or more linked worktrees. When you are done with a linked worktree,
> +remove it with `git worktree remove`.
>
>  In its simplest form, `git worktree add <path>` automatically creates a
>  new branch whose name is the final component of `<path>`, which is
>  convenient if you plan to work on a new topic. For instance, `git
>  worktree add ../hotfix` creates new branch `hotfix` and checks it out at
> -path `../hotfix`. To instead work on an existing branch in a new working
> -tree, use `git worktree add <path> <branch>`. On the other hand, if you
> -just plan to make some experimental changes or do testing without
> -disturbing existing development, it is often convenient to create a
> -'throwaway' working tree not associated with any branch. For instance,
> -`git worktree add -d <path>` creates a new working tree with a detached
> -`HEAD` at the same commit as the current branch.
> +path `../hotfix`. To instead work on an existing branch in a new worktree,
> +use `git worktree add <path> <branch>`. On the other hand, if you just
> +plan to make some experimental changes or do testing without disturbing
> +existing development, it is often convenient to create a 'throwaway'
> +worktree not associated with any branch. For instance,
> +`git worktree add -d <path>` creates a new worktree with a detached `HEAD`
> +at the same commit as the current branch.
>
>  If a working tree 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
>  `gc.worktreePruneExpire` in linkgit:git-config[1]), or you can run
> -`git worktree prune` in the main or any linked working tree to
> -clean up any stale administrative files.
> +`git worktree prune` in the main or any linked worktree to clean up any
> +stale administrative files.
>
> -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 the working tree for a a linked worktree is stored on a portable device

If you re-roll, don't forget to correct the "a a" too.  :-)

> +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.
>
>  COMMANDS
>  --------
>  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 a worktree at `<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}`.
>  +
>  If `<commit-ish>` is a branch name (call it `<branch>`) and is not found,
>  and neither `-b` nor `-B` nor `--detach` are used, but there does
> --
> gitgitgadget

Patch

diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index b8d53c48303..27437615436 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -25,45 +25,49 @@  Manage multiple working trees attached to the same repository.
 
 A git repository can support multiple working trees, allowing you to check
 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 new worktree is called a "linked worktree" as opposed to the "main
+worktree" prepared by linkgit:git-init[1] or linkgit:git-clone[1].
+A repository has one main worktree (if it's not a bare repository) and
+zero or more linked worktrees. When you are done with a linked worktree,
+remove it with `git worktree remove`.
 
 In its simplest form, `git worktree add <path>` automatically creates a
 new branch whose name is the final component of `<path>`, which is
 convenient if you plan to work on a new topic. For instance, `git
 worktree add ../hotfix` creates new branch `hotfix` and checks it out at
-path `../hotfix`. To instead work on an existing branch in a new working
-tree, use `git worktree add <path> <branch>`. On the other hand, if you
-just plan to make some experimental changes or do testing without
-disturbing existing development, it is often convenient to create a
-'throwaway' working tree not associated with any branch. For instance,
-`git worktree add -d <path>` creates a new working tree with a detached
-`HEAD` at the same commit as the current branch.
+path `../hotfix`. To instead work on an existing branch in a new worktree,
+use `git worktree add <path> <branch>`. On the other hand, if you just
+plan to make some experimental changes or do testing without disturbing
+existing development, it is often convenient to create a 'throwaway'
+worktree not associated with any branch. For instance,
+`git worktree add -d <path>` creates a new worktree with a detached `HEAD`
+at the same commit as the current branch.
 
 If a working tree 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
 `gc.worktreePruneExpire` in linkgit:git-config[1]), or you can run
-`git worktree prune` in the main or any linked working tree to
-clean up any stale administrative files.
+`git worktree prune` in the main or any linked worktree to clean up any
+stale administrative files.
 
-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 the working tree for a 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.
 
 COMMANDS
 --------
 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 a worktree at `<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}`.
 +
 If `<commit-ish>` is a branch name (call it `<branch>`) and is not found,
 and neither `-b` nor `-B` nor `--detach` are used, but there does