summaryrefslogtreecommitdiff
path: root/Documentation/git-worktree.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/git-worktree.txt')
-rw-r--r--Documentation/git-worktree.txt75
1 files changed, 67 insertions, 8 deletions
diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index fb68156cf8..7c4cfb0885 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -9,7 +9,8 @@ git-worktree - Manage multiple working trees
SYNOPSIS
--------
[verse]
-'git worktree add' [-f] [--detach] [-b <new-branch>] <path> [<branch>]
+'git worktree add' [-f] [--detach] [--checkout] [-b <new-branch>] <path> [<branch>]
+'git worktree list' [--porcelain]
'git worktree prune' [-n] [-v] [--expire <expire>]
DESCRIPTION
@@ -31,11 +32,9 @@ The working tree's administrative files in the repository (see
`git worktree prune` in the main or any linked working tree to
clean up any stale administrative files.
-If you move a linked working tree to another file system, or
-within a file system that does not support hard links, you need to run
-at least one git command inside the linked working tree
-(e.g. `git status`) in order to update its administrative files in the
-repository so that they do not get automatically pruned.
+If you move a linked working tree, you need to manually update the
+administrative files so that they do not get pruned automatically. See
+section "DETAILS" for more information.
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
@@ -49,12 +48,20 @@ add <path> [<branch>]::
Create `<path>` and checkout `<branch>` into it. The new working directory
is linked to the current repository, sharing everything except working
-directory specific files such as HEAD, index, etc.
+directory specific files such as HEAD, index, etc. `-` may also be
+specified as `<branch>`; it is synonymous with `@{-1}`.
+
If `<branch>` is omitted and neither `-b` nor `-B` nor `--detached` used,
then, as a convenience, a new branch based at HEAD is created automatically,
as if `-b $(basename <path>)` was specified.
+list::
+
+List details of each worktree. The main worktree is listed first, followed by
+each of the linked worktrees. The output details include if the worktree is
+bare, the revision currently checked out, and the branch currently checked out
+(or 'detached HEAD' if none).
+
prune::
Prune working tree information in $GIT_DIR/worktrees.
@@ -81,11 +88,22 @@ OPTIONS
With `add`, detach HEAD in the new working tree. See "DETACHED HEAD"
in linkgit:git-checkout[1].
+--[no-]checkout::
+ By default, `add` checks out `<branch>`, however, `--no-checkout` can
+ be used to suppress checkout in order to make customizations,
+ such as configuring sparse-checkout. See "Sparse checkout"
+ in linkgit:git-read-tree[1].
+
-n::
--dry-run::
With `prune`, do not remove anything; just report what it would
remove.
+--porcelain::
+ With `list`, output in an easy-to-parse format for scripts.
+ This format will remain stable across Git versions and regardless of user
+ configuration. See below for details.
+
-v::
--verbose::
With `prune`, report all removals.
@@ -124,6 +142,13 @@ thumb is do not make any assumption about whether a path belongs to
$GIT_DIR or $GIT_COMMON_DIR when you need to directly access something
inside $GIT_DIR. Use `git rev-parse --git-path` to get the final path.
+If you move a linked working tree, you need to update the 'gitdir' file
+in the entry's directory. For example, if a linked working tree is moved
+to `/newpath/test-next` and its `.git` file points to
+`/path/main/.git/worktrees/test-next`, then update
+`/path/main/.git/worktrees/test-next/gitdir` to reference `/newpath/test-next`
+instead.
+
To prevent a $GIT_DIR/worktrees entry from being pruned (which
can be useful in some situations, such as when the
entry's working tree is stored on a portable device), add a file named
@@ -134,6 +159,41 @@ to `/path/main/.git/worktrees/test-next` then a file named
`test-next` entry from being pruned. See
linkgit:gitrepository-layout[5] for details.
+LIST OUTPUT FORMAT
+------------------
+The worktree list command has two output formats. The default format shows the
+details on a single line with columns. For example:
+
+------------
+S git worktree list
+/path/to/bare-source (bare)
+/path/to/linked-worktree abcd1234 [master]
+/path/to/other-linked-worktree 1234abc (detached HEAD)
+------------
+
+Porcelain Format
+~~~~~~~~~~~~~~~~
+The porcelain format has a line per attribute. Attributes are listed with a
+label and value separated by a single space. Boolean attributes (like 'bare'
+and 'detached') are listed as a label only, and are only present if and only
+if the value is true. An empty line indicates the end of a worktree. For
+example:
+
+------------
+S git worktree list --porcelain
+worktree /path/to/bare-source
+bare
+
+worktree /path/to/linked-worktree
+HEAD abcd1234abcd1234abcd1234abcd1234abcd1234
+branch refs/heads/master
+
+worktree /path/to/other-linked-worktree
+HEAD 1234abc1234abc1234abc1234abc1234abc1234a
+detached
+
+------------
+
EXAMPLES
--------
You are in the middle of a refactoring session and your boss comes in and
@@ -167,7 +227,6 @@ performed manually, such as:
- `remove` to remove a linked working tree and its administrative files (and
warn if the working tree is dirty)
- `mv` to move or rename a working tree and update its administrative files
-- `list` to list linked working trees
- `lock` to prevent automatic pruning of administrative files (for instance,
for a working tree on a portable device)