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] [-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
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. 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 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 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
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 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 $ git worktree add --track -b <branch> <path> <remote>/<branch>
57 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 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 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 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 prune
86 Prune working tree information in $GIT_DIR/worktrees.
87 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 unlock
95 Unlock a working tree, allowing it to be pruned, moved or deleted.
96
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 -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 --detach
112 With add, detach HEAD in the new working tree. See "DETACHED HEAD"
113 in git-checkout(1).
114 --[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 --[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 This can also be set up as the default behaviour by using the
129 worktree.guessRemote config option.
130 --[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 --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 -n, --dry-run
143 With prune, do not remove anything; just report what it would
144 remove.
145 --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 -v, --verbose
152 With prune, report all removals.
153 --expire <time>
155 With prune, only expire unused working trees older than <time>.
156 --reason <string>
158 With lock, an explanation why the working tree is locked.
159 <worktree>
161 Working trees can be identified by path, either relative or
162 absolute.
163 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
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 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 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 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 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 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
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 $ 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 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 $ git worktree list --porcelain
235 worktree /path/to/bare-source
236 bare
237 worktree /path/to/linked-worktree
239 HEAD abcd1234abcd1234abcd1234abcd1234abcd1234
240 branch refs/heads/master
241 worktree /path/to/other-linked-worktree
243 HEAD 1234abc1234abc1234abc1234abc1234abc1234a
244 detached
245
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 $ 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
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
271 Part of the git(1) suite
272Git 2.18.1 05/14/2019 GIT-WORKTREE(1)