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