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:
parent
23f832e29e
commit
c57bf8ce9e
@ -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
|
||||||
|
Loading…
Reference in New Issue
Block a user