@continuedev/worktree-tools

Fast git worktree setup with Copy-on-Write - create isolated dev environments in seconds

Creates new git worktrees with all dependencies and build outputs copied instantly using filesystem-level Copy-on-Write. Skip the 10-15 minute npm install and npm run build cycle when working with multiple branches.

Features

• ⚡️ 10-15x faster than traditional worktree setup (60 seconds vs 10-15 minutes)
• 💾 Space efficient - Uses Copy-on-Write to share unchanged files (~100MB per worktree vs. 1.5GB)
• 🔧 Zero config - Works out of the box with sensible defaults
• 📝 Customizable - YAML config file for project-specific needs
• 🎯 Background copy - Start working immediately while files copy
• 🛠️ Status tracking - Monitor copy progress with live updates
• 🌟 Glob patterns - Use packages/*/node_modules instead of listing each package

Installation

npm install -g @continuedev/worktree-tools

Or use directly with npx:

npx @continuedev/worktree-tools my-branch --new

Quick Start

# First time setup - create config file
wt init

# Create a new worktree with new branch
wt my-feature --new

# Switch to it (can start working immediately!)
cd .worktrees/my-feature

# Check copy status
wt status my-feature

# When done, remove it
wt remove my-feature

Commands

wt init

Create a worktree-config.yaml file with default settings. Run this once per project.

wt init

This creates a config file you can edit to customize what gets copied.

wt <branch-name> or wt setup <branch-name>

Creates a new worktree with all dependencies copied.

# Create new branch from current HEAD (short form)
wt feature/new-ui --new

# Checkout existing branch (short form)
wt feature/existing-branch

# Or use explicit 'setup' command
wt setup feature/new-ui --new

Options:

• -n, --new - Create a new branch instead of checking out existing

Note: The short form wt <branch-name> is recommended for everyday use.

wt status <branch-name>

Check the copy status of a worktree.

# Check status
wt status my-feature

# Follow live progress
wt status my-feature --follow

Options:

• -f, --follow - Follow the copy log in real-time (like tail -f)

wt list

List all worktrees.

wt list

wt remove <branch-name>

Remove a worktree.

# Remove worktree
wt remove my-feature

# Force removal with uncommitted changes
wt remove my-feature --force

Options:

• -f, --force - Force removal even with uncommitted changes

Configuration

Run wt init to create a worktree-config.yaml file in your project root:

# Large directories - copied using Copy-on-Write
cowCopyTargets:
  - node_modules
  - app/node_modules
  - packages/*/node_modules # Glob: all package node_modules
  - app/.next
  - services/*/dist # Glob: all service builds

# Small files - copied with regular cp
regularCopyTargets:
  - .env
  - app/.env
  - app/.env.local
  - services/*/.env # Glob: all service .env files

Glob Pattern Support

The config file supports glob patterns for flexible path matching:

• * - Matches any characters except /
• ** - Matches any characters including /
• ? - Matches a single character
• [abc] - Matches any character in the set

Examples:

cowCopyTargets:
  - packages/*/node_modules         # All package node_modules
  - services/*/dist                 # All service dist directories
  - **/.next                        # All .next directories anywhere

regularCopyTargets:
  - **/.env                         # All .env files anywhere
  - services/**/*.config.js         # All config.js files in services

Configuration Categories

cowCopyTargets - Large directories (100+ files, >10MB)

• Uses Copy-on-Write for fast, space-efficient copying
• Best for: node_modules, build outputs (dist, .next, out)

regularCopyTargets - Small files or optional files

• Uses regular file copy
• Files checked for existence (won't error if missing)
• Best for: .env files, configs, build caches

How It Works

1. Creates git worktree - Standard git worktree in .worktrees/<branch-name>
2. Launches background copy - Returns immediately (~1 second)
3. Copies with CoW - Large directories use ditto --clone (macOS) for instant cloning
4. Tracks progress - Status files let you monitor copy progress

What Gets Copied

By default (customizable via config):

• All node_modules directories (root + workspaces)
• Build outputs (.next, dist, out)
• Environment files (.env, .env.local)
• TypeScript build info

Copy-on-Write Explained

On APFS (macOS), files are cloned at the filesystem level:

• Files share the same disk blocks until modified
• Modifications trigger automatic copy (no risk of corruption)
• Much faster than copying data (only metadata operations)
• Dramatically reduces disk space usage

Fallbacks: On non-APFS filesystems, falls back to rsync or cp.

Performance

| Operation | Traditional | With worktree-tools | Speedup | | ----------------------- | ----------- | ------------------- | ------------ | | Create worktree | 10-15 min | ~60 seconds | 10-15x | | Disk space per worktree | 1.5GB | 100MB | 15x less |

Requirements

• Node.js: 16.0.0 or higher
• Git: Any recent version
• macOS: Copy-on-Write works best on APFS (falls back to regular copy on other systems)

Use Cases

Perfect for:

• Feature branches - Work on multiple features simultaneously
• Bug fixes - Quickly create isolated environments for fixes
• Code review - Test PRs without affecting your main branch
• Experiments - Try risky changes in isolated worktrees
• Monorepos - Fast worktree setup even with many workspaces

Troubleshooting

Copy is slow

Copy-on-Write is limited by file count, not size. 60 seconds for ~100k files is normal. The alternative (traditional setup) takes 10-15 minutes.

Config file not found

If you see "No configuration file found", run:

wt init

This creates worktree-config.yaml with sensible defaults. Edit it to customize what gets copied.

The tool searches for the config file in:

1. Current directory
2. scripts/ directory
3. .worktrees/ directory
4. Parent directory

Files not copying

Check that paths in config are relative to repository root (no leading /).

Examples

Monorepo Setup

# Without globs (explicit)
cowCopyTargets:
  - node_modules
  - packages/frontend/node_modules
  - packages/backend/node_modules
  - packages/frontend/dist
  - packages/backend/dist

regularCopyTargets:
  - .env
  - packages/frontend/.env
  - packages/backend/.env

With globs (recommended):

cowCopyTargets:
  - node_modules
  - packages/*/node_modules # All packages
  - packages/*/dist # All builds

regularCopyTargets:
  - .env
  - packages/*/.env # All package .env files

Minimal Setup

cowCopyTargets:
  - node_modules

regularCopyTargets:
  - .env

Complex Monorepo

cowCopyTargets:
  - node_modules
  - apps/*/node_modules           # All apps
  - packages/*/node_modules       # All packages
  - apps/*/.next                  # All Next.js builds
  - packages/*/dist               # All package builds
  - **/*.tsbuildinfo              # All TypeScript build info

regularCopyTargets:
  - .env
  - .env.*                        # All .env variants
  - apps/**/.env                  # All app .env files
  - packages/**/.env              # All package .env files

Contributing

Issues and PRs welcome! See CONTRIBUTING.md for details on:

• Commit message format (Conventional Commits)
• How semantic-release works
• Release workflow

Releases

This package uses semantic-release for automated versioning and publishing. Releases are triggered automatically when commits are merged to main:

• feat: commits → minor version (1.0.0 → 1.1.0)
• fix: commits → patch version (1.0.0 → 1.0.1)
• BREAKING CHANGE: → major version (1.0.0 → 2.0.0)

See the CHANGELOG for release history.

License

Apache-2.0

Related

• Git Worktree Documentation
• APFS Copy-on-Write