1GIT-WORKTREE(1)                   Git Manual                   GIT-WORKTREE(1)
2
3
4

NAME

6       git-worktree - Manage multiple working trees
7

SYNOPSIS

9       git worktree add [-f] [--detach] [--checkout] [--lock] [-b <new-branch>] <path> [<commit-ish>]
10       git worktree list [--porcelain]
11       git worktree lock [--reason <string>] <worktree>
12       git worktree move <worktree> <new-path>
13       git worktree prune [-n] [-v] [--expire <expire>]
14       git worktree remove [-f] <worktree>
15       git worktree unlock <worktree>
16
17

DESCRIPTION

19       Manage multiple working trees attached to the same repository.
20
21       A git repository can support multiple working trees, allowing you to
22       check out more than one branch at a time. With git worktree add a new
23       working tree is associated with the repository. This new working tree
24       is called a "linked working tree" as opposed to the "main working tree"
25       prepared by "git init" or "git clone". A repository has one main
26       working tree (if it’s not a bare repository) and zero or more linked
27       working trees. When you are done with a linked working tree, remove it
28       with git worktree remove.
29
30       If a working tree is deleted without using git worktree remove, then
31       its associated administrative files, which reside in the repository
32       (see "DETAILS" below), will eventually be removed automatically (see
33       gc.worktreePruneExpire in git-config(1)), or you can run git worktree
34       prune in the main or any linked working tree to clean up any stale
35       administrative files.
36
37       If a linked working tree is stored on a portable device or network
38       share which is not always mounted, you can prevent its administrative
39       files from being pruned by issuing the git worktree lock command,
40       optionally specifying --reason to explain why the working tree is
41       locked.
42

COMMANDS

44       add <path> [<commit-ish>]
45           Create <path> and checkout <commit-ish> into it. The new working
46           directory is linked to the current repository, sharing everything
47           except working directory specific files such as HEAD, index, etc.
48           - may also be specified as <commit-ish>; it is synonymous with
49           @{-1}.
50
51           If <commit-ish> is a branch name (call it <branch>) and is not
52           found, and neither -b nor -B nor --detach are used, but there does
53           exist a tracking branch in exactly one remote (call it <remote>)
54           with a matching name, treat as equivalent to:
55
56               $ git worktree add --track -b <branch> <path> <remote>/<branch>
57
58           If <commit-ish> is omitted and neither -b nor -B nor --detach used,
59           then, as a convenience, the new worktree is associated with a
60           branch (call it <branch>) named after $(basename <path>). If
61           <branch> doesn’t exist, a new branch based on HEAD is automatically
62           created as if -b <branch> was given. If <branch> does exist, it
63           will be checked out in the new worktree, if it’s not checked out
64           anywhere else, otherwise the command will refuse to create the
65           worktree (unless --force is used).
66
67       list
68           List details of each worktree. The main worktree is listed first,
69           followed by each of the linked worktrees. The output details
70           include if the worktree is bare, the revision currently checked
71           out, and the branch currently checked out (or detached HEAD if
72           none).
73
74       lock
75           If a working tree is on a portable device or network share which is
76           not always mounted, lock it to prevent its administrative files
77           from being pruned automatically. This also prevents it from being
78           moved or deleted. Optionally, specify a reason for the lock with
79           --reason.
80
81       move
82           Move a working tree to a new location. Note that the main working
83           tree or linked working trees containing submodules cannot be moved.
84
85       prune
86           Prune working tree information in $GIT_DIR/worktrees.
87
88       remove
89           Remove a working tree. Only clean working trees (no untracked files
90           and no modification in tracked files) can be removed. Unclean
91           working trees or ones with submodules can be removed with --force.
92           The main working tree cannot be removed.
93
94       unlock
95           Unlock a working tree, allowing it to be pruned, moved or deleted.
96

OPTIONS

98       -f, --force
99           By default, add refuses to create a new working tree when
100           <commit-ish> is a branch name and is already checked out by another
101           working tree and remove refuses to remove an unclean working tree.
102           This option overrides these safeguards.
103
104       -b <new-branch>, -B <new-branch>
105           With add, create a new branch named <new-branch> starting at
106           <commit-ish>, and check out <new-branch> into the new working tree.
107           If <commit-ish> is omitted, it defaults to HEAD. By default, -b
108           refuses to create a new branch if it already exists.  -B overrides
109           this safeguard, resetting <new-branch> to <commit-ish>.
110
111       --detach
112           With add, detach HEAD in the new working tree. See "DETACHED HEAD"
113           in git-checkout(1).
114
115       --[no-]checkout
116           By default, add checks out <commit-ish>, however, --no-checkout can
117           be used to suppress checkout in order to make customizations, such
118           as configuring sparse-checkout. See "Sparse checkout" in git-read-
119           tree(1).
120
121       --[no-]guess-remote
122           With worktree add <path>, without <commit-ish>, instead of creating
123           a new branch from HEAD, if there exists a tracking branch in
124           exactly one remote matching the basename of <path>, base the new
125           branch on the remote-tracking branch, and mark the remote-tracking
126           branch as "upstream" from the new branch.
127
128           This can also be set up as the default behaviour by using the
129           worktree.guessRemote config option.
130
131       --[no-]track
132           When creating a new branch, if <commit-ish> is a branch, mark it as
133           "upstream" from the new branch. This is the default if <commit-ish>
134           is a remote-tracking branch. See "--track" in git-branch(1) for
135           details.
136
137       --lock
138           Keep the working tree locked after creation. This is the equivalent
139           of git worktree lock after git worktree add, but without race
140           condition.
141
142       -n, --dry-run
143           With prune, do not remove anything; just report what it would
144           remove.
145
146       --porcelain
147           With list, output in an easy-to-parse format for scripts. This
148           format will remain stable across Git versions and regardless of
149           user configuration. See below for details.
150
151       -v, --verbose
152           With prune, report all removals.
153
154       --expire <time>
155           With prune, only expire unused working trees older than <time>.
156
157       --reason <string>
158           With lock, an explanation why the working tree is locked.
159
160       <worktree>
161           Working trees can be identified by path, either relative or
162           absolute.
163
164           If the last path components in the working tree’s path is unique
165           among working trees, it can be used to identify worktrees. For
166           example if you only have two working trees, at "/abc/def/ghi" and
167           "/abc/def/ggg", then "ghi" or "def/ghi" is enough to point to the
168           former working tree.
169

