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>
This commit is contained in:
Derrick Stolee
2022-02-23 14:29:14 +00:00
committed by Junio C Hamano
parent c57bf8ce9e
commit 599701441e

View File

@ -88,75 +88,72 @@ branches from there if `<branch>` is ambiguous but exists on the
linkgit:git-config[1].
+
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
(call it `<branch>`) named after `$(basename <path>)`. If `<branch>`
doesn't exist, a new branch based on `HEAD` is automatically created as
if `-b <branch>` was given. If `<branch>` does exist, it will be
checked out in the new working tree, if it's not checked out anywhere
else, otherwise the command will refuse to create the working tree (unless
`--force` is used).
then, as a convenience, the new worktree is associated with a branch (call
it `<branch>`) named after `$(basename <path>)`. If `<branch>` doesn't
exist, a new branch based on `HEAD` is automatically created as if
`-b <branch>` was given. If `<branch>` does exist, it will be checked out
in the new worktree, if it's not checked out anywhere else, otherwise the
command will refuse to create the worktree (unless `--force` is used).
list::
List details of each working tree. The main working tree is listed first,
followed by each of the linked working trees. The output details include
whether the working tree is bare, the revision currently checked out, the
List details of each worktree. The main worktree is listed first,
followed by each of the linked worktrees. The output details include
whether the worktree is bare, the revision currently checked out, the
branch currently checked out (or "detached HEAD" if none), "locked" if
the worktree is locked, "prunable" if the worktree can be pruned by `prune`
command.
the worktree is locked, "prunable" if the worktree can be pruned by the
`prune` command.
lock::
If a working tree is on a portable device or network share which
is not always mounted, lock it to prevent its administrative
files from being pruned automatically. This also prevents it from
being moved or deleted. Optionally, specify a reason for the lock
with `--reason`.
If a worktree is on a portable device or network share which is not always
mounted, lock it to prevent its administrative files from being pruned
automatically. This also prevents it from being moved or deleted.
Optionally, specify a reason for the lock with `--reason`.
move::
Move a working tree to a new location. Note that the main working tree
or linked working trees containing submodules cannot be moved with this
command. (The `git worktree repair` command, however, can reestablish
the connection with linked working trees if you move the main working
tree manually.)
Move a worktree to a new location. Note that the main worktree or linked
worktrees containing submodules cannot be moved with this command. (The
`git worktree repair` command, however, can reestablish the connection
with linked worktrees if you move the main worktree manually.)
prune::
Prune working tree information in `$GIT_DIR/worktrees`.
Prune worktree information in `$GIT_DIR/worktrees`.
remove::
Remove a working tree. Only clean working trees (no untracked files
and no modification in tracked files) can be removed. Unclean working
trees or ones with submodules can be removed with `--force`. The main
working tree cannot be removed.
Remove a worktree. Only clean worktrees (no untracked files and no
modification in tracked files) can be removed. Unclean worktrees or ones
with submodules can be removed with `--force`. The main worktree cannot be
removed.
repair [<path>...]::
Repair working tree administrative files, if possible, if they have
become corrupted or outdated due to external factors.
Repair worktree administrative files, if possible, if they have become
corrupted or outdated due to external factors.
+
For instance, if the main working tree (or bare repository) is moved,
linked working trees will be unable to locate it. Running `repair` in
the main working tree will reestablish the connection from linked
working trees back to the main working tree.
For instance, if the main worktree (or bare repository) is moved, linked
worktrees will be unable to locate it. Running `repair` in the main
worktree will reestablish the connection from linked worktrees back to the
main worktree.
+
Similarly, if a linked working tree is moved without using `git worktree
move`, the main working tree (or bare repository) will be unable to
locate it. Running `repair` within the recently-moved working tree will
reestablish the connection. If multiple linked working trees are moved,
running `repair` from any working tree with each tree's new `<path>` as
an argument, will reestablish the connection to all the specified paths.
Similarly, if the working tree for a linked worktree is moved without
using `git worktree move`, the main worktree (or bare repository) will be
unable to locate it. Running `repair` within the recently-moved worktree
will reestablish the connection. If multiple linked worktrees are moved,
running `repair` from any worktree with each tree's new `<path>` as an
argument, will reestablish the connection to all the specified paths.
+
If both the main working tree and linked working trees have been moved
manually, then running `repair` in the main working tree and specifying the
new `<path>` of each linked working tree will reestablish all connections
in both directions.
If both the main worktree and linked worktrees have been moved manually,
then running `repair` in the main worktree and specifying the new `<path>`
of each linked worktree will reestablish all connections in both
directions.
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
-------