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 the branch exists in multiple remotes and one of them is named
59           by the checkout.defaultRemote configuration variable, we’ll use
60           that one for the purposes of disambiguation, even if the <branch>
61           isn’t unique across all remotes. Set it to e.g.
62           checkout.defaultRemote=origin to always checkout remote branches
63           from there if <branch> is ambiguous but exists on the origin
64           remote. See also checkout.defaultRemote in git-config(1).
65
66           If <commit-ish> is omitted and neither -b nor -B nor --detach used,
67           then, as a convenience, the new worktree is associated with a
68           branch (call it <branch>) named after $(basename <path>). If
69           <branch> doesn’t exist, a new branch based on HEAD is automatically
70           created as if -b <branch> was given. If <branch> does exist, it
71           will be checked out in the new worktree, if it’s not checked out
72           anywhere else, otherwise the command will refuse to create the
73           worktree (unless --force is used).
74
75       list
76           List details of each worktree. The main worktree is listed first,
77           followed by each of the linked worktrees. The output details
78           include if the worktree is bare, the revision currently checked
79           out, and the branch currently checked out (or detached HEAD if
80           none).
81
82       lock
83           If a working tree is on a portable device or network share which is
84           not always mounted, lock it to prevent its administrative files
85           from being pruned automatically. This also prevents it from being
86           moved or deleted. Optionally, specify a reason for the lock with
87           --reason.
88
89       move
90           Move a working tree to a new location. Note that the main working
91           tree or linked working trees containing submodules cannot be moved.
92
93       prune
94           Prune working tree information in $GIT_DIR/worktrees.
95
96       remove
97           Remove a working tree. Only clean working trees (no untracked files
98           and no modification in tracked files) can be removed. Unclean
99           working trees or ones with submodules can be removed with --force.
100           The main working tree cannot be removed.
101
102       unlock
103           Unlock a working tree, allowing it to be pruned, moved or deleted.
104

OPTIONS

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

REFS

190       In multiple working trees, some refs may be shared between all working
191       trees, some refs are local. One example is HEAD is different for all
192       working trees. This section is about the sharing rules and how to
193       access refs of one working tree from another.
194
195       In general, all pseudo refs are per working tree and all refs starting
196       with "refs/" are shared. Pseudo refs are ones like HEAD which are
197       directly under GIT_DIR instead of inside GIT_DIR/refs. There are one
198       exception to this: refs inside refs/bisect and refs/worktree is not
199       shared.
200
201       Refs that are per working tree can still be accessed from another
202       working tree via two special paths, main-worktree and worktrees. The
203       former gives access to per-worktree refs of the main working tree,
204       while the latter to all linked working trees.
205
206       For example, main-worktree/HEAD or main-worktree/refs/bisect/good
207       resolve to the same value as the main working tree’s HEAD and
208       refs/bisect/good respectively. Similarly, worktrees/foo/HEAD or
209       worktrees/bar/refs/bisect/bad are the same as
210       GIT_COMMON_DIR/worktrees/foo/HEAD and
211       GIT_COMMON_DIR/worktrees/bar/refs/bisect/bad.
212
213       To access refs, it’s best not to look inside GIT_DIR directly. Instead
214       use commands such as git-rev-parse(1) or git-update-ref(1) which will
215       handle refs correctly.
216

CONFIGURATION FILE

218       By default, the repository "config" file is shared across all working
219       trees. If the config variables core.bare or core.worktree are already
220       present in the config file, they will be applied to the main working
221       trees only.
222
223       In order to have configuration specific to working trees, you can turn
224       on "worktreeConfig" extension, e.g.:
225
226           $ git config extensions.worktreeConfig true
227
228
229       In this mode, specific configuration stays in the path pointed by git
230       rev-parse --git-path config.worktree. You can add or update
231       configuration in this file with git config --worktree. Older Git
232       versions will refuse to access repositories with this extension.
233
234       Note that in this file, the exception for core.bare and core.worktree
235       is gone. If you have them in $GIT_DIR/config before, you must move them
236       to the config.worktree of the main working tree. You may also take this
237       opportunity to review and move other configuration that you do not want
238       to share to all working trees:
239
240       ·   core.worktree and core.bare should never be shared
241
242       ·   core.sparseCheckout is recommended per working tree, unless you are
243           sure you always use sparse checkout for all working trees.
244

DETAILS

