npm package: @rowing-tech/worktree-manager
Description: A manager for setting up git worktrees in any repository - Built at Rowing.tech
Author: faramos
Latest version: 1.0.4

# Worktree Manager 🚀

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

> Built with ❤️ at [Rowing.tech](https://www.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):**

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

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

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

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

### 3. Start Working

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

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

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

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

```bash
# 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](https://github.com/faramos) at [Rowing.tech](https://www.rowing.tech) - Augmenting workforce through intelligent automation, AI orchestration and custom solutions.

## License

MIT - see [LICENSE](LICENSE) for details