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`move` refuses to move a locked working tree unless `--force` is specified 129twice. 130+ 131`remove` refuses to remove an unclean working tree unless `--force` is used. 132 133-b <new-branch>:: 134-B <new-branch>:: 135 With `add`, create a new branch named `<new-branch>` starting at 136 `<commit-ish>`, and check out `<new-branch>` into the new working tree. 137 If `<commit-ish>` is omitted, it defaults to HEAD. 138 By default, `-b` refuses to create a new branch if it already 139 exists. `-B` overrides this safeguard, resetting `<new-branch>` to 140 `<commit-ish>`. 141 142--detach:: 143 With `add`, detach HEAD in the new working tree. See "DETACHED HEAD" 144 in linkgit:git-checkout[1]. 145 146--[no-]checkout:: 147 By default, `add` checks out `<commit-ish>`, however, `--no-checkout` can 148 be used to suppress checkout in order to make customizations, 149 such as configuring sparse-checkout. See "Sparse checkout" 150 in linkgit:git-read-tree[1]. 151 152--[no-]guess-remote:: 153 With `worktree add <path>`, without `<commit-ish>`, instead 154 of creating a new branch from HEAD, if there exists a tracking 155 branch in exactly one remote matching the basename of `<path>`, 156 base the new branch on the remote-tracking branch, and mark 157 the remote-tracking branch as "upstream" from the new branch. 158+ 159This can also be set up as the default behaviour by using the 160`worktree.guessRemote` config option. 161 162--[no-]track:: 163 When creating a new branch, if `<commit-ish>` is a branch, 164 mark it as "upstream" from the new branch. This is the 165 default if `<commit-ish>` is a remote-tracking branch. See 166 "--track" in linkgit:git-branch[1] for details. 167 168--lock:: 169 Keep the working tree locked after creation. This is the 170 equivalent of `git worktree lock` after `git worktree add`, 171 but without race condition. 172 173-n:: 174--dry-run:: 175 With `prune`, do not remove anything; just report what it would 176 remove. 177 178--porcelain:: 179 With `list`, output in an easy-to-parse format for scripts. 180 This format will remain stable across Git versions and regardless of user 181 configuration. See below for details. 182 183-q:: 184--quiet:: 185 With 'add', suppress feedback messages. 186 187-v:: 188--verbose:: 189 With `prune`, report all removals. 190 191--expire <time>:: 192 With `prune`, only expire unused working trees older than <time>. 193 194--reason <string>:: 195 With `lock`, an explanation why the working tree is locked. 196 197<worktree>:: 198 Working trees can be identified by path, either relative or 199 absolute. 200+ 201If the last path components in the working tree's path is unique among 202working trees, it can be used to identify worktrees. For example if 203you only have two working trees, at "/abc/def/ghi" and "/abc/def/ggg", 204then "ghi" or "def/ghi" is enough to point to the former working tree. 205 206DETAILS 207------- 208Each linked working tree has a private sub-directory in the repository's 209$GIT_DIR/worktrees directory. The private sub-directory's name is usually 210the base name of the linked working tree's path, possibly appended with a 211number to make it unique. For example, when `$GIT_DIR=/path/main/.git` the 212command `git worktree add /path/other/test-next next` creates the linked 213working tree in `/path/other/test-next` and also creates a 214`$GIT_DIR/worktrees/test-next` directory (or `$GIT_DIR/worktrees/test-next1` 215if `test-next` is already taken). 216 217Within a linked working tree, $GIT_DIR is set to point to this private 218directory (e.g. `/path/main/.git/worktrees/test-next` in the example) and 219$GIT_COMMON_DIR is set to point back to the main working tree's $GIT_DIR 220(e.g. `/path/main/.git`). These settings are made in a `.git` file located at 221the top directory of the linked working tree. 222 223Path resolution via `git rev-parse --git-path` uses either 224$GIT_DIR or $GIT_COMMON_DIR depending on the path. For example, in the 225linked working tree `git rev-parse --git-path HEAD` returns 226`/path/main/.git/worktrees/test-next/HEAD` (not 227`/path/other/test-next/.git/HEAD` or `/path/main/.git/HEAD`) while `git 228rev-parse --git-path refs/heads/master` uses 229$GIT_COMMON_DIR and returns `/path/main/.git/refs/heads/master`, 230since refs are shared across all working trees. 231 232See linkgit:gitrepository-layout[5] for more information. The rule of 233thumb is do not make any assumption about whether a path belongs to 234$GIT_DIR or $GIT_COMMON_DIR when you need to directly access something 235inside $GIT_DIR. Use `git rev-parse --git-path` to get the final path. 236 237If you manually move a linked working tree, you need to update the 'gitdir' file 238in the entry's directory. For example, if a linked working tree is moved 239to `/newpath/test-next` and its `.git` file points to 240`/path/main/.git/worktrees/test-next`, then update 241`/path/main/.git/worktrees/test-next/gitdir` to reference `/newpath/test-next` 242instead. 243 244To prevent a $GIT_DIR/worktrees entry from being pruned (which 245can be useful in some situations, such as when the 246entry's working tree is stored on a portable device), use the 247`git worktree lock` command, which adds a file named 248'locked' to the entry's directory. The file contains the reason in 249plain text. For example, if a linked working tree's `.git` file points 250to `/path/main/.git/worktrees/test-next` then a file named 251`/path/main/.git/worktrees/test-next/locked` will prevent the 252`test-next` entry from being pruned. See 253linkgit:gitrepository-layout[5] for details. 254 255LIST OUTPUT FORMAT 256------------------ 257The worktree list command has two output formats. The default format shows the 258details on a single line with columns. For example: 259 260------------ 261$ git worktree list 262/path/to/bare-source (bare) 263/path/to/linked-worktree abcd1234 [master] 264/path/to/other-linked-worktree 1234abc (detached HEAD) 265------------ 266 267Porcelain Format 268~~~~~~~~~~~~~~~~ 269The porcelain format has a line per attribute. Attributes are listed with a 270label and value separated by a single space. Boolean attributes (like 'bare' 271and 'detached') are listed as a label only, and are only present if and only 272if the value is true. An empty line indicates the end of a worktree. For 273example: 274 275------------ 276$ git worktree list --porcelain 277worktree /path/to/bare-source 278bare 279 280worktree /path/to/linked-worktree 281HEAD abcd1234abcd1234abcd1234abcd1234abcd1234 282branch refs/heads/master 283 284worktree /path/to/other-linked-worktree 285HEAD 1234abc1234abc1234abc1234abc1234abc1234a 286detached 287 288------------ 289 290EXAMPLES 291-------- 292You are in the middle of a refactoring session and your boss comes in and 293demands that you fix something immediately. You might typically use 294linkgit:git-stash[1] to store your changes away temporarily, however, your 295working tree is in such a state of disarray (with new, moved, and removed 296files, and other bits and pieces strewn around) that you don't want to risk 297disturbing any of it. Instead, you create a temporary linked working tree to 298make the emergency fix, remove it when done, and then resume your earlier 299refactoring session. 300 301------------ 302$ git worktree add -b emergency-fix ../temp master 303$ pushd ../temp 304# ... hack hack hack ... 305$ git commit -a -m 'emergency fix for boss' 306$ popd 307$ git worktree remove ../temp 308------------ 309 310BUGS 311---- 312Multiple checkout in general is still experimental, and the support 313for submodules is incomplete. It is NOT recommended to make multiple 314checkouts of a superproject. 315 316GIT 317--- 318Part of the linkgit:git[1] suite