Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Branches and Tags

git worktree command

Reference for git worktree: add, list, remove, move, lock and prune linked working trees, use -b and --detach, and understand what is shared and what is not.

git worktree lets one repository have several working directories, each with its own checked-out branch. All of them share the same object database, refs and configuration, so a second worktree costs only the files on disk, not another clone.

Typical uses: reviewing a pull request while your own work stays untouched, running a long test on one branch while you edit another, or keeping a release checkout beside main. A branch can be checked out in only one worktree at a time.

Terminal
git worktree add ../hotfix hotfix-branch
git worktree list
git worktree remove ../hotfix

Try it

Bash Add, list and remove a worktree

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Detached, locked and pruned worktrees

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
git worktree add [-f] [--detach] [--checkout | --no-checkout] [--lock [--reason <s>]]
                 [-b <new-branch> | -B <new-branch>] <path> [<commit-ish>]
git worktree list [--porcelain [-z]] [-v]
git worktree remove [-f] <worktree>
git worktree move <worktree> <new-path>
git worktree lock [--reason <string>] <worktree>
git worktree unlock <worktree>
git worktree prune [-n] [-v] [--expire <time>]
git worktree repair [<path>...]
Name Description
add <path> [<commit-ish>] Create a new working tree at <path>. With a branch name it checks that branch out; with no commit-ish it creates a branch named after the directory.
-b, -B Create (or reset) a new branch for the worktree.
--detach Check out a commit with a detached HEAD.
--no-checkout Create the directory without populating files (useful with sparse checkout).
list Show all worktrees with their path, commit and branch.
remove Delete a clean worktree and its administrative data; -f also removes one with changes.
move Relocate a worktree.
lock / unlock Prevent pruning or removal, for worktrees on removable media.
prune Remove metadata for worktrees whose directory is gone.
repair Fix links after the main repository or a worktree was moved by hand.

Returns: add prints Preparing worktree ... (to standard error); list prints one line per worktree.

Errors: "fatal: '' is already checked out at ''" when the branch is used elsewhere; "contains modified or untracked files" when removing a dirty tree; the main worktree cannot be removed.

Usage notes

  • Shared: objects, refs, tags, remotes, and configuration (unless extensions.worktreeConfig is on). Per worktree: HEAD, the index, and files like MERGE_HEAD, rebase-merge and refs/bisect.
  • Layout: a linked worktree has a .git file pointing to .git/worktrees/<name> in the main repository; see .git file and commondir.
  • Branch locking protects you from moving the same branch in two places. --force overrides it for the rare cases you need it.
  • Do not delete the directory by hand. Use git worktree remove; if you did delete it, git worktree prune cleans the records (they are also pruned by git gc).
  • Moving the main repository breaks the links; git worktree repair reconnects them.
  • Hooks and config such as core.hooksPath apply to all worktrees; per-worktree values need git config --worktree.
  • Submodules are not supported well in linked worktrees; avoid the combination for important work.
  • Tooling tip: build output and node_modules are not shared, so each worktree needs its own installation.