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