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.txt95
1 files changed, 71 insertions, 24 deletions
diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index 3387e2f037..5b9ad0429c 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -3,7 +3,7 @@ git-worktree(1)
NAME
----
-git-worktree - Manage multiple worktrees
+git-worktree - Manage multiple working trees
SYNOPSIS
@@ -11,11 +11,12 @@ SYNOPSIS
[verse]
'git worktree add' [-f] [--detach] [-b <new-branch>] <path> [<branch>]
'git worktree prune' [-n] [-v] [--expire <expire>]
+'git worktree list' [--porcelain]
DESCRIPTION
-----------
-Manage multiple worktrees attached to the same repository.
+Manage multiple working trees attached to the same repository.
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
@@ -27,19 +28,19 @@ bare repository) and zero or more linked working trees.
When you are done with a linked working tree you can simply delete it.
The working tree's administrative files in the repository (see
"DETAILS" below) will eventually be removed automatically (see
-`gc.pruneworktreesexpire` 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
clean up any stale administrative files.
-If you move a linked working directory to another file system, or
+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 directory
+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 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
-being pruned by creating a file named 'lock' alongside the other
+being pruned by creating a file named 'locked' alongside the other
administrative files, optionally containing a plain text reason that
pruning should be suppressed. See section "DETAILS" for more information.
@@ -51,47 +52,59 @@ 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.
+
-If `<branch>` is omitted and neither `-b` nor `-B` is used, then, as a
-convenience, a new branch based at HEAD is created automatically, as if
-`-b $(basename <path>)` was specified.
+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.
prune::
Prune working tree information in $GIT_DIR/worktrees.
+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).
+
OPTIONS
-------
-f::
--force::
- By default, `add` refuses to create a new worktree when `<branch>`
- is already checked out by another worktree. This option overrides
+ By default, `add` refuses to create a new working tree when `<branch>`
+ is already checked out by another working tree. This option overrides
that safeguard.
-b <new-branch>::
-B <new-branch>::
With `add`, create a new branch named `<new-branch>` starting at
- `<branch>`, and check out `<new-branch>` into the new worktree.
+ `<branch>`, and check out `<new-branch>` into the new working tree.
If `<branch>` is omitted, it defaults to HEAD.
By default, `-b` refuses to create a new branch if it already
exists. `-B` overrides this safeguard, resetting `<new-branch>` to
`<branch>`.
--detach::
- With `add`, detach HEAD in the new worktree. See "DETACHED HEAD" in
- linkgit:git-checkout[1].
+ With `add`, detach HEAD in the new working tree. See "DETACHED HEAD"
+ in linkgit:git-checkout[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.
--expire <time>::
- With `prune`, only expire unused worktrees older than <time>.
+ With `prune`, only expire unused working trees older than <time>.
DETAILS
-------
@@ -124,7 +137,7 @@ 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.
-To prevent a $GIT_DIR/worktrees entry from from being pruned (which
+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
'locked' to the entry's directory. The file contains the reason in
@@ -134,14 +147,49 @@ 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
demands that you fix something immediately. You might typically use
linkgit:git-stash[1] to store your changes away temporarily, however, your
-worktree is in such a state of disarray (with new, moved, and removed files,
-and other bits and pieces strewn around) that you don't want to risk
-disturbing any of it. Instead, you create a temporary linked worktree to
+working tree is in such a state of disarray (with new, moved, and removed
+files, and other bits and pieces strewn around) that you don't want to risk
+disturbing any of it. Instead, you create a temporary linked working tree to
make the emergency fix, remove it when done, and then resume your earlier
refactoring session.
@@ -164,12 +212,11 @@ checkouts of a superproject.
git-worktree could provide more automation for tasks currently
performed manually, such as:
-- `remove` to remove a linked worktree and its administrative files (and
- warn if the worktree is dirty)
-- `mv` to move or rename a worktree and update its administrative files
-- `list` to list linked worktrees
+- `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
- `lock` to prevent automatic pruning of administrative files (for instance,
- for a worktree on a portable device)
+ for a working tree on a portable device)
GIT
---