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