git-worktree

# Git Worktree Manager Manage git worktrees for isolated parallel development with a simple, safe interface. ## What It Does Creates and manages git worktrees — separate working directories from the same repository that allow you to: - Work on multiple branches simultaneously without stashing - Review PRs in complete isolation from your current work - Test features without switching branches in your main working directory - Keep separate .env configurations per worktree ## Critical Rule **ALWAYS use the manager script. NEVER use raw `git worktree add` directly.** The manager script provides: - Automatic .env file copying - .gitignore management - Safety validations - Consistent directory structure - Color-coded output ## Manager Script Location ```bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh ``` Replace `${CLAUDE_PLUGIN_ROOT}` with the actual plugin installation path. ## Usage ### create Create a new worktree: ```bash worktree-manager.sh create <branch-name> [from-branch] ``` **Behavior:** - Creates worktree in `.worktrees/<branch-name>/` - Branches from `main` by default (or specify `from-branch`) - Copies all `.env*` files from main repo - Adds `.worktrees/` to `.gitignore` if missing - Symlinks the main repo's `.ruvector/` into the worktree if it exists (see [ruvector DB Sharing](#ruvector-db-sharing) below) - Fails safely if worktree already exists **Examples:** ```bash # Create worktree for feature branch worktree-manager.sh create feature-auth # Create worktree from specific branch worktree-manager.sh create hotfix-security develop ``` ### list / ls List all worktrees: ```bash worktree-manager.sh list worktree-manager.sh ls ``` **Output:** ``` Worktrees: main /home/user/repo (clean) feature-auth /home/user/repo/.worktrees/feature-auth (modified) pr-review-123 /home/user/repo/.worktrees/pr-review-123 (clean) ``` ### switch / go Switch to a worktree directory: ```bash worktree-manager.sh switch <name> worktree-manager.sh go <name> ``` **Note:** Prints `cd` command for shell evaluation: ```bash # Use with eval or source eval "$(worktree-manager.sh switch feature-auth)" # Or create shell function wtgo() { eval "$(worktree-manager.sh go "$1")"; } ``` ### copy-env Copy .env files to a worktree: ```bash worktree-manager.sh copy-env <name> ``` Copies all `.env*` files from main repo to specified worktree. Useful if you've updated environment configuration and need to sync. Also repairs a missing `.ruvector/` symlink for worktrees created before that feature existed (see below). ### ruvector DB Sharing When a Claude Code session runs inside a worktree, the ruvector MCP server resolves `${PWD}/.ruvector/` against the worktree path. Because `.ruvector/` is gitignored (`**/.ruvector/`), it is not present in a fresh worktree, so the MCP server and hook scripts would silently no-op (no recall, no session-start context, no post-edit indexing). `worktree-manager.sh create` injects an absolute symlink `${worktree}/.ruvector -> ${main_repo}/.ruvector` after the `.env` copy step, so MCP and hooks reach the project's shared DB. `worktree-manager.sh copy-env` applies the same fix retroactively. **Behavior:** - Skipped silently (with `info`) if the symlink already exists — idempotent. - Skipped (with `warning`) if a real `.ruvector/` directory already exists in the worktree — preserves the user's intentional isolated DB if they bypassed the manager script. - Skipped (with `warning`) if the main repo has no `.ruvector/` yet — no dangling symlinks. - Removed safely on `cleanup`: `[ -L ]` check, then `rm --` (no `-r`, no `-f`, no trailing slash). Cannot follow into the main repo's DB. **MCP-spawn-time qualifier:** `RUVECTOR_STORAGE_PATH` is evaluated when Claude Code spawns the MCP server process for a session. The symlink only helps when Claude Code is launched (or re-launched) **from inside the worktree directory**. A pre-existing session started in main that later `cd`s into a worktree continues to write to the main repo's DB directly. **Concurrent-write caveat:** When two Claude Code sessions run simultaneously (one in main, one in a worktree, or two worktrees), both MCP server processes write to the same shared DB without cross-process locking. Avoid running simultaneous sessions with active `hooks_remember` / `/ruvector:index` operations on the same project. See `plugins/yellow-ruvector/CLAUDE.md` Known Limitations. ### cleanup / clean Remove inactive worktrees: ```bash worktree-manager.sh cleanup worktree-manager.sh clean ``` **Behavior:** - Lists all worktrees - Prompts for confirmation - Removes worktrees one by one - Skips currently active worktree - Removes empty `.worktrees/` directory if all cleaned up ## When to Use ### Code Review (/flow:review) When reviewing a PR and you're not on the target branch: ```bash # Workflow offers worktree option /flow:review # Choose worktree option # Skill automatically creates worktree for PR branch # You can review without affecting your current work ``` ### Parallel Feature Development (/flow:work) When working on multiple features: ```bash # Start feature 1 /flow:work # Creates worktree for feature-1 # In another terminal, start feature 2 cd .worktrees/feature-2 /flow:work # Both features developed independently ``` ### Manual Worktree Management When you need direct control: ```bash # Create worktree worktree-manager.sh create experimental-refactor # Switch to it eval "$(worktree-manager.sh go experimental-refactor)" # List all worktree-manager.sh list # Clean up when done worktree-manager.sh cleanup ``` ## Workflow Examples ### Example 1: Code Review with Worktree ```bash # You're on feature-auth branch, working on authentication $ git branch --show-current feature-auth # PR needs review on different branch $ /flow:review pr-123 # Workflow detects branch mismatch, offers worktree option # Select "Create worktree for isolated review" # Worktree created automatically: # - Branch: pr-review-123 # - Location: .worktrees/pr-review-123/ # - .env files copied # - Ready for isolated review # After review, cleanup: $ worktree-manager.sh cleanup ``` ### Example 2: Parallel Feature Development ```bash # Main repo: working on feature A $ pwd /home/user/myproject # Need to quickly prototype feature B $ worktree-manager.sh create feature-b Created worktree: .worktrees/feature-b $ eval "$(worktree-manager.sh go feature-b)" $ pwd /home/user/myproject/.worktrees/feature-b # Work on feature B $ nvim src/feature-b.ts $ git commit -m "feat: prototype feature B" # Switch back to main repo $ cd /home/user/myproject # Both features isolated, no stashing needed ``` ## Integration with Workflows ### /flow:review Integration When `/flow:review` detects you're not on the target branch: 1. Offers worktree option 2. Calls this skill: `/git-worktree create pr-review-<number>` 3. Switches to worktree 4. Proceeds with review in isolation ### /flow:work Integration When starting feature work: 1. Asks if you want isolated environment 2. Calls: `/git-worktree create <branch-name>` 3. Copies .env files automatically 4. Starts feature work in worktree ## Auto-Trust mise/direnv After Worktree Creation If your project uses [mise](https://mise.jdx.dev/) (`.mise.toml`, `.tool-versions`) or [direnv](https://direnv.net/) (`.envrc`), the new worktree directory starts **untrusted** — the tool refuses to load configs until the user explicitly opts in. This breaks the principle of least surprise: you create a worktree, `cd` in, and tooling silently fails to load. The fix is to auto-trust the new worktree directory at creation time. The manager script handles common cases; the patterns below show how to do it explicitly when needed (e.g., a CI runner creating a throwaway worktree). **mise:** ```bash # After: worktree-manager.sh create feature-auth cd .worktrees/feature-auth # Trust the worktree's mise config mise trust 2>/dev/null || true # Or trust without cd (mise --cwd is supported on recent versions) mise --cwd .worktrees/feature-auth trust 2>/dev/null || true ``` **direnv:** ```bash # direnv requires both `allow` and a load on entry cd .worktrees/feature-auth direnv allow 2>/dev/null || true # Or non-interactively direnv allow .worktrees/feature-auth 2>/dev/null || true ``` **Suppress on absent tools:** `2>/dev/null || true` keeps the trust step quiet when neither mise nor direnv is installed. Do **not** drop the redirect — without it, missing-binary stderr leaks into worktree creation logs. **Why this is per-worktree:** mise and direnv key trust on the absolute path of the directory containing the config. A worktree at `.worktrees/feature-auth/` is a different absolute path from the main repo, even when the `.mise.toml` content is identical. ## `.git`-Is-a-File Detection (Submodule and Worktree Cases) In a normal repo, `.git` is a directory. But in two important cases it is a **plain file** containing a `gitdir: <path>` pointer: 1. **Inside a submodule:** the submodule's `.git` is a file pointing at `<superproject>/.git/modules/<submodule-name>`. 2. **Inside an existing worktree:** the worktree's `.git` is a file pointing at `<main-repo>/.git/worktrees/<worktree-name>`. Naive scripts that do `[ -d .git ]` to detect a git repo will misclassify both cases as "not a git repo" and fail in confusing ways. **Detection pattern:** ```bash # Correct: handles both directory and file forms is_git_repo() { [ -e .git ] && git rev-parse --git-dir >/dev/null 2>&1 } # Or check the type explicitly git_dir_kind() { if [ -d .git ]; then echo "directory" # main repo elif [ -f .git ]; then # Read the gitdir pointer to know whether it's a worktree or submodule case "$(head -n 1 .git)" in "gitdir: "*/.git/worktrees/*) echo "worktree" ;; "gitdir: "*/.git/modules/*) echo "submodule" ;; "gitdir: "*) echo "linked" ;; *) echo "unknown" ;; esac else echo "none" fi } ``` **Worktree creation inside a submodule:** Avoid creating a worktree **inside** a directory whose `.git` is the submodule pointer file — `git worktree add` from a submodule treats the submodule's gitdir as the parent, which lands the new worktree under `<superproject>/.git/modules/<sub>/worktrees/`, far from where users expect. Always run worktree commands from the **superproject root**, or explicitly pass `-C <superproject-root>` to `git worktree add`. **Why this matters for the manager script:** the helper resolves `get_repo_root` via `git rev-parse --show-toplevel`, which already returns the correct top-level whether `.git` is a file or directory. But any caller that pre-checks `[ -d .git ]` before invoking the helper will short-circuit incorrectly. Use `git rev-parse --git-dir` (which handles both forms) instead. ## Troubleshooting See [troubleshooting.md](troubleshooting.md) for common issues and solutions. ## Design Principles ### KISS (Keep It Simple, Stupid) - One script does everything - Clear command names - No complex configuration - Fails fast with clear errors ### Opinionated Defaults - Worktrees always in `.worktrees/` directory - Always branch from `main` (unless specified) - Always copy .env files - Branch name = worktree name (1:1 mapping) ### Safety First - Never overwrites existing worktrees - Requires confirmation for cleanup - Adds .gitignore automatically - Color-coded warnings and errors ## Reference **Git worktree documentation:** ```bash man git-worktree ``` **Common git worktree commands:** ```bash git worktree list # List worktrees git worktree remove <path> # Remove specific worktree git worktree prune # Clean up stale references ``` **But use the manager script instead** for consistent, safe operations.