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