git-worktree
Manage multiple working trees
TLDR
Create a new directory with the specified branch checked out into it
$ git worktree add [path/to/directory] [branch]
Create a new directory with a new branch checked out into it
$ git worktree add [path/to/directory] -b [new_branch]
List all the working directories attached to this repository
$ git worktree list
Remove a worktree (after deleting worktree directory)
$ git worktree prune
SYNOPSIS
gitworktree add [ -f] [ --detach] [ --checkout] [ --lock] [ -b <new -branch>] <path> [<commit -ish>] gitworktree list [ --porcelain] gitworktree lock [ --reason <string>] <worktree> gitworktree move <worktree> <new -path> gitworktree prune [ -n] [ -v] [ --expire <expire>] gitworktree remove [ -f] <worktree> gitworktree unlock <worktree>
DESCRIPTION
COMMANDS
add <path> [<commit -ish>] Create <path> and checkout <commit-ish> into it . The new working directory is linked to the current repository, sharing everything except working directory specific files such as HEAD, index, etc . - may also be specified as <commit-ish> ;it is synonymous with @{-1} .
If <commit -ish> is a branch name (call it <branch> )and is not found, and neither -b nor -B nor --detach are used, but there does exist a tracking branch in exactly one remote (call it <remote> )with a matching name, treat as equivalent to: .RS 4$ git worktree add --track -b <branch> <path> <remote>/<branch> .RE If the branch exists in multiple remotes and one of them is named by the checkout.defaultRemote configuration variable, we use that one for the purposes of disambiguation, even if the <branch> isn unique across all remotes . Set it to e .g . checkout.defaultRemote=origin to always checkout remote branches from there if <branch> is ambiguous but exists on the origin remote . See also checkout.defaultRemote in git-config (1). If <commit-ish> is omitted and neither -b nor -B nor --detach used, then, as a convenience, the new worktree is associated with a branch (call it <branch> )named after $(basename<path>) . If <branch> doesn exist, a new branch based on HEAD is automatically created as if -b <branch> was given . If <branch> does exist, it will be checked out in the new worktree, if it not checked out anywhere else, otherwise the command will refuse to create the worktree (unless --force is used) .
list List details of each worktree . The main worktree is listed first, followed by each of the linked worktrees . The output details include if the worktree is bare, the revision currently checked out, and the branch currently checked out (or detachedHEAD if none) .
lock If a working tree is on a portable device or network share which is not always mounted, lock it to prevent its administrative files from being pruned automatically . This also prevents it from being moved or deleted . Optionally, specify a reason for the lock with --reason .
move Move a working tree to a new location . Note that the main working tree or linked working trees containing submodules cannot be moved .
prune Prune working tree information in $GIT_DIR/worktrees .
remove Remove a working tree . Only clean working trees (no untracked files and no modification in tracked files) can be removed . Unclean working trees or ones with submodules can be removed with --force . The main working tree cannot be removed .
unlock Unlock a working tree, allowing it to be pruned, moved or deleted .
OPTIONS
-f, --force By default, add refuses to create a new working tree when <commit-ish> is a branch name and is already checked out by another working tree, or if <path> is already assigned to some working tree but is missing (for instance, if <path> was deleted manually) . This option overrides these safeguards . To add a missing but locked working tree path, specify --force twice .
move refuses to move a locked working tree unless --force is specified twice . remove refuses to remove an unclean working tree unless --force is used . To remove a locked working tree, specify --force twice .-b <new -branch>, -B <new -branch> With add ,create a new branch named <new-branch> starting at <commit-ish> ,and check out <new-branch> into the new working tree . If <commit-ish> is omitted, it defaults to HEAD . By default, -b refuses to create a new branch if it already exists . -B overrides this safeguard, resetting <new-branch> to <commit-ish> .
--detach With add ,detach HEAD in the new working tree . See "DETACHED HEAD" in git-checkout (1).
--[no -]checkout By default, add checks out <commit-ish> ,however, --no -checkout can be used to suppress checkout in order to make customizations, such as configuring sparse -checkout . See "Sparse checkout" in git-read-tree (1).
--[no -]guess -remote With worktreeadd <path> ,without <commit-ish> ,instead of creating a new branch from HEAD, if there exists a tracking branch in exactly one remote matching the basename of <path> ,base the new branch on the remote -tracking branch, and mark the remote -tracking branch as "upstream" from the new branch . This can also be set up as the default behaviour by using the worktree.guessRemote config option .
--[no -]track When creating a new branch, if <commit-ish> is a branch, mark it as "upstream" from the new branch . This is the default if <commit-ish> is a remote -tracking branch . See " --track" in git-branch (1) for details .
--lock Keep the working tree locked after creation . This is the equivalent of gitworktree lock after gitworktree add ,but without race condition .
-n, --dry -run With prune ,do not remove anything; just report what it would remove .
--porcelain With list ,output in an easy -to -parse format for scripts . This format will remain stable across Git versions and regardless of user configuration . See below for details .
-q, --quiet With add ,suppress feedback messages .
-v, --verbose With prune ,report all removals .
--expire <time> With prune ,only expire unused working trees older than <time> .
--reason <string> With lock ,an explanation why the working tree is locked .
<worktree> Working trees can be identified by path, either relative or absolute . If the last path components in the working tree path is unique among working trees, it can be used to identify worktrees . For example if you only have two working trees, at "/abc/def/ghi" and "/abc/def/ggg", then "ghi" or "def/ghi" is enough to point to the former working tree .
REFS
CONFIGURATION FILE
$ git config extensions .worktreeConfig true .RE In this mode, specific configuration stays in the path pointed by gitrev -parse --git -path config .worktree . You can add or update configuration in this file with gitconfig --worktree . Older Git versions will refuse to access repositories with this extension . Note that in this file, the exception for core.bare and core.worktree is gone . If you have them in $GIT_DIR/config before, you must move them to the config.worktree of the main working tree . You may also take this opportunity to review and move other configuration that you do not want to share to all working trees: '-04' '+03' .sp -1
2.3 core.worktree and core.bare should never be shared '-04' '+03' .sp -1
2.3 core.sparseCheckout is recommended per working tree, unless you are sure you always use sparse checkout for all working trees .
DETAILS
LIST OUTPUT FORMAT
$ git worktree list /path/to/bare -source (bare) /path/to/linked -worktree abcd1234 [master] /path/to/other -linked -worktree 1234abc (detached HEAD) .RE
Porcelain Format
The porcelain format has a line per attribute . Attributes are listed with a label and value separated by a single space . Boolean attributes (like bare and detached )are listed as a label only, and are only present if and only if the value is true . The first attribute of a worktree is always worktree ,an empty line indicates the end of the record . For example: .RS 4$ git worktree list --porcelain worktree /path/to/bare -source bare
worktree /path/to/linked -worktree HEAD abcd1234abcd1234abcd1234abcd1234abcd1234 branch refs/heads/master
worktree /path/to/other -linked -worktree HEAD 1234abc1234abc1234abc1234abc1234abc1234a detached .RE
EXAMPLES
$ git worktree add -b emergency -fix . ./temp master $ pushd . ./temp # . . . hack hack hack . . . $ git commit -a -m (Aqemergency fix for boss (Aq $ popd $ git worktree remove . ./temp .RE