git-worktree

Create a new directory with the specified branch checked out into it

$ git worktree add [path/to/directory] [branch]

$ git worktree add [path/to/directory] -b [new_branch]

$ git worktree list

$ git worktree prune

git worktree subcommand [options] [arguments]

Common subcommands:
add: git worktree add [-b new-branch] [--track] [--bare] [--[no-]orphan] [--[no-]checkout] [--detach] [--force] [--dry-run] path [commit-ish]
list: git worktree list [--porcelain] [--bare]
remove: git worktree remove [--force] path
prune: git worktree prune [--expire time]
move: git worktree move path new-path
lock: git worktree lock path
unlock: git worktree unlock path

add path [commit-ish]
    Creates a new working tree at <path>, optionally checking out <commit-ish>.

list
    Lists all linked working trees.

remove path
    Removes a linked working tree at <path>.

prune
    Removes stale working tree information (directories corresponding to removed worktrees).

move path new-path
    Moves a linked working tree from <path> to <new-path>.

lock path
    Marks a working tree as 'locked', preventing accidental removal.

unlock path
    Unlocks a previously locked working tree.

--detach
     (for add) Check out HEAD into a detached HEAD state in the new worktree.

-b new-branch
     (for add) Create and checkout a new branch named <new-branch> in the new worktree.

--track
     (for add) Set up the new branch to track a remote branch if <commit-ish> is a remote-tracking branch.

--bare
     (for add, list) For add, creates a bare worktree (no working files). For list, lists bare worktrees.

--[no-]orphan
     (for add) Create an orphan branch in the new worktree (--orphan) or prevent it (--no-orphan).

--[no-]checkout
     (for add) Perform (--checkout) or skip (--no-checkout) the initial checkout of files.

--force
     (for add, remove) For add, force creation into a non-empty directory. For remove, force removal of a dirty worktree.

--dry-run
     (for add) Don't actually create the worktree, just show what would happen.

--porcelain
     (for list) Output working tree information in a machine-readable format.

--expire time
     (for prune) Prune working trees whose associated Git directory is older than the specified time.

git worktree allows creating and managing additional linked working trees for a single Git repository. This means you can have multiple directories, each containing a checkout of a different branch or commit from the same underlying repository. It's incredibly useful for developers who need to work on multiple features, branches, or experiments concurrently without constantly switching branches in a single working directory, stashing changes, or cloning the repository multiple times. It facilitates rapid context switching and parallel development, making it easier to manage complex workflows and quickly test different codebases.

A worktree cannot be a submodule, nor can it be nested inside another worktree. The original/main worktree cannot be removed using git worktree remove. Removing a worktree with uncommitted changes requires the --force option. Each linked worktree maintains its own HEAD and index, but they all share the same object database with the main repository.

A git worktree maintains a separate HEAD, index, and working tree for each linked worktree, all sharing the same Git object database (typically located in the original repository's .git/objects directory). This shared object database makes linked worktrees very lightweight in terms of disk space, as only the working files and per-worktree metadata are duplicated.

git worktree is ideal for:
- Working on a feature branch while simultaneously performing a hotfix on main.
- Testing a branch against different environments or dependencies without altering your primary working directory.
- Running build processes for multiple branches in parallel.
- Reviewing pull requests or patches in an isolated environment without disturbing your current work.

git worktree was introduced in Git version 2.5 (June 2015). It was developed to address the common use case of needing to work on multiple branches simultaneously without duplicating the entire repository or constantly stashing/unstashing changes in a single working directory. Before its introduction, users often resorted to multiple clones or complex manual setups to achieve similar parallel development capabilities. Its availability significantly streamlined such workflows by providing a first-class mechanism within Git itself.

git-clone(1), git-branch(1), git-checkout(1), git-reflog(1)