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