1git-worktree(1) 2=============== 3 4NAME 5---- 6git-worktree - Manage multiple working trees 7 8 9SYNOPSIS 10-------- 11[verse] 12'git worktree add' [-f] [--detach] [--checkout] [--lock] [-b <new-branch>] <path> [<commit-ish>] 13'git worktree list' [--porcelain] 14'git worktree lock' [--reason <string>] <worktree> 15'git worktree move' <worktree> <new-path> 16'git worktree prune' [-n] [-v] [--expire <expire>] 17'git worktree remove' [-f] <worktree> 18'git worktree unlock' <worktree> 19 20DESCRIPTION 21----------- 22 23Manage multiple working trees attached to the same repository. 24 25A git repository can support multiple working trees, allowing you to check 26out more than one branch at a time. With `git worktree add` a new working 27tree is associated with the repository. This new working tree is called a 28"linked working tree" as opposed to the "main working tree" prepared by "git 29init" or "git clone". A repository has one main working tree (if it's not a 30bare repository) and zero or more linked working trees. When you are done 31with a linked working tree, remove it with `git worktree remove`. 32 33If a working tree is deleted without using `git worktree remove`, then 34its associated administrative files, which reside in the repository 35(see "DETAILS" below), will eventually be removed automatically (see 36`gc.worktreePruneExpire` in linkgit:git-config[1]), or you can run 37`git worktree prune` in the main or any linked working tree to 38clean up any stale administrative files. 39 40If a linked working tree is stored on a portable device or network share 41which is not always mounted, you can prevent its administrative files from 42being pruned by issuing the `git worktree lock` command, optionally 43specifying `--reason` to explain why the working tree is locked. 44 45COMMANDS 46-------- 47add <path> [<commit-ish>]:: 48 49Create `<path>` and checkout `<commit-ish>` into it. The new working directory 50is linked to the current repository, sharing everything except working 51directory specific files such as HEAD, index, etc. `-` may also be 52specified as `<commit-ish>`; it is synonymous with `@{-1}`. 53+ 54If <commit-ish> is a branch name (call it `<branch>`) and is not found, 55and neither `-b` nor `-B` nor `--detach` are used, but there does 56exist a tracking branch in exactly one remote (call it `<remote>`) 57with a matching name, treat as equivalent to: 58+ 59------------ 60$ git worktree add --track -b <branch> <path> <remote>/<branch> 61------------ 62+ 63If the branch exists in multiple remotes and one of them is named by 64the `checkout.defaultRemote` configuration variable, we'll use that 65one for the purposes of disambiguation, even if the `<branch>` isn't 66unique across all remotes. Set it to 67e.g. `checkout.defaultRemote=origin` to always checkout remote 68branches from there if `<branch>` is ambiguous but exists on the 69'origin' remote. See also `checkout.defaultRemote` in 70linkgit:git-config[1]. 71+ 72If `<commit-ish>` is omitted and neither `-b` nor `-B` nor `--detach` used, 73then, as a convenience, the new worktree is associated with a branch 74(call it `<branch>`) named after `$(basename <path>)`. If `<branch>` 75doesn't exist, a new branch based on HEAD is automatically created as 76if `-b <branch>` was given. If `<branch>` does exist, it will be 77checked out in the new worktree, if it's not checked out anywhere 78else, otherwise the command will refuse to create the worktree (unless 79`--force` is used). 80 81list:: 82 83List details of each worktree. The main worktree is listed first, followed by 84each of the linked worktrees. The output details include if the worktree is 85bare, the revision currently checked out, and the branch currently checked out 86(or 'detached HEAD' if none). 87 88lock:: 89 90If a working tree is on a portable device or network share which 91is not always mounted, lock it to prevent its administrative 92files from being pruned automatically. This also prevents it from 93being moved or deleted. Optionally, specify a reason for the lock 94with `--reason`. 95 96move:: 97 98Move a working tree to a new location. Note that the main working tree 99or linked working trees containing submodules cannot be moved. 100 101prune:: 102 103Prune working tree information in $GIT_DIR/worktrees. 104 105remove:: 106 107Remove a working tree. Only clean working trees (no untracked files 108and no modification in tracked files) can be removed. Unclean working 109trees or ones with submodules can be removed with `--force`. The main 110working tree cannot be removed. 111 112unlock:: 113 114Unlock a working tree, allowing it to be pruned, moved or deleted. 115 116OPTIONS 117------- 118 119-f:: 120--force:: 121 By default, `add` refuses to create a new working tree when 122 `<commit-ish>` is a branch name and is already checked out by 123 another working tree, or if `<path>` is already assigned to some 124 working tree but is missing (for instance, if `<path>` was deleted 125 manually). This option overrides these safeguards. To add a missing but 126 locked working tree path, specify `--force` twice. 127+ 128`remove` refuses to remove an unclean working tree unless `--force` is used. 129 130-b <new-branch>:: 131-B <new-branch>:: 132 With `add`, create a new branch named `<new-branch>` starting at 133 `<commit-ish>`, and check out `<new-branch>` into the new working tree. 134 If `<commit-ish>` is omitted, it defaults to HEAD. 135 By default, `-b` refuses to create a new branch if it already 136 exists. `-B` overrides this safeguard, resetting `<new-branch>` to 137 `<commit-ish>`. 138 139--detach:: 140 With `add`, detach HEAD in the new working tree. See "DETACHED HEAD" 141 in linkgit:git-checkout[1]. 142 143--[no-]checkout:: 144 By default, `add` checks out `<commit-ish>`, however, `--no-checkout` can 145 be used to suppress checkout in order to make customizations, 146 such as configuring sparse-checkout. See "Sparse checkout" 147 in linkgit:git-read-tree[1]. 148 149--[no-]guess-remote:: 150 With `worktree add <path>`, without `<commit-ish>`, instead 151 of creating a new branch from HEAD, if there exists a tracking 152 branch in exactly one remote matching the basename of `<path>`, 153 base the new branch on the remote-tracking branch, and mark 154 the remote-tracking branch as "upstream" from the new branch. 155+ 156This can also be set up as the default behaviour by using the 157`worktree.guessRemote` config option. 158 159--[no-]track:: 160 When creating a new branch, if `<commit-ish>` is a branch, 161 mark it as "upstream" from the new branch. This is the 162 default if `<commit-ish>` is a remote-tracking branch. See 163 "--track" in linkgit:git-branch[1] for details. 164 165--lock:: 166 Keep the working tree locked after creation. This is the 167 equivalent of `git worktree lock` after `git worktree add`, 168 but without race condition. 169 170-n:: 171--dry-run:: 172 With `prune`, do not remove anything; just report what it would 173 remove. 174 175--porcelain:: 176 With `list`, output in an easy-to-parse format for scripts. 177 This format will remain stable across Git versions and regardless of user 178 configuration. See below for details. 179 180-q:: 181--quiet:: 182 With 'add', suppress feedback messages. 183 184-v:: 185--verbose:: 186 With `prune`, report all removals. 187 188--expire <time>:: 189 With `prune`, only expire unused working trees older than <time>. 190 191--reason <string>:: 192 With `lock`, an explanation why the working tree is locked. 193 194<worktree>:: 195 Working trees can be identified by path, either relative or 196 absolute. 197+ 198If the last path components in the working tree's path is unique among 199working trees, it can be used to identify worktrees. For example if 200you only have two working trees, at "/abc/def/ghi" and "/abc/def/ggg", 201then "ghi" or "def/ghi" is enough to point to the former working tree. 202 203DETAILS 204------- 205Each linked working tree has a private sub-directory in the repository's 206$GIT_DIR/worktrees directory. The private sub-directory's name is usually 207the base name of the linked working tree's path, possibly appended with a 208number to make it unique. For example, when `$GIT_DIR=/path/main/.git` the 209command `git worktree add /path/other/test-next next` creates the linked 210working tree in `/path/other/test-next` and also creates a 211`$GIT_DIR/worktrees/test-next` directory (or `$GIT_DIR/worktrees/test-next1` 212if `test-next` is already taken). 213 214Within a linked working tree, $GIT_DIR is set to point to this private 215directory (e.g. `/path/main/.git/worktrees/test-next` in the example) and 216$GIT_COMMON_DIR is set to point back to the main working tree's $GIT_DIR 217(e.g. `/path/main/.git`). These settings are made in a `.git` file located at 218the top directory of the linked working tree. 219 220Path resolution via `git rev-parse --git-path` uses either 221$GIT_DIR or $GIT_COMMON_DIR depending on the path. For example, in the 222linked working tree `git rev-parse --git-path HEAD` returns 223`/path/main/.git/worktrees/test-next/HEAD` (not 224`/path/other/test-next/.git/HEAD` or `/path/main/.git/HEAD`) while `git 225rev-parse --git-path refs/heads/master` uses 226$GIT_COMMON_DIR and returns `/path/main/.git/refs/heads/master`, 227since refs are shared across all working trees. 228 229See linkgit:gitrepository-layout[5] for more information. The rule of 230thumb is do not make any assumption about whether a path belongs to 231$GIT_DIR or $GIT_COMMON_DIR when you need to directly access something 232inside $GIT_DIR. Use `git rev-parse --git-path` to get the final path. 233 234If you manually move a linked working tree, you need to update the 'gitdir' file 235in the entry's directory. For example, if a linked working tree is moved 236to `/newpath/test-next` and its `.git` file points to 237`/path/main/.git/worktrees/test-next`, then update 238`/path/main/.git/worktrees/test-next/gitdir` to reference `/newpath/test-next` 239instead. 240 241To prevent a $GIT_DIR/worktrees entry from being pruned (which 242can be useful in some situations, such as when the 243entry's working tree is stored on a portable device), use the 244`git worktree lock` command, which adds a file named 245'locked' to the entry's directory. The file contains the reason in 246plain text. For example, if a linked working tree's `.git` file points 247to `/path/main/.git/worktrees/test-next` then a file named 248`/path/main/.git/worktrees/test-next/locked` will prevent the 249`test-next` entry from being pruned. See 250linkgit:gitrepository-layout[5] for details. 251 252LIST OUTPUT FORMAT 253------------------ 254The worktree list command has two output formats. The default format shows the 255details on a single line with columns. For example: 256 257------------ 258$ git worktree list 259/path/to/bare-source (bare) 260/path/to/linked-worktree abcd1234 [master] 261/path/to/other-linked-worktree 1234abc (detached HEAD) 262------------ 263 264Porcelain Format 265~~~~~~~~~~~~~~~~ 266The porcelain format has a line per attribute. Attributes are listed with a 267label and value separated by a single space. Boolean attributes (like 'bare' 268and 'detached') are listed as a label only, and are only present if and only 269if the value is true. An empty line indicates the end of a worktree. For 270example: 271 272------------ 273$ git worktree list --porcelain 274worktree /path/to/bare-source 275bare 276 277worktree /path/to/linked-worktree 278HEAD abcd1234abcd1234abcd1234abcd1234abcd1234 279branch refs/heads/master 280 281worktree /path/to/other-linked-worktree 282HEAD 1234abc1234abc1234abc1234abc1234abc1234a 283detached 284 285------------ 286 287EXAMPLES 288-------- 289You are in the middle of a refactoring session and your boss comes in and 290demands that you fix something immediately. You might typically use 291linkgit:git-stash[1] to store your changes away temporarily, however, your 292working tree is in such a state of disarray (with new, moved, and removed 293files, and other bits and pieces strewn around) that you don't want to risk 294disturbing any of it. Instead, you create a temporary linked working tree to 295make the emergency fix, remove it when done, and then resume your earlier 296refactoring session. 297 298------------ 299$ git worktree add -b emergency-fix ../temp master 300$ pushd ../temp 301# ... hack hack hack ... 302$ git commit -a -m 'emergency fix for boss' 303$ popd 304$ git worktree remove ../temp 305------------ 306 307BUGS 308---- 309Multiple checkout in general is still experimental, and the support 310for submodules is incomplete. It is NOT recommended to make multiple 311checkouts of a superproject. 312 313GIT 314--- 315Part of the linkgit:git[1] suite