worktree: use 'worktree' over 'working tree'

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 <gitster@pobox.com>
Signed-off-by: Derrick Stolee <derrickstolee@github.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Derrick Stolee 2022-02-23 14:29:13 +00:00 committed by Junio C Hamano
parent 23f832e29e
commit c57bf8ce9e

View File

@ -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 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 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 tree is associated with the repository, along with additional metadata
"linked working tree" as opposed to the "main working tree" prepared by that differentiates that working tree from others in the same repository.
linkgit:git-init[1] or linkgit:git-clone[1]. The working tree, along with this metadata, is called a "worktree".
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 This new worktree is called a "linked worktree" as opposed to the "main
with a linked working tree, remove it with `git worktree remove`. 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 In its simplest form, `git worktree add <path>` automatically creates a
new branch whose name is the final component of `<path>`, which is 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 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 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 path `../hotfix`. To instead work on an existing branch in a new worktree,
tree, use `git worktree add <path> <branch>`. On the other hand, if you use `git worktree add <path> <branch>`. On the other hand, if you just
just plan to make some experimental changes or do testing without plan to make some experimental changes or do testing without disturbing
disturbing existing development, it is often convenient to create a existing development, it is often convenient to create a 'throwaway'
'throwaway' working tree not associated with any branch. For instance, worktree not associated with any branch. For instance,
`git worktree add -d <path>` creates a new working tree with a detached `git worktree add -d <path>` creates a new worktree with a detached `HEAD`
`HEAD` at the same commit as the current branch. at the same commit as the current branch.
If a working tree is deleted without using `git worktree remove`, then If a working tree is deleted without using `git worktree remove`, then
its associated administrative files, which reside in the repository its associated administrative files, which reside in the repository
(see "DETAILS" below), will eventually be removed automatically (see (see "DETAILS" below), will eventually be removed automatically (see
`gc.worktreePruneExpire` in linkgit:git-config[1]), or you can run `gc.worktreePruneExpire` in linkgit:git-config[1]), or you can run
`git worktree prune` in the main or any linked working tree to `git worktree prune` in the main or any linked worktree to clean up any
clean up any stale administrative files. stale administrative files.
If a linked working tree is stored on a portable device or network share If the working tree for a linked worktree is stored on a portable device
which is not always mounted, you can prevent its administrative files from or network share which is not always mounted, you can prevent its
being pruned by issuing the `git worktree lock` command, optionally administrative files from being pruned by issuing the `git worktree lock`
specifying `--reason` to explain why the working tree is locked. command, optionally specifying `--reason` to explain why the worktree is
locked.
COMMANDS COMMANDS
-------- --------
add <path> [<commit-ish>]:: add <path> [<commit-ish>]::
Create `<path>` and checkout `<commit-ish>` into it. The new working directory Create a worktree at `<path>` and checkout `<commit-ish>` into it. The new worktree
is linked to the current repository, sharing everything except working is linked to the current repository, sharing everything except per-worktree
directory specific files such as `HEAD`, `index`, etc. As a convenience, files such as `HEAD`, `index`, etc. As a convenience, `<commit-ish>` may
`<commit-ish>` may be a bare "`-`", which is synonymous with `@{-1}`. be a bare "`-`", which is synonymous with `@{-1}`.
+ +
If `<commit-ish>` is a branch name (call it `<branch>`) and is not found, 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 and neither `-b` nor `-B` nor `--detach` are used, but there does