workon 3.2.4 → 3.4.0

package/README.md

@@ -6,12 +6,13 @@ A productivity CLI tool that helps developers quickly switch between projects wi
 
 ## Features
 
-✨ **Smart Project Switching** - Switch between projects in your current shell (no nested processes!)  
-🔧 **IDE Integration** - Automatically open projects in VS Code, IntelliJ IDEA, or Atom  
-🌐 **Web Integration** - Launch project websites and documentation  
-🌳 **Git Branch Support** - Different configurations for different branches  
-📁 **Auto Directory Change** - Seamlessly `cd` into project directories  
-⚡ **Interactive Setup** - Guided project configuration  
+✨ **Smart Project Switching** - Switch between projects in your current shell (no nested processes!)
+🔧 **IDE Integration** - Automatically open projects in VS Code, IntelliJ IDEA, or Atom
+🌐 **Web Integration** - Launch project websites and documentation
+🌳 **Git Branch Support** - Different configurations for different branches
+🌲 **Git Worktrees** - Create, open, and manage git worktrees with tmux integration
+📁 **Auto Directory Change** - Seamlessly `cd` into project directories
+⚡ **Interactive Setup** - Guided project configuration
 🔄 **Backward Compatible** - Legacy nested shell mode still available
 
 ## Requirements
@@ -53,17 +54,23 @@ workon --help
 
 ## Quick Start
 
-1. **Create your first project:**
+1. **Add your first project:**
    ```bash
-   workon  # Start interactive mode
+   cd ~/code/myproject
+   workon add .  # Register current directory as a project
    ```
 
-2. **Switch to a project:**
+2. **Or use interactive mode:**
+   ```bash
+   workon  # Start interactive setup wizard
+   ```
+
+3. **Switch to a project:**
    ```bash
    workon myproject  # Automatically cd + open IDE
    ```
 
-3. **List available projects:**
+4. **List available projects:**
    ```bash
    workon config list
    ```
@@ -115,6 +122,23 @@ workon config set projects.myapp.events.ide true
 
 ## Usage Examples
 
+### Adding Projects
+
+```bash
+# Add current directory as a project
+cd ~/code/myproject
+workon add .
+
+# Add with a custom name
+workon add . --name my-awesome-project
+
+# Add with specific IDE
+workon add . --ide idea
+
+# Add a project from any path
+workon add ~/code/another-project
+```
+
 ### Basic Project Switching
 ```bash
 # Switch to project (changes directory + opens IDE)
@@ -126,12 +150,104 @@ workon myproject --shell
 #         code "/path/to/myproject" &
 ```
 
+### Colon Syntax (Run Specific Events)
+
+Use the colon syntax to run only specific events for a project:
+
+```bash
+# Run only the cwd event (just change directory)
+workon myproject:cwd
+
+# Run multiple specific events
+workon myproject:cwd,ide
+
+# Show available events for a project
+workon myproject:help
+```
+
 ### Branch-Specific Configuration
 ```bash
 # Configure different settings for a git branch
 workon myproject#feature-branch
 ```
 
+### Git Worktrees
+
+Manage git worktrees with full tmux integration. There are two commands:
+
+- `workon worktrees` - Manage worktrees (run from the **main repository**)
+- `workon worktree` - Operate on the **current worktree** you're inside
+
+#### Managing Worktrees (from main repo)
+
+```bash
+cd ~/code/myproject
+
+# Show interactive worktree menu
+workon worktrees
+
+# List worktrees
+workon worktrees list
+
+# Create a new worktree
+workon worktrees add feature-branch
+
+# Open workon session in a worktree (creates tmux session)
+workon worktrees open feature-branch
+
+# Remove a worktree
+workon worktrees remove feature-branch
+
+# Merge worktree branch and remove
+workon worktrees merge feature-branch
+
+# Create branch from detached HEAD (for PR workflow)
+workon worktrees branch my-worktree new-branch-name --push
+```
+
+#### Operating on Current Worktree (from inside a worktree)
+
+When you're inside a worktree, use `workon worktree` (singular):
+
+```bash
+cd ~/code/myproject/.worktrees/feature-branch
+
+# Show status of current worktree
+workon worktree
+workon worktree status
+
+# Merge this worktree's branch into main/master
+workon worktree merge
+
+# Remove this worktree (shows instructions to exit first)
+workon worktree remove
+```
+
+If you run `workon worktrees` from inside a worktree, you'll get a helpful error directing you to use `workon worktree` instead.
+
+#### Notes
+
+- If you run worktree commands from an unregistered git repository, workon will prompt you to register it first
+- Worktrees created by workon are stored in `.worktrees/` inside the project
+- External worktrees (created elsewhere) show as "(external)" in the list
+
+#### Post-Setup Hook
+
+Create `.workon/worktree-setup.sh` in your project to run commands after creating a worktree:
+
+```bash
+#!/bin/bash
+# Install dependencies
+[ -f "package.json" ] && npm install
+
+# Copy environment file
+[ -f "$PROJECT_PATH/.env" ] && cp "$PROJECT_PATH/.env" .env
+```
+
+Environment variables available:
+- `WORKTREE_PATH` - Absolute path to the new worktree
+- `PROJECT_PATH` - Absolute path to the main project
+
 ### Legacy Mode (Nested Shells)
 ```bash
 # Use the old behavior if needed (spawns new shell)