Fast git worktree setup with Copy-on-Write - instantly create isolated dev environments
npm install @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.
- ⚡️ 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
``bash`
npm install -g @continuedev/worktree-tools
Or use directly with npx:
`bash`
npx @continuedev/worktree-tools my-branch --new
`bashFirst time setup - create config file
wt init
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 --newCheckout existing branch (short form)
wt feature/existing-branchOr use explicit 'setup' command
wt setup feature/new-ui --new
`Options:
-
-n, --new - Create a new branch instead of checking out existingNote: The short form
wt is recommended for everyday use.$3
Check the copy status of a worktree.
`bash
Check status
wt status my-featureFollow 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-featureForce removal with uncommitted changes
wt remove my-feature --force
`Options:
-
-f, --force - Force removal even with uncommitted changesConfiguration
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 buildsSmall 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 setExamples:
`yaml
cowCopyTargets:
- packages/*/node_modules # All package node_modules
- services/*/dist # All service dist directories
- **/.next # All .next directories anywhereregularCopyTargets:
- **/.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 cachesHow 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/distregularCopyTargets:
- .env
- packages/frontend/.env
- packages/backend/.env
`With globs (recommended):
`yaml
cowCopyTargets:
- node_modules
- packages/*/node_modules # All packages
- packages/*/dist # All buildsregularCopyTargets:
- .env
- packages/*/.env # All package .env files
`$3
`yaml
cowCopyTargets:
- node_modulesregularCopyTargets:
- .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 inforegularCopyTargets:
- .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.
Apache-2.0
- Git Worktree Documentation
- APFS Copy-on-Write