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