Worktree Manager 🚀

Manage git worktrees in any repository with one command. Work on multiple branches simultaneously without switching contexts.

Built with ❤️ at Rowing.tech

⚠️ Important Safety Notice

Before using this tool:

• 🛡️ Make a backup of your repository before running
• 🧪 Test first in a non-production folder or repository
• 📤 Ensure all changes are pushed to your remote repository
• ⚙️ This tool manipulates files and git configuration extensively

While thoroughly tested with 35 test cases, we strongly recommend experimenting in a safe environment first.

Quick Start

Run from anywhere (no need to be in a git repo):

npx @rowing-tech/worktree-manager@latest

The interactive tool will:

• 🔍 Ask for your repository path or URL if not in a git repo
• 📥 Clone repositories automatically from GitHub, GitLab, Bitbucket URLs
• 🎯 Detect available branches automatically
• 🔄 Offer conversion options (convert existing repo vs tools-only)
• ✅ Create selected worktrees automatically
• 📝 Set up shared environment and scripts

New in v3.1.1: Effect.js Architecture & Best Practices 🔥

• ⚡ Effect.js Architecture - Built with Effect.js for robust functional programming patterns
• 🏗️ Platform Services - Uses @effect/platform for standard file system operations
• 🛡️ Type-Safe Operations - Schema validation and branded types for bulletproof code
• 🔄 Composable Effects - Parallel operations, resource management, and structured concurrency
• 🎯 Enhanced Error Handling - Detailed error context with recovery suggestions
• 🧪 Comprehensive Testing - 35 tests including integration and scenario testing with realistic CLI simulation

Previous Features:

• 📥 Automatic git cloning - paste any GitHub/GitLab URL and it clones automatically
• 🌐 Universal repository support - works with GitHub, GitLab, Bitbucket, and more
• 🔒 Enhanced security - input sanitization prevents shell injection attacks
• 🛡️ Environment protection - existing .env files are never overwritten
• 🚨 Better error handling - specific error messages with actionable solutions
• ✅ Prerequisite validation - checks for required tools before starting
• 🧹 Automatic cleanup - removes partial files if setup fails
• 🛡️ Safe branch filtering - validates branch names for security
• 🎨 Interactive prompts for better user experience
• 🔧 Smart repository detection - works from any directory
• 🏗️ Automatic conversion of existing repos to worktree structure

What You Get

• 🔄 No More Context Switching: Change branches by changing directories
• 🔐 Shared Environment: Single .env file across all worktrees
• 🚀 Parallel Development: Run multiple branches simultaneously
• ⚙️ IDE Configuration Sync: Copy settings between worktrees (VS Code, Cursor, Claude)
• 📦 Dependency Isolation: Separate node_modules for each branch
• 🎯 Smart Setup: Interactive prompts guide you through the process
• 🔧 Flexible Installation: Works from any directory, no pre-setup needed

After Setup

1. Create Your Environment File

cp .env.sample .env
# Edit .env with your actual values

Note: If you already have a .env file, the tool will never overwrite it. Your existing environment variables are always protected.

2. Create Your First Worktree

# For main branch
./scripts/create-worktree.sh main

# For a new feature branch
./scripts/create-worktree.sh feature/my-feature main

3. Start Working

cd main/               # Switch to main branch
pnpm install && pnpm dev

# In another terminal
cd feature/my-feature/ # Switch to feature branch
pnpm install && pnpm dev

Daily Usage

# Create new feature branch
./scripts/create-worktree.sh feature/login-page main

# Work on it
cd feature/login-page/
pnpm install
pnpm dev

# Switch back to main
cd ../main/

# List all worktrees
git worktree list

# Remove old worktrees
git worktree remove feature/old-feature

Project Structure After Setup

your-repository/
├── .env                     # Shared secrets (not in git)
├── scripts/
│   ├── create-worktree.sh   # Creates new worktrees
│   └── sync-ide-config.sh   # Syncs IDE configurations
├── main/                    # Main branch worktree
│   ├── .env → ../.env      # Symlink to shared .env
│   └── [your project files]
└── feature/
    └── your-feature/        # Feature branch worktree
        ├── .env → ../../.env # Symlink to shared .env
        └── [your project files]

Advanced Features

Sync IDE Configurations

# Copy VS Code/Cursor settings between worktrees
./scripts/sync-ide-config.sh main feature/my-feature

Interactive Setup Flow

When you run the command, you'll see:

🚀 Worktree Manager
==================

# If not in a git repository:
❌ Not in a git repository
? Enter the path to your git repository (or git URL to clone): https://github.com/user/repo

🔄 Cloning repository from https://github.com/user/repo...
✅ Repository cloned to ./repo

📁 Detected repository: my-project
📍 Location: /Users/you/my-project

? How would you like to set up worktrees?
  ○ Convert to worktree structure (moves current files to main/ subdirectory)
  ○ Just add worktree tools (keeps current structure)

📋 Available branches:
   main
   develop
   feature/auth

? Which branches would you like to create worktrees for?
◉ main
◯ develop
◯ feature/auth

🚀 Creating worktrees...
✅ Created worktree for main

🎉 Setup complete!
Ready to work! You can now:
  cd main/

Requirements

• Node.js 18+ (for running the CLI)
• Git 2.5+ (for worktree support)
• curl (for git cloning operations)

Platform Support

• ✅ macOS & Linux: Full support
• ✅ Windows: Works with Git Bash or WSL
• ✅ CI/CD: Perfect for parallel testing workflows

Why Use Worktrees?

• No more git stash when switching branches
• Run multiple branches simultaneously for testing
• Separate dependencies - no conflicts between branches
• Faster CI/CD - test multiple branches in parallel
• Better for large projects - avoid long build times when switching

Development

This project is built with modern tooling:

# Clone and setup
git clone https://github.com/rowing-tech/worktree-manager.git
cd worktree-manager
pnpm install

# Development commands
pnpm build        # Compile TypeScript with shebang
pnpm dev          # Build and run CLI with --help
pnpm dev:interactive # Build and run CLI interactively
pnpm dev:watch    # Watch mode for development
pnpm test         # Run tests in watch mode (optimized to avoid restarts)
pnpm test:run     # Run tests once (35 tests pass in ~9 seconds)
pnpm type-check   # Verify TypeScript types

Tech Stack:

• Effect.js v3.x for functional programming patterns and robust error handling
• @effect/platform for cross-platform file system operations
• TypeScript for type safety and modern JavaScript features
• Service Architecture with dependency injection and Effect.js patterns for testability
• Schema Validation with Effect.js Schema and branded types for type-safe operations
• ES Modules for modern compatibility
• Vitest for fast testing with comprehensive coverage
• Inquirer for beautiful interactive prompts (wrapped in Effect patterns)
• tsx for seamless development workflow
• Comprehensive Logging with structured LoggerService following Effect.js patterns
• Resource Management with WorkingDirectoryService for safe operations

Contributing

Found a bug or have an improvement? We welcome contributions!

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes with tests: pnpm test
4. Ensure types are correct: pnpm type-check
5. Submit a pull request

Credits

Developed by faramos at Rowing.tech - Augmenting workforce through intelligent automation, AI orchestration and custom solutions.

License

MIT - see LICENSE for details