246       Each linked working tree has a private sub-directory in the
247       repository’s $GIT_DIR/worktrees directory. The private sub-directory’s
248       name is usually the base name of the linked working tree’s path,
249       possibly appended with a number to make it unique. For example, when
250       $GIT_DIR=/path/main/.git the command git worktree add
251       /path/other/test-next next creates the linked working tree in
252       /path/other/test-next and also creates a $GIT_DIR/worktrees/test-next
253       directory (or $GIT_DIR/worktrees/test-next1 if test-next is already
254       taken).
255
256       Within a linked working tree, $GIT_DIR is set to point to this private
257       directory (e.g. /path/main/.git/worktrees/test-next in the example) and
258       $GIT_COMMON_DIR is set to point back to the main working tree’s
259       $GIT_DIR (e.g. /path/main/.git). These settings are made in a .git file
260       located at the top directory of the linked working tree.
261
262       Path resolution via git rev-parse --git-path uses either $GIT_DIR or
263       $GIT_COMMON_DIR depending on the path. For example, in the linked
264       working tree git rev-parse --git-path HEAD returns
265       /path/main/.git/worktrees/test-next/HEAD (not
266       /path/other/test-next/.git/HEAD or /path/main/.git/HEAD) while git
267       rev-parse --git-path refs/heads/master uses $GIT_COMMON_DIR and returns
268       /path/main/.git/refs/heads/master, since refs are shared across all
269       working trees, except refs/bisect and refs/worktree.
270
271       See gitrepository-layout(5) for more information. The rule of thumb is
272       do not make any assumption about whether a path belongs to $GIT_DIR or
273       $GIT_COMMON_DIR when you need to directly access something inside
274       $GIT_DIR. Use git rev-parse --git-path to get the final path.
275
276       If you manually move a linked working tree, you need to update the
277       gitdir file in the entry’s directory. For example, if a linked working
278       tree is moved to /newpath/test-next and its .git file points to
279       /path/main/.git/worktrees/test-next, then update
280       /path/main/.git/worktrees/test-next/gitdir to reference
281       /newpath/test-next instead.
282
283       To prevent a $GIT_DIR/worktrees entry from being pruned (which can be
284       useful in some situations, such as when the entry’s working tree is
285       stored on a portable device), use the git worktree lock command, which
286       adds a file named locked to the entry’s directory. The file contains
287       the reason in plain text. For example, if a linked working tree’s .git
288       file points to /path/main/.git/worktrees/test-next then a file named
289       /path/main/.git/worktrees/test-next/locked will prevent the test-next
290       entry from being pruned. See gitrepository-layout(5) for details.
291
292       When extensions.worktreeConfig is enabled, the config file
293       .git/worktrees/<id>/config.worktree is read after .git/config is.
294

LIST OUTPUT FORMAT

296       The worktree list command has two output formats. The default format
297       shows the details on a single line with columns. For example:
298
299           $ git worktree list
300           /path/to/bare-source            (bare)
301           /path/to/linked-worktree        abcd1234 [master]
302           /path/to/other-linked-worktree  1234abc  (detached HEAD)
303
304
305   Porcelain Format
306       The porcelain format has a line per attribute. Attributes are listed
307       with a label and value separated by a single space. Boolean attributes
308       (like bare and detached) are listed as a label only, and are only
309       present if and only if the value is true. The first attribute of a
310       worktree is always worktree, an empty line indicates the end of the
311       record. For example:
312
313           $ git worktree list --porcelain
314           worktree /path/to/bare-source
315           bare
316
317           worktree /path/to/linked-worktree
318           HEAD abcd1234abcd1234abcd1234abcd1234abcd1234
319           branch refs/heads/master
320
321           worktree /path/to/other-linked-worktree
322           HEAD 1234abc1234abc1234abc1234abc1234abc1234a
323           detached
324
325

EXAMPLES

327       You are in the middle of a refactoring session and your boss comes in
328       and demands that you fix something immediately. You might typically use
329       git-stash(1) to store your changes away temporarily, however, your
330       working tree is in such a state of disarray (with new, moved, and
331       removed files, and other bits and pieces strewn around) that you don’t
332       want to risk disturbing any of it. Instead, you create a temporary
333       linked working tree to make the emergency fix, remove it when done, and
334       then resume your earlier refactoring session.
335
336           $ git worktree add -b emergency-fix ../temp master
337           $ pushd ../temp
338           # ... hack hack hack ...
339           $ git commit -a -m 'emergency fix for boss'
340           $ popd
341           $ git worktree remove ../temp
342
343

BUGS

345       Multiple checkout in general is still experimental, and the support for
346       submodules is incomplete. It is NOT recommended to make multiple
347       checkouts of a superproject.
348

GIT

350       Part of the git(1) suite
351
352
353
354Git 2.20.1                        12/15/2018                   GIT-WORKTREE(1)
Impressum