@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

``bash
npm install -g @continuedev/worktree-tools
`

Or use directly with npx:

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

Quick Start

`bash


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

$3

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

`bash
wt init
`

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

$3

Creates a new worktree with all dependencies copied.

`bash


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 is recommended for everyday use.

$3

Check the copy status of a worktree.

`bash


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)

$3

List all worktrees.

`bash
wt list
`

$3

Remove a worktree.

`bash


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:

`yaml


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
`

$3

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:

`yaml
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
`

$3

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/
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

$3

By default (customizable via config):

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

$3

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

$3

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.

$3

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

`bash
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

$3

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

Examples

$3

`yaml


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):

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

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

$3

`yaml
cowCopyTargets:
- node_modules

regularCopyTargets:
- .env
`

$3

`yaml
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