1GIT-WORKTREE(1) Git Manual GIT-WORKTREE(1)
2
6 git-worktree - Manage multiple working trees
7
9 git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]]
10 [--orphan] [(-b | -B) <new-branch>] <path> [<commit-ish>]
11 git worktree list [-v | --porcelain [-z]]
12 git worktree lock [--reason <string>] <worktree>
13 git worktree move <worktree> <new-path>
14 git worktree prune [-n] [-v] [--expire <expire>]
15 git worktree remove [-f] <worktree>
16 git worktree repair [<path>...]
17 git worktree unlock <worktree>
18
20 Manage multiple working trees attached to the same repository.
21 A git repository can support multiple working trees, allowing you to
23 check out more than one branch at a time. With git worktree add a new
24 working tree is associated with the repository, along with additional
25 metadata that differentiates that working tree from others in the same
26 repository. The working tree, along with this metadata, is called a
27 "worktree".
28 This new worktree is called a "linked worktree" as opposed to the "main
30 worktree" prepared by git-init(1) or git-clone(1). A repository has one
31 main worktree (if it’s not a bare repository) and zero or more linked
32 worktrees. When you are done with a linked worktree, remove it with git
33 worktree remove.
34 In its simplest form, git worktree add <path> automatically creates a
36 new branch whose name is the final component of <path>, which is
37 convenient if you plan to work on a new topic. For instance, git
38 worktree add ../hotfix creates new branch hotfix and checks it out at
39 path ../hotfix. To instead work on an existing branch in a new
40 worktree, use git worktree add <path> <branch>. On the other hand, if
41 you just plan to make some experimental changes or do testing without
42 disturbing existing development, it is often convenient to create a
43 throwaway worktree not associated with any branch. For instance, git
44 worktree add -d <path> creates a new worktree with a detached HEAD at
45 the same commit as the current branch.
46 If a working tree is deleted without using git worktree remove, then
48 its associated administrative files, which reside in the repository
49 (see "DETAILS" below), will eventually be removed automatically (see
50 gc.worktreePruneExpire in git-config(1)), or you can run git worktree
51 prune in the main or any linked worktree to clean up any stale
52 administrative files.
53 If the working tree for a linked worktree is stored on a portable
55 device or network share which is not always mounted, you can prevent
56 its administrative files from being pruned by issuing the git worktree
57 lock command, optionally specifying --reason to explain why the
58 worktree is locked.
59
61 add <path> [<commit-ish>]
62 Create a worktree at <path> and checkout <commit-ish> into it. The
63 new worktree is linked to the current repository, sharing
64 everything except per-worktree files such as HEAD, index, etc. As a
65 convenience, <commit-ish> may be a bare "-", which is synonymous
66 with @{-1}.
67 If <commit-ish> is a branch name (call it <branch>) and is not
69 found, and neither -b nor -B nor --detach are used, but there does
70 exist a tracking branch in exactly one remote (call it <remote>)
71 with a matching name, treat as equivalent to:
72 $ git worktree add --track -b <branch> <path> <remote>/<branch>
74 If the branch exists in multiple remotes and one of them is named
76 by the checkout.defaultRemote configuration variable, we’ll use
77 that one for the purposes of disambiguation, even if the <branch>
78 isn’t unique across all remotes. Set it to e.g.
79 checkout.defaultRemote=origin to always checkout remote branches
80 from there if <branch> is ambiguous but exists on the origin
81 remote. See also checkout.defaultRemote in git-config(1).
82 If <commit-ish> is omitted and neither -b nor -B nor --detach used,
84 then, as a convenience, the new worktree is associated with a
85 branch (call it <branch>) named after $(basename <path>). If
86 <branch> doesn’t exist, a new branch based on HEAD is automatically
87 created as if -b <branch> was given. If <branch> does exist, it
88 will be checked out in the new worktree, if it’s not checked out
89 anywhere else, otherwise the command will refuse to create the
90 worktree (unless --force is used).
91 If <commit-ish> is omitted, neither --detach, or --orphan is used,
93 and there are no valid local branches (or remote branches if
94 --guess-remote is specified) then, as a convenience, the new
95 worktree is associated with a new orphan branch named <branch>
96 (after $(basename <path>) if neither -b or -B is used) as if
97 --orphan was passed to the command. In the event the repository has
98 a remote and --guess-remote is used, but no remote or local
99 branches exist, then the command fails with a warning reminding the
100 user to fetch from their remote first (or override by using
101 -f/--force).
102 list
104 List details of each worktree. The main worktree is listed first,
105 followed by each of the linked worktrees. The output details
106 include whether the worktree is bare, the revision currently
107 checked out, the branch currently checked out (or "detached HEAD"
108 if none), "locked" if the worktree is locked, "prunable" if the
109 worktree can be pruned by the prune command.
110 lock
112 If a worktree is on a portable device or network share which is not
113 always mounted, lock it to prevent its administrative files from
114 being pruned automatically. This also prevents it from being moved
115 or deleted. Optionally, specify a reason for the lock with
116 --reason.
117 move
119 Move a worktree to a new location. Note that the main worktree or
120 linked worktrees containing submodules cannot be moved with this
121 command. (The git worktree repair command, however, can reestablish
122 the connection with linked worktrees if you move the main worktree
123 manually.)
124 prune
126 Prune worktree information in $GIT_DIR/worktrees.
127 remove
129 Remove a worktree. Only clean worktrees (no untracked files and no
130 modification in tracked files) can be removed. Unclean worktrees or
131 ones with submodules can be removed with --force. The main worktree
132 cannot be removed.
133 repair [<path>...]
135 Repair worktree administrative files, if possible, if they have
136 become corrupted or outdated due to external factors.
137 For instance, if the main worktree (or bare repository) is moved,
139 linked worktrees will be unable to locate it. Running repair in the
140 main worktree will reestablish the connection from linked worktrees
141 back to the main worktree.
142 Similarly, if the working tree for a linked worktree is moved
144 without using git worktree move, the main worktree (or bare
145 repository) will be unable to locate it. Running repair within the
146 recently-moved worktree will reestablish the connection. If
147 multiple linked worktrees are moved, running repair from any
148 worktree with each tree’s new <path> as an argument, will
149 reestablish the connection to all the specified paths.
150 If both the main worktree and linked worktrees have been moved
152 manually, then running repair in the main worktree and specifying
153 the new <path> of each linked worktree will reestablish all
154 connections in both directions.
155 unlock
157 Unlock a worktree, allowing it to be pruned, moved or deleted.
158
160 -f, --force
161 By default, add refuses to create a new worktree when <commit-ish>
162 is a branch name and is already checked out by another worktree, or
163 if <path> is already assigned to some worktree but is missing (for
164 instance, if <path> was deleted manually). This option overrides
165 these safeguards. To add a missing but locked worktree path,
166 specify --force twice.
167 move refuses to move a locked worktree unless --force is specified
169 twice. If the destination is already assigned to some other
170 worktree but is missing (for instance, if <new-path> was deleted
171 manually), then --force allows the move to proceed; use --force
172 twice if the destination is locked.
173 remove refuses to remove an unclean worktree unless --force is
175 used. To remove a locked worktree, specify --force twice.
176 -b <new-branch>, -B <new-branch>
178 With add, create a new branch named <new-branch> starting at
179 <commit-ish>, and check out <new-branch> into the new worktree. If
180 <commit-ish> is omitted, it defaults to HEAD. By default, -b
181 refuses to create a new branch if it already exists. -B overrides
182 this safeguard, resetting <new-branch> to <commit-ish>.
183 -d, --detach
185 With add, detach HEAD in the new worktree. See "DETACHED HEAD" in
186 git-checkout(1).
187 --[no-]checkout
189 By default, add checks out <commit-ish>, however, --no-checkout can
190 be used to suppress checkout in order to make customizations, such
191 as configuring sparse-checkout. See "Sparse checkout" in git-read-
192 tree(1).
193 --[no-]guess-remote
195 With worktree add <path>, without <commit-ish>, instead of creating
196 a new branch from HEAD, if there exists a tracking branch in
197 exactly one remote matching the basename of <path>, base the new
198 branch on the remote-tracking branch, and mark the remote-tracking
199 branch as "upstream" from the new branch.
200 This can also be set up as the default behaviour by using the
202 worktree.guessRemote config option.
203 --[no-]track
205 When creating a new branch, if <commit-ish> is a branch, mark it as
206 "upstream" from the new branch. This is the default if <commit-ish>
207 is a remote-tracking branch. See --track in git-branch(1) for
208 details.
209 --lock
211 Keep the worktree locked after creation. This is the equivalent of
212 git worktree lock after git worktree add, but without a race
213 condition.
214 -n, --dry-run
216 With prune, do not remove anything; just report what it would
217 remove.
218 --orphan
220 With add, make the new worktree and index empty, associating the
221 worktree with a new orphan/unborn branch named <new-branch>.
222 --porcelain
224 With list, output in an easy-to-parse format for scripts. This
225 format will remain stable across Git versions and regardless of
226 user configuration. It is recommended to combine this with -z. See
227 below for details.
228 -z
230 Terminate each line with a NUL rather than a newline when
231 --porcelain is specified with list. This makes it possible to parse
232 the output when a worktree path contains a newline character.
233 -q, --quiet
235 With add, suppress feedback messages.
236 -v, --verbose
238 With prune, report all removals.
239 With list, output additional information about worktrees (see
241 below).
242 --expire <time>
244 With prune, only expire unused worktrees older than <time>.
245 With list, annotate missing worktrees as prunable if they are older
247 than <time>.
248 --reason <string>
250 With lock or with add --lock, an explanation why the worktree is
251 locked.
252 <worktree>
254 Worktrees can be identified by path, either relative or absolute.
255 If the last path components in the worktree’s path is unique among
257 worktrees, it can be used to identify a worktree. For example if
258 you only have two worktrees, at /abc/def/ghi and /abc/def/ggg, then
259 ghi or def/ghi is enough to point to the former worktree.
260
262 When using multiple worktrees, some refs are shared between all
263 worktrees, but others are specific to an individual worktree. One
264 example is HEAD, which is different for each worktree. This section is
265 about the sharing rules and how to access refs of one worktree from
266 another.
267 In general, all pseudo refs are per-worktree and all refs starting with
269 refs/ are shared. Pseudo refs are ones like HEAD which are directly
270 under $GIT_DIR instead of inside $GIT_DIR/refs. There are exceptions,
271 however: refs inside refs/bisect, refs/worktree and refs/rewritten are
272 not shared.
273 Refs that are per-worktree can still be accessed from another worktree
275 via two special paths, main-worktree and worktrees. The former gives
276 access to per-worktree refs of the main worktree, while the latter to
277 all linked worktrees.
278 For example, main-worktree/HEAD or main-worktree/refs/bisect/good
280 resolve to the same value as the main worktree’s HEAD and
281 refs/bisect/good respectively. Similarly, worktrees/foo/HEAD or
282 worktrees/bar/refs/bisect/bad are the same as
283 $GIT_COMMON_DIR/worktrees/foo/HEAD and
284 $GIT_COMMON_DIR/worktrees/bar/refs/bisect/bad.
285 To access refs, it’s best not to look inside $GIT_DIR directly. Instead
287 use commands such as git-rev-parse(1) or git-update-ref(1) which will
288 handle refs correctly.
289
291 By default, the repository config file is shared across all worktrees.
292 If the config variables core.bare or core.worktree are present in the
293 common config file and extensions.worktreeConfig is disabled, then they
294 will be applied to the main worktree only.
295 In order to have worktree-specific configuration, you can turn on the
297 worktreeConfig extension, e.g.:
298 $ git config extensions.worktreeConfig true
300 In this mode, specific configuration stays in the path pointed by git
302 rev-parse --git-path config.worktree. You can add or update
303 configuration in this file with git config --worktree. Older Git
304 versions will refuse to access repositories with this extension.
305 Note that in this file, the exception for core.bare and core.worktree
307 is gone. If they exist in $GIT_DIR/config, you must move them to the
308 config.worktree of the main worktree. You may also take this
309 opportunity to review and move other configuration that you do not want
310 to share to all worktrees:
311 • core.worktree should never be shared.
313 • core.bare should not be shared if the value is core.bare=true.
315 • core.sparseCheckout should not be shared, unless you are sure you
317 always use sparse checkout for all worktrees.
318 See the documentation of extensions.worktreeConfig in git-config(1) for
320 more details.
321
323 Each linked worktree has a private sub-directory in the repository’s
324 $GIT_DIR/worktrees directory. The private sub-directory’s name is
325 usually the base name of the linked worktree’s path, possibly appended
326 with a number to make it unique. For example, when
327 $GIT_DIR=/path/main/.git the command git worktree add
328 /path/other/test-next next creates the linked worktree in
329 /path/other/test-next and also creates a $GIT_DIR/worktrees/test-next
330 directory (or $GIT_DIR/worktrees/test-next1 if test-next is already
331 taken).
332 Within a linked worktree, $GIT_DIR is set to point to this private
334 directory (e.g. /path/main/.git/worktrees/test-next in the example) and
335 $GIT_COMMON_DIR is set to point back to the main worktree’s $GIT_DIR
336 (e.g. /path/main/.git). These settings are made in a .git file located
337 at the top directory of the linked worktree.
338 Path resolution via git rev-parse --git-path uses either $GIT_DIR or
340 $GIT_COMMON_DIR depending on the path. For example, in the linked
341 worktree git rev-parse --git-path HEAD returns
342 /path/main/.git/worktrees/test-next/HEAD (not
343 /path/other/test-next/.git/HEAD or /path/main/.git/HEAD) while git
344 rev-parse --git-path refs/heads/master uses $GIT_COMMON_DIR and returns
345 /path/main/.git/refs/heads/master, since refs are shared across all
346 worktrees, except refs/bisect, refs/worktree and refs/rewritten.
347 See gitrepository-layout(5) for more information. The rule of thumb is
349 do not make any assumption about whether a path belongs to $GIT_DIR or
350 $GIT_COMMON_DIR when you need to directly access something inside
351 $GIT_DIR. Use git rev-parse --git-path to get the final path.
352 If you manually move a linked worktree, you need to update the gitdir
354 file in the entry’s directory. For example, if a linked worktree is
355 moved to /newpath/test-next and its .git file points to
356 /path/main/.git/worktrees/test-next, then update
357 /path/main/.git/worktrees/test-next/gitdir to reference
358 /newpath/test-next instead. Better yet, run git worktree repair to
359 reestablish the connection automatically.
360 To prevent a $GIT_DIR/worktrees entry from being pruned (which can be
362 useful in some situations, such as when the entry’s worktree is stored
363 on a portable device), use the git worktree lock command, which adds a
364 file named locked to the entry’s directory. The file contains the
365 reason in plain text. For example, if a linked worktree’s .git file
366 points to /path/main/.git/worktrees/test-next then a file named
367 /path/main/.git/worktrees/test-next/locked will prevent the test-next
368 entry from being pruned. See gitrepository-layout(5) for details.
369 When extensions.worktreeConfig is enabled, the config file
371 .git/worktrees/<id>/config.worktree is read after .git/config is.
372
374 The worktree list command has two output formats. The default format
375 shows the details on a single line with columns. For example:
376 $ git worktree list
378 /path/to/bare-source (bare)
379 /path/to/linked-worktree abcd1234 [master]
380 /path/to/other-linked-worktree 1234abc (detached HEAD)
381 The command also shows annotations for each worktree, according to its
383 state. These annotations are:
384 • locked, if the worktree is locked.
386 • prunable, if the worktree can be pruned via git worktree prune.
388 $ git worktree list
390 /path/to/linked-worktree abcd1234 [master]
391 /path/to/locked-worktree acbd5678 (brancha) locked
392 /path/to/prunable-worktree 5678abc (detached HEAD) prunable
393 For these annotations, a reason might also be available and this can be
395 seen using the verbose mode. The annotation is then moved to the next
396 line indented followed by the additional information.
397 $ git worktree list --verbose
399 /path/to/linked-worktree abcd1234 [master]
400 /path/to/locked-worktree-no-reason abcd5678 (detached HEAD) locked
401 /path/to/locked-worktree-with-reason 1234abcd (brancha)
402 locked: worktree path is mounted on a portable device
403 /path/to/prunable-worktree 5678abc1 (detached HEAD)
404 prunable: gitdir file points to non-existent location
405 Note that the annotation is moved to the next line if the additional
407 information is available, otherwise it stays on the same line as the
408 worktree itself.
409 Porcelain Format
411 The porcelain format has a line per attribute. If -z is given then the
412 lines are terminated with NUL rather than a newline. Attributes are
413 listed with a label and value separated by a single space. Boolean
414 attributes (like bare and detached) are listed as a label only, and are
415 present only if the value is true. Some attributes (like locked) can be
416 listed as a label only or with a value depending upon whether a reason
417 is available. The first attribute of a worktree is always worktree, an
418 empty line indicates the end of the record. For example:
419 $ git worktree list --porcelain
421 worktree /path/to/bare-source
422 bare
423 worktree /path/to/linked-worktree
425 HEAD abcd1234abcd1234abcd1234abcd1234abcd1234
426 branch refs/heads/master
427 worktree /path/to/other-linked-worktree
429 HEAD 1234abc1234abc1234abc1234abc1234abc1234a
430 detached
431 worktree /path/to/linked-worktree-locked-no-reason
433 HEAD 5678abc5678abc5678abc5678abc5678abc5678c
434 branch refs/heads/locked-no-reason
435 locked
436 worktree /path/to/linked-worktree-locked-with-reason
438 HEAD 3456def3456def3456def3456def3456def3456b
439 branch refs/heads/locked-with-reason
440 locked reason why is locked
441 worktree /path/to/linked-worktree-prunable
443 HEAD 1233def1234def1234def1234def1234def1234b
444 detached
445 prunable gitdir file points to non-existent location
446 Unless -z is used any "unusual" characters in the lock reason such as
448 newlines are escaped and the entire reason is quoted as explained for
449 the configuration variable core.quotePath (see git-config(1)). For
450 Example:
451 $ git worktree list --porcelain
453 ...
454 locked "reason\nwhy is locked"
455 ...
456
458 You are in the middle of a refactoring session and your boss comes in
459 and demands that you fix something immediately. You might typically use
460 git-stash(1) to store your changes away temporarily, however, your
461 working tree is in such a state of disarray (with new, moved, and
462 removed files, and other bits and pieces strewn around) that you don’t
463 want to risk disturbing any of it. Instead, you create a temporary
464 linked worktree to make the emergency fix, remove it when done, and
465 then resume your earlier refactoring session.
466 $ git worktree add -b emergency-fix ../temp master
468 $ pushd ../temp
469 # ... hack hack hack ...
470 $ git commit -a -m 'emergency fix for boss'
471 $ popd
472 $ git worktree remove ../temp
473
475 Multiple checkout in general is still experimental, and the support for
476 submodules is incomplete. It is NOT recommended to make multiple
477 checkouts of a superproject.
478
480 Part of the git(1) suite
481Git 2.43.0 11/20/2023 GIT-WORKTREE(1)