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-]track:: 119 When creating a new branch, if `<commit-ish>` is a branch, 120 mark it as "upstream" from the new branch. This is the 121 default if `<commit-ish>` is a remote-tracking branch. See 122 "--track" in linkgit:git-branch[1] for details. 123 124--lock:: 125 Keep the working tree locked after creation. This is the 126 equivalent of `git worktree lock` after `git worktree add`, 127 but without race condition. 128 129-n:: 130--dry-run:: 131 With `prune`, do not remove anything; just report what it would 132 remove. 133 134--porcelain:: 135 With `list`, output in an easy-to-parse format for scripts. 136 This format will remain stable across Git versions and regardless of user 137 configuration. See below for details. 138 139-v:: 140--verbose:: 141 With `prune`, report all removals. 142 143--expire <time>:: 144 With `prune`, only expire unused working trees older than <time>. 145 146--reason <string>:: 147 With `lock`, an explanation why the working tree is locked. 148 149<worktree>:: 150 Working trees can be identified by path, either relative or 151 absolute. 152+ 153If the last path components in the working tree's path is unique among 154working trees, it can be used to identify worktrees. For example if 155you only have two working trees, at "/abc/def/ghi" and "/abc/def/ggg", 156then "ghi" or "def/ghi" is enough to point to the former working tree. 157 158DETAILS 159------- 160Each linked working tree has a private sub-directory in the repository's 161$GIT_DIR/worktrees directory. The private sub-directory's name is usually 162the base name of the linked working tree's path, possibly appended with a 163number to make it unique. For example, when `$GIT_DIR=/path/main/.git` the 164command `git worktree add /path/other/test-next next` creates the linked 165working tree in `/path/other/test-next` and also creates a 166`$GIT_DIR/worktrees/test-next` directory (or `$GIT_DIR/worktrees/test-next1` 167if `test-next` is already taken). 168 169Within a linked working tree, $GIT_DIR is set to point to this private 170directory (e.g. `/path/main/.git/worktrees/test-next` in the example) and 171$GIT_COMMON_DIR is set to point back to the main working tree's $GIT_DIR 172(e.g. `/path/main/.git`). These settings are made in a `.git` file located at 173the top directory of the linked working tree. 174 175Path resolution via `git rev-parse --git-path` uses either 176$GIT_DIR or $GIT_COMMON_DIR depending on the path. For example, in the 177linked working tree `git rev-parse --git-path HEAD` returns 178`/path/main/.git/worktrees/test-next/HEAD` (not 179`/path/other/test-next/.git/HEAD` or `/path/main/.git/HEAD`) while `git 180rev-parse --git-path refs/heads/master` uses 181$GIT_COMMON_DIR and returns `/path/main/.git/refs/heads/master`, 182since refs are shared across all working trees. 183 184See linkgit:gitrepository-layout[5] for more information. The rule of 185thumb is do not make any assumption about whether a path belongs to 186$GIT_DIR or $GIT_COMMON_DIR when you need to directly access something 187inside $GIT_DIR. Use `git rev-parse --git-path` to get the final path. 188 189If you move a linked working tree, you need to update the 'gitdir' file 190in the entry's directory. For example, if a linked working tree is moved 191to `/newpath/test-next` and its `.git` file points to 192`/path/main/.git/worktrees/test-next`, then update 193`/path/main/.git/worktrees/test-next/gitdir` to reference `/newpath/test-next` 194instead. 195 196To prevent a $GIT_DIR/worktrees entry from being pruned (which 197can be useful in some situations, such as when the 198entry's working tree is stored on a portable device), use the 199`git worktree lock` command, which adds a file named 200'locked' to the entry's directory. The file contains the reason in 201plain text. For example, if a linked working tree's `.git` file points 202to `/path/main/.git/worktrees/test-next` then a file named 203`/path/main/.git/worktrees/test-next/locked` will prevent the 204`test-next` entry from being pruned. See 205linkgit:gitrepository-layout[5] for details. 206 207LIST OUTPUT FORMAT 208------------------ 209The worktree list command has two output formats. The default format shows the 210details on a single line with columns. For example: 211 212------------ 213S git worktree list 214/path/to/bare-source (bare) 215/path/to/linked-worktree abcd1234 [master] 216/path/to/other-linked-worktree 1234abc (detached HEAD) 217------------ 218 219Porcelain Format 220~~~~~~~~~~~~~~~~ 221The porcelain format has a line per attribute. Attributes are listed with a 222label and value separated by a single space. Boolean attributes (like 'bare' 223and 'detached') are listed as a label only, and are only present if and only 224if the value is true. An empty line indicates the end of a worktree. For 225example: 226 227------------ 228S git worktree list --porcelain 229worktree /path/to/bare-source 230bare 231 232worktree /path/to/linked-worktree 233HEAD abcd1234abcd1234abcd1234abcd1234abcd1234 234branch refs/heads/master 235 236worktree /path/to/other-linked-worktree 237HEAD 1234abc1234abc1234abc1234abc1234abc1234a 238detached 239 240------------ 241 242EXAMPLES 243-------- 244You are in the middle of a refactoring session and your boss comes in and 245demands that you fix something immediately. You might typically use 246linkgit:git-stash[1] to store your changes away temporarily, however, your 247working tree is in such a state of disarray (with new, moved, and removed 248files, and other bits and pieces strewn around) that you don't want to risk 249disturbing any of it. Instead, you create a temporary linked working tree to 250make the emergency fix, remove it when done, and then resume your earlier 251refactoring session. 252 253------------ 254$ git worktree add -b emergency-fix ../temp master 255$ pushd ../temp 256# ... hack hack hack ... 257$ git commit -a -m 'emergency fix for boss' 258$ popd 259$ rm -rf ../temp 260$ git worktree prune 261------------ 262 263BUGS 264---- 265Multiple checkout in general is still experimental, and the support 266for submodules is incomplete. It is NOT recommended to make multiple 267checkouts of a superproject. 268 269git-worktree could provide more automation for tasks currently 270performed manually, such as: 271 272- `remove` to remove a linked working tree and its administrative files (and 273 warn if the working tree is dirty) 274- `mv` to move or rename a working tree and update its administrative files 275 276GIT 277--- 278Part of the linkgit:git[1] suite