DETAILS

171       Each linked working tree has a private sub-directory in the
172       repository’s $GIT_DIR/worktrees directory. The private sub-directory’s
173       name is usually the base name of the linked working tree’s path,
174       possibly appended with a number to make it unique. For example, when
175       $GIT_DIR=/path/main/.git the command git worktree add
176       /path/other/test-next next creates the linked working tree in
177       /path/other/test-next and also creates a $GIT_DIR/worktrees/test-next
178       directory (or $GIT_DIR/worktrees/test-next1 if test-next is already
179       taken).
180
181       Within a linked working tree, $GIT_DIR is set to point to this private
182       directory (e.g. /path/main/.git/worktrees/test-next in the example) and
183       $GIT_COMMON_DIR is set to point back to the main working tree’s
184       $GIT_DIR (e.g. /path/main/.git). These settings are made in a .git file
185       located at the top directory of the linked working tree.
186
187       Path resolution via git rev-parse --git-path uses either $GIT_DIR or
188       $GIT_COMMON_DIR depending on the path. For example, in the linked
189       working tree git rev-parse --git-path HEAD returns
190       /path/main/.git/worktrees/test-next/HEAD (not
191       /path/other/test-next/.git/HEAD or /path/main/.git/HEAD) while git
192       rev-parse --git-path refs/heads/master uses $GIT_COMMON_DIR and returns
193       /path/main/.git/refs/heads/master, since refs are shared across all
194       working trees.
195
196       See gitrepository-layout(5) for more information. The rule of thumb is
197       do not make any assumption about whether a path belongs to $GIT_DIR or
198       $GIT_COMMON_DIR when you need to directly access something inside
199       $GIT_DIR. Use git rev-parse --git-path to get the final path.
200
201       If you manually move a linked working tree, you need to update the
202       gitdir file in the entry’s directory. For example, if a linked working
203       tree is moved to /newpath/test-next and its .git file points to
204       /path/main/.git/worktrees/test-next, then update
205       /path/main/.git/worktrees/test-next/gitdir to reference
206       /newpath/test-next instead.
207
208       To prevent a $GIT_DIR/worktrees entry from being pruned (which can be
209       useful in some situations, such as when the entry’s working tree is
210       stored on a portable device), use the git worktree lock command, which
211       adds a file named locked to the entry’s directory. The file contains
212       the reason in plain text. For example, if a linked working tree’s .git
213       file points to /path/main/.git/worktrees/test-next then a file named
214       /path/main/.git/worktrees/test-next/locked will prevent the test-next
215       entry from being pruned. See gitrepository-layout(5) for details.
216

LIST OUTPUT FORMAT

218       The worktree list command has two output formats. The default format
219       shows the details on a single line with columns. For example:
220
221           $ git worktree list
222           /path/to/bare-source            (bare)
223           /path/to/linked-worktree        abcd1234 [master]
224           /path/to/other-linked-worktree  1234abc  (detached HEAD)
225
226
227   Porcelain Format
228       The porcelain format has a line per attribute. Attributes are listed
229       with a label and value separated by a single space. Boolean attributes
230       (like bare and detached) are listed as a label only, and are only
231       present if and only if the value is true. An empty line indicates the
232       end of a worktree. For example:
233
234           $ git worktree list --porcelain
235           worktree /path/to/bare-source
236           bare
237
238           worktree /path/to/linked-worktree
239           HEAD abcd1234abcd1234abcd1234abcd1234abcd1234
240           branch refs/heads/master
241
242           worktree /path/to/other-linked-worktree
243           HEAD 1234abc1234abc1234abc1234abc1234abc1234a
244           detached
245
246

EXAMPLES

248       You are in the middle of a refactoring session and your boss comes in
249       and demands that you fix something immediately. You might typically use
250       git-stash(1) to store your changes away temporarily, however, your
251       working tree is in such a state of disarray (with new, moved, and
252       removed files, and other bits and pieces strewn around) that you don’t
253       want to risk disturbing any of it. Instead, you create a temporary
254       linked working tree to make the emergency fix, remove it when done, and
255       then resume your earlier refactoring session.
256
257           $ git worktree add -b emergency-fix ../temp master
258           $ pushd ../temp
259           # ... hack hack hack ...
260           $ git commit -a -m 'emergency fix for boss'
261           $ popd
262           $ git worktree remove ../temp
263
264

BUGS

266       Multiple checkout in general is still experimental, and the support for
267       submodules is incomplete. It is NOT recommended to make multiple
268       checkouts of a superproject.
269

GIT

271       Part of the git(1) suite
272
273
274
275Git 2.18.1                        05/14/2019                   GIT-WORKTREE(1)
Impressum