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 add [-f|--force] [--detach] [-b ] [--checkout-create] <path> [<commit-ish>]
git worktree list [--porcelain]
git worktree prune [-n|--dry-run] [-v|--verbose]
git worktree remove [-f|--force] <worktree>
git worktree move <worktree> <new-path>
git worktree lock [--reason <string>] <worktree>
git worktree unlock <worktree>

add
    Create a new working tree at specified path, optionally checking out a commit-ish or branch

-b , --branch
    Create new branch and check it out in new worktree

--detach
    Detach HEAD in new worktree at specified commit

-f, --force
    Overwrite existing path or allow cross-filesystem

--checkout-create
    Similar to add but create worktree before checkout

list
    List all working trees with paths, refs, and status

--porcelain
    Machine-readable list format for scripting

prune
    Remove working trees missing from filesystem

-n, --dry-run
    Show what would be pruned without action

-v, --verbose
    Verbose output during pruning

remove
    Remove specified working tree directory

move
    Move working tree to new path

lock
    Lock worktree to prevent pruning (add optional reason)

--reason
    Specify lock reason

unlock
    Unlock previously locked worktree

The git worktree command enables managing multiple working trees (checkouts) attached to a single Git repository. This allows developers to work on several branches simultaneously without needing to stash changes or switch contexts frequently.

Each worktree has its own working directory, index, and HEAD, but shares the same object database and refs with the main repository. This is particularly useful for:
• Parallel feature development.
• Quick context switching between long-running tasks.
• Bisecting or experimenting without disrupting main work.

Key subcommands include add to create new worktrees, list to enumerate them, prune to clean up stale references, remove and move for maintenance, and lock/unlock to protect against accidental deletion.

Worktrees must reside on the same filesystem as the repository (or use git worktree add --force for symlinks). They enhance productivity in complex projects while keeping repository size minimal.

Worktrees require Git 2.5+; cannot nest worktrees; main worktree cannot be removed; locked worktrees resist pruning; cross-filesystem needs --force; bare repos need explicit main worktree setup.

git worktree add ../feature-branch feature-branch
Adds worktree at ../feature-branch checking out feature-branch.

git worktree list
Lists all worktrees.

Bare repos (--bare) support worktrees but lack a default main one; use git worktree add --guess-remote or specify explicitly.

Introduced in Git 2.5.0 (January 2015) to address limitations of single-worktree model. Evolved with subcommands like move (2.17), lock (2.22), and porcelain output. Widely adopted for multi-branch workflows, especially in CI/CD and large monorepos.

git-branch(1), git-checkout(1), git-switch(1), git-stash(1)