C

Understanding Git Worktree: Commands, Flags, and Best Practices

A comprehensive guide to git worktree commands, their options, and when to use each flag.

conceptsworktreereferenceflagsparallel development

Overview

Git worktree allows you to check out multiple branches simultaneously in separate directories, all linked to the same repository. This is invaluable for parallel development, code reviews, and emergency fixes without disrupting your current work.

Core commands

Git worktree provides four main subcommands:

  • git worktree add — Create a new worktree
  • git worktree list — Show all linked worktrees
  • git worktree remove — Delete a worktree
  • git worktree prune — Clean up stale worktree references

git worktree add

The most commonly used command. Creates a new working tree at the specified path.

Basic syntax

git worktree add <path> [<commit-ish>]

Flags and options

  • -b <new-branch> — Create a new branch and check it out in the worktree

    # Create worktree with new branch based on current HEAD
git worktree add -b feature/new-ui ../feature-ui

# Create worktree with new branch based on specific commit
git worktree add -b hotfix/login ../hotfix origin/main

  • -B <new-branch> — Like -b, but resets the branch if it already exists

    # Force create/reset branch in new worktree
git worktree add -B experiment/perf ../perf-test origin/main

  • --detach — Create worktree in detached HEAD state (no branch)

    # Useful for inspecting a specific commit or tag
git worktree add --detach ../release-audit v2.1.0

  • --track — Set up tracking for the new branch against a remote branch

    # Create local branch that tracks remote
git worktree add --track -b feat/api ../api-work origin/feat/api

  • --no-track — Do not set up tracking even when branching from a remote

    git worktree add --no-track -b local-experiment ../experiment origin/main

  • --guess-remote — Automatically find and track a remote branch with the same name

    # If origin/feat/search exists, automatically track it
git worktree add --guess-remote ../search feat/search

  • --lock — Lock the worktree immediately after creation (prevents accidental pruning)

    # Useful for worktrees on removable drives
git worktree add --lock ../external-drive/repo-backup main

  • --reason <string> — Provide a reason when using --lock

    git worktree add --lock --reason "USB drive backup" ../usb/repo main

  • -f, --force — Allow adding a worktree even if the path is already registered

    # Override existing registration
git worktree add -f ../recovered-worktree main

  • -q, --quiet — Suppress feedback messages

    git worktree add -q ../silent-worktree main

git worktree list

Displays all worktrees associated with the repository.

git worktree list

Output example:

/home/user/project         abc1234 [main]
/home/user/project-hotfix  def5678 [hotfix/login]
/home/user/project-review  ghi9012 (detached HEAD)

Flags

  • --porcelain — Machine-readable output format for scripting
  • -v, --verbose — Show additional information like lock reasons

git worktree remove

Removes a worktree and its administrative files. The directory must be clean (no uncommitted changes).

git worktree remove ../project-hotfix

Flags

  • -f, --force — Remove even if there are uncommitted changes (use with caution)

git worktree prune

Cleans up stale worktree references when directories have been manually deleted or moved.

git worktree prune

Flags

  • -n, --dry-run — Show what would be pruned without actually doing it
  • -v, --verbose — Report all removals
  • --expire <time> — Only prune worktrees older than the specified time

git worktree lock/unlock

Protect worktrees from accidental pruning, useful for worktrees on removable media.

# Lock a worktree
git worktree lock ../external-worktree

# Lock with a reason
git worktree lock --reason "On network drive" ../network-worktree

# Unlock when done
git worktree unlock ../external-worktree

git worktree move

Relocate a worktree to a new path.

git worktree move ../old-path ../new-path

Flags

  • -f, --force — Force move even if destination exists

git worktree repair

Repair worktree administrative files after manual moves or path changes.

# Repair all worktrees
git worktree repair

# Repair specific paths
git worktree repair ../moved-worktree

Common patterns

Create worktree from remote branch

# Fetch and create worktree in one flow
git fetch origin feature/api
git worktree add ../api-review origin/feature/api

Create worktree for a tag or release

git worktree add --detach ../v2-audit v2.0.0

Create worktree with new branch from remote

git worktree add -b local-feature --track ../feature-work origin/feature

Important constraints

  • One branch per worktree — A branch cannot be checked out in multiple worktrees simultaneously
  • Shared objects — All worktrees share the same .git objects, so disk usage is minimal
  • Independent indexes — Each worktree has its own staging area and working directory
  • Stash is shared — The stash is global across all worktrees in the repository

Related scenarios