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 second of multiple changes to git-worktree.txt, restricted
to the COMMANDS section.

There is some language around the movement of "the working tree of a
linked worktree" which is used once, but the remaining uses are left as
just moving "a linked worktree" for brevity.

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>
maint
Derrick Stolee 2022-02-23 14:29:14 +00:00 committed by Junio C Hamano
parent c57bf8ce9e
commit 599701441e
1 changed files with 41 additions and 44 deletions

View File

@ -88,75 +88,72 @@ branches from there if `<branch>` is ambiguous but exists on the
linkgit:git-config[1]. linkgit:git-config[1].
+ +
If `<commit-ish>` is omitted and neither `-b` nor `-B` nor `--detach` used, If `<commit-ish>` is omitted and neither `-b` nor `-B` nor `--detach` used,
then, as a convenience, the new working tree is associated with a branch then, as a convenience, the new worktree is associated with a branch (call
(call it `<branch>`) named after `$(basename <path>)`. If `<branch>` it `<branch>`) named after `$(basename <path>)`. If `<branch>` doesn't
doesn't exist, a new branch based on `HEAD` is automatically created as exist, a new branch based on `HEAD` is automatically created as if
if `-b <branch>` was given. If `<branch>` does exist, it will be `-b <branch>` was given. If `<branch>` does exist, it will be checked out
checked out in the new working tree, if it's not checked out anywhere in the new worktree, if it's not checked out anywhere else, otherwise the
else, otherwise the command will refuse to create the working tree (unless command will refuse to create the worktree (unless `--force` is used).
`--force` is used).


list:: list::


List details of each working tree. The main working tree is listed first, List details of each worktree. The main worktree is listed first,
followed by each of the linked working trees. The output details include followed by each of the linked worktrees. The output details include
whether the working tree is bare, the revision currently checked out, the whether the worktree is bare, the revision currently checked out, the
branch currently checked out (or "detached HEAD" if none), "locked" if branch currently checked out (or "detached HEAD" if none), "locked" if
the worktree is locked, "prunable" if the worktree can be pruned by `prune` the worktree is locked, "prunable" if the worktree can be pruned by the
command. `prune` command.


lock:: lock::


If a working tree is on a portable device or network share which If a worktree is on a portable device or network share which is not always
is not always mounted, lock it to prevent its administrative mounted, lock it to prevent its administrative files from being pruned
files from being pruned automatically. This also prevents it from automatically. This also prevents it from being moved or deleted.
being moved or deleted. Optionally, specify a reason for the lock Optionally, specify a reason for the lock with `--reason`.
with `--reason`.


move:: move::


Move a working tree to a new location. Note that the main working tree Move a worktree to a new location. Note that the main worktree or linked
or linked working trees containing submodules cannot be moved with this worktrees containing submodules cannot be moved with this command. (The
command. (The `git worktree repair` command, however, can reestablish `git worktree repair` command, however, can reestablish the connection
the connection with linked working trees if you move the main working with linked worktrees if you move the main worktree manually.)
tree manually.)


prune:: prune::


Prune working tree information in `$GIT_DIR/worktrees`. Prune worktree information in `$GIT_DIR/worktrees`.


remove:: remove::


Remove a working tree. Only clean working trees (no untracked files Remove a worktree. Only clean worktrees (no untracked files and no
and no modification in tracked files) can be removed. Unclean working modification in tracked files) can be removed. Unclean worktrees or ones
trees or ones with submodules can be removed with `--force`. The main with submodules can be removed with `--force`. The main worktree cannot be
working tree cannot be removed. removed.


repair [<path>...]:: repair [<path>...]::


Repair working tree administrative files, if possible, if they have Repair worktree administrative files, if possible, if they have become
become corrupted or outdated due to external factors. corrupted or outdated due to external factors.
+ +
For instance, if the main working tree (or bare repository) is moved, For instance, if the main worktree (or bare repository) is moved, linked
linked working trees will be unable to locate it. Running `repair` in worktrees will be unable to locate it. Running `repair` in the main
the main working tree will reestablish the connection from linked worktree will reestablish the connection from linked worktrees back to the
working trees back to the main working tree. main worktree.
+ +
Similarly, if a linked working tree is moved without using `git worktree Similarly, if the working tree for a linked worktree is moved without
move`, the main working tree (or bare repository) will be unable to using `git worktree move`, the main worktree (or bare repository) will be
locate it. Running `repair` within the recently-moved working tree will unable to locate it. Running `repair` within the recently-moved worktree
reestablish the connection. If multiple linked working trees are moved, will reestablish the connection. If multiple linked worktrees are moved,
running `repair` from any working tree with each tree's new `<path>` as running `repair` from any worktree with each tree's new `<path>` as an
an argument, will reestablish the connection to all the specified paths. argument, will reestablish the connection to all the specified paths.
+ +
If both the main working tree and linked working trees have been moved If both the main worktree and linked worktrees have been moved manually,
manually, then running `repair` in the main working tree and specifying the then running `repair` in the main worktree and specifying the new `<path>`
new `<path>` of each linked working tree will reestablish all connections of each linked worktree will reestablish all connections in both
in both directions. directions.


unlock:: unlock::


Unlock a working tree, allowing it to be pruned, moved or deleted. Unlock a worktree, allowing it to be pruned, moved or deleted.


OPTIONS OPTIONS
------- -------