refactor(ce-worktree): trim to creation-only and fix latent bugs (#631)
This commit is contained in:
Trevin Chow
@@ -1,310 +1,77 @@
|
||||
---
|
||||
name: ce-worktree
|
||||
description: This skill manages Git worktrees for isolated parallel development. It handles creating, listing, switching, and cleaning up worktrees with a simple interactive interface, following KISS principles.
|
||||
description: Create an isolated git worktree for parallel feature work or PR review. Use when starting work that should not disturb the current checkout, or when `ce-work` or `ce-code-review` offers a worktree option.
|
||||
---
|
||||
|
||||
# Git Worktree Manager
|
||||
# Worktree Creation
|
||||
|
||||
This skill provides a unified interface for managing Git worktrees across your development workflow. Whether you're reviewing PRs in isolation or working on features in parallel, this skill handles all the complexity.
|
||||
Create a worktree under `.worktrees/<branch>` with branch-specific setup that `git worktree add` alone does not handle:
|
||||
|
||||
## What This Skill Does
|
||||
- Copies `.env`, `.env.local`, `.env.test`, etc. from the main repo (skips `.env.example`)
|
||||
- Trusts `mise`/`direnv` configs, with branch-aware safety rules so review branches do not auto-grant trust to untrusted `.envrc` content
|
||||
- Adds `.worktrees` to `.gitignore` if not already ignored
|
||||
- Does not modify the main repo checkout — `from-branch` is fetched, not checked out
|
||||
|
||||
- **Create worktrees** from main branch with clear branch names
|
||||
- **List worktrees** with current status
|
||||
- **Switch between worktrees** for parallel work
|
||||
- **Clean up completed worktrees** automatically
|
||||
- **Interactive confirmations** at each step
|
||||
- **Automatic .gitignore management** for worktree directory
|
||||
- **Automatic .env file copying** from main repo to new worktrees
|
||||
- **Automatic dev tool trusting** for mise and direnv configs with review-safe guardrails
|
||||
|
||||
## CRITICAL: Always Use the Manager Script
|
||||
|
||||
**NEVER call `git worktree add` directly.** Always use the `worktree-manager.sh` script.
|
||||
|
||||
The script handles critical setup that raw git commands don't:
|
||||
1. Copies `.env`, `.env.local`, `.env.test`, etc. from main repo
|
||||
2. Trusts dev tool configs with branch-aware safety rules:
|
||||
- mise: auto-trust only when unchanged from a trusted baseline branch
|
||||
- direnv: auto-allow only for trusted base branches; review worktrees stay manual
|
||||
3. Ensures `.worktrees` is in `.gitignore`
|
||||
4. Creates consistent directory structure
|
||||
## Creating a worktree
|
||||
|
||||
```bash
|
||||
# ✅ CORRECT - Always use the script
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/ce-worktree/scripts/worktree-manager.sh create feature-name
|
||||
|
||||
# ❌ WRONG - Never do this directly
|
||||
git worktree add .worktrees/feature-name -b feature-name main
|
||||
bash scripts/worktree-manager.sh create <branch-name> [from-branch]
|
||||
```
|
||||
|
||||
## When to Use This Skill
|
||||
Defaults:
|
||||
- `from-branch` defaults to origin's default branch (or `main` if that cannot be resolved)
|
||||
- The new branch is created at `origin/<from-branch>` (or the local ref if the remote is unavailable)
|
||||
|
||||
Use this skill in these scenarios:
|
||||
|
||||
1. **Code Review (`/ce-code-review`)**: If NOT already on the target branch (PR branch or requested branch), offer worktree for isolated review
|
||||
2. **Feature Work (`/ce-work`)**: Always ask if user wants parallel worktree or live branch work
|
||||
3. **Parallel Development**: When working on multiple features simultaneously
|
||||
4. **Cleanup**: After completing work in a worktree
|
||||
|
||||
## How to Use
|
||||
|
||||
### In Claude Code Workflows
|
||||
|
||||
The skill is automatically called from `/ce-code-review` and `/ce-work` commands:
|
||||
|
||||
```
|
||||
# For review: offers worktree if not on PR branch
|
||||
# For work: always asks - new branch or worktree?
|
||||
Examples:
|
||||
```bash
|
||||
bash scripts/worktree-manager.sh create feat/login
|
||||
bash scripts/worktree-manager.sh create fix/email-validation develop
|
||||
```
|
||||
|
||||
### Manual Usage
|
||||
After creation, switch to the worktree with `cd .worktrees/<branch-name>`.
|
||||
|
||||
You can also invoke the skill directly from bash:
|
||||
## Other worktree operations
|
||||
|
||||
Use `git` directly — no wrapper is needed and none is provided:
|
||||
|
||||
```bash
|
||||
# Create a new worktree (copies .env files automatically)
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/ce-worktree/scripts/worktree-manager.sh create feature-login
|
||||
|
||||
# List all worktrees
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/ce-worktree/scripts/worktree-manager.sh list
|
||||
|
||||
# Switch to a worktree
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/ce-worktree/scripts/worktree-manager.sh switch feature-login
|
||||
|
||||
# Copy .env files to an existing worktree (if they weren't copied)
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/ce-worktree/scripts/worktree-manager.sh copy-env feature-login
|
||||
|
||||
# Clean up completed worktrees
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/ce-worktree/scripts/worktree-manager.sh cleanup
|
||||
git worktree list # list worktrees
|
||||
git worktree remove .worktrees/<branch> # remove a worktree
|
||||
cd .worktrees/<branch> # switch to a worktree
|
||||
cd "$(git rev-parse --show-toplevel)" # return to main checkout
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
### `create <branch-name> [from-branch]`
|
||||
|
||||
Creates a new worktree with the given branch name.
|
||||
|
||||
**Options:**
|
||||
- `branch-name` (required): The name for the new branch and worktree
|
||||
- `from-branch` (optional): Base branch to create from (defaults to `main`)
|
||||
|
||||
**Example:**
|
||||
To copy `.env*` files into an existing worktree created without them, run this from the main repo (not from inside the worktree, since branch names often contain slashes like `feat/login`):
|
||||
```bash
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/ce-worktree/scripts/worktree-manager.sh create feature-login
|
||||
cp .env* .worktrees/<branch>/
|
||||
```
|
||||
|
||||
**What happens:**
|
||||
1. Checks if worktree already exists
|
||||
2. Updates the base branch from remote
|
||||
3. Creates new worktree and branch
|
||||
4. **Copies all .env files from main repo** (.env, .env.local, .env.test, etc.)
|
||||
5. **Trusts dev tool configs** with branch-aware safety rules:
|
||||
- trusted bases (`main`, `develop`, `dev`, `trunk`, `staging`, `release/*`) compare against themselves
|
||||
- other branches compare against the default branch
|
||||
- direnv auto-allow is skipped on non-trusted bases because `.envrc` can source unchecked files
|
||||
6. Shows path for cd-ing to the worktree
|
||||
## Dev tool trust behavior
|
||||
|
||||
### `list` or `ls`
|
||||
When mise or direnv configs are present, the script attempts to trust them so hooks and scripts do not block on interactive prompts. Trust is baseline-checked against a reference branch:
|
||||
|
||||
Lists all available worktrees with their branches and current status.
|
||||
- **Trusted base branches** (`main`, `develop`, `dev`, `trunk`, `staging`, `release/*`): the new worktree's configs are compared against that branch; unchanged configs are auto-trusted. `direnv allow` is permitted.
|
||||
- **Other branches** (feature branches, PR review branches): configs are compared against the default branch; `direnv allow` is skipped regardless, because `.envrc` can source files that direnv does not validate.
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/ce-worktree/scripts/worktree-manager.sh list
|
||||
```
|
||||
Modified configs are never auto-trusted. The script prints the manual trust command to run after review.
|
||||
|
||||
**Output shows:**
|
||||
- Worktree name
|
||||
- Branch name
|
||||
- Which is current (marked with ✓)
|
||||
- Main repo status
|
||||
## When to create a worktree
|
||||
|
||||
### `switch <name>` or `go <name>`
|
||||
Create a worktree when:
|
||||
- Reviewing a PR while keeping the main checkout free for other work
|
||||
- Running multiple features in parallel without branch-switching overhead
|
||||
- Keeping the default branch free of in-progress state
|
||||
|
||||
Switches to an existing worktree and cd's into it.
|
||||
Do not create a worktree for single-task work that can happen on a branch in the main checkout.
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/ce-worktree/scripts/worktree-manager.sh switch feature-login
|
||||
```
|
||||
## Integration
|
||||
|
||||
**Optional:**
|
||||
- If name not provided, lists available worktrees and prompts for selection
|
||||
|
||||
### `cleanup` or `clean`
|
||||
|
||||
Interactively cleans up inactive worktrees with confirmation.
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/ce-worktree/scripts/worktree-manager.sh cleanup
|
||||
```
|
||||
|
||||
**What happens:**
|
||||
1. Lists all inactive worktrees
|
||||
2. Asks for confirmation
|
||||
3. Removes selected worktrees
|
||||
4. Cleans up empty directories
|
||||
|
||||
## Workflow Examples
|
||||
|
||||
### Code Review with Worktree
|
||||
|
||||
```bash
|
||||
# Claude Code recognizes you're not on the PR branch
|
||||
# Offers: "Use worktree for isolated review? (y/n)"
|
||||
|
||||
# You respond: yes
|
||||
# Script runs (copies .env files automatically):
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/ce-worktree/scripts/worktree-manager.sh create pr-123-feature-name
|
||||
|
||||
# You're now in isolated worktree for review with all env vars
|
||||
cd .worktrees/pr-123-feature-name
|
||||
|
||||
# After review, return to main:
|
||||
cd ../..
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/ce-worktree/scripts/worktree-manager.sh cleanup
|
||||
```
|
||||
|
||||
### Parallel Feature Development
|
||||
|
||||
```bash
|
||||
# For first feature (copies .env files):
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/ce-worktree/scripts/worktree-manager.sh create feature-login
|
||||
|
||||
# Later, start second feature (also copies .env files):
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/ce-worktree/scripts/worktree-manager.sh create feature-notifications
|
||||
|
||||
# List what you have:
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/ce-worktree/scripts/worktree-manager.sh list
|
||||
|
||||
# Switch between them as needed:
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/ce-worktree/scripts/worktree-manager.sh switch feature-login
|
||||
|
||||
# Return to main and cleanup when done:
|
||||
cd .
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/ce-worktree/scripts/worktree-manager.sh cleanup
|
||||
```
|
||||
|
||||
## Key Design Principles
|
||||
|
||||
### KISS (Keep It Simple, Stupid)
|
||||
|
||||
- **One manager script** handles all worktree operations
|
||||
- **Simple commands** with sensible defaults
|
||||
- **Interactive prompts** prevent accidental operations
|
||||
- **Clear naming** using branch names directly
|
||||
|
||||
### Opinionated Defaults
|
||||
|
||||
- Worktrees always created from **main** (unless specified)
|
||||
- Worktrees stored in **.worktrees/** directory
|
||||
- Branch name becomes worktree name
|
||||
- **.gitignore** automatically managed
|
||||
|
||||
### Safety First
|
||||
|
||||
- **Confirms before creating** worktrees
|
||||
- **Confirms before cleanup** to prevent accidental removal
|
||||
- **Won't remove current worktree**
|
||||
- **Clear error messages** for issues
|
||||
|
||||
## Integration with Workflows
|
||||
|
||||
### `/ce-code-review`
|
||||
|
||||
Instead of always creating a worktree:
|
||||
|
||||
```
|
||||
1. Check current branch
|
||||
2. If ALREADY on target branch (PR branch or requested branch) → stay there, no worktree needed
|
||||
3. If DIFFERENT branch than the review target → offer worktree:
|
||||
"Use worktree for isolated review? (y/n)"
|
||||
- yes → call ce-worktree skill
|
||||
- no → proceed with PR diff on current branch
|
||||
```
|
||||
|
||||
### `/ce-work`
|
||||
|
||||
Always offer choice:
|
||||
|
||||
```
|
||||
1. Ask: "How do you want to work?
|
||||
1. New branch on current worktree (live work)
|
||||
2. Worktree (parallel work)"
|
||||
|
||||
2. If choice 1 → create new branch normally
|
||||
3. If choice 2 → call ce-worktree skill to create from main
|
||||
```
|
||||
`ce-work` and `ce-code-review` offer this skill as an option. When the user selects "worktree" in those flows, invoke `bash scripts/worktree-manager.sh create <branch>` with a meaningful branch name derived from the work description (e.g., `feat/crowd-sniff`, `fix/email-validation`). Avoid auto-generated names like `worktree-jolly-beaming-raven` that obscure the work.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Worktree already exists"
|
||||
**"Worktree already exists"**: the path is already in use. Either switch to it (`cd .worktrees/<branch>`) or remove it (`git worktree remove .worktrees/<branch>`) before recreating.
|
||||
|
||||
If you see this, the script will ask if you want to switch to it instead.
|
||||
**"Cannot remove worktree: it is the current worktree"**: `cd` out of the worktree first, then `git worktree remove`.
|
||||
|
||||
### "Cannot remove worktree: it is the current worktree"
|
||||
|
||||
Switch out of the worktree first (to main repo), then cleanup:
|
||||
|
||||
```bash
|
||||
cd $(git rev-parse --show-toplevel)
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/ce-worktree/scripts/worktree-manager.sh cleanup
|
||||
```
|
||||
|
||||
### Lost in a worktree?
|
||||
|
||||
See where you are:
|
||||
|
||||
```bash
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/ce-worktree/scripts/worktree-manager.sh list
|
||||
```
|
||||
|
||||
### .env files missing in worktree?
|
||||
|
||||
If a worktree was created without .env files (e.g., via raw `git worktree add`), copy them:
|
||||
|
||||
```bash
|
||||
bash ${CLAUDE_PLUGIN_ROOT}/skills/ce-worktree/scripts/worktree-manager.sh copy-env feature-name
|
||||
```
|
||||
|
||||
Navigate back to main:
|
||||
|
||||
```bash
|
||||
cd $(git rev-parse --show-toplevel)
|
||||
```
|
||||
|
||||
## Technical Details
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
.worktrees/
|
||||
├── feature-login/ # Worktree 1
|
||||
│ ├── .git
|
||||
│ ├── app/
|
||||
│ └── ...
|
||||
├── feature-notifications/ # Worktree 2
|
||||
│ ├── .git
|
||||
│ ├── app/
|
||||
│ └── ...
|
||||
└── ...
|
||||
|
||||
.gitignore (updated to include .worktrees)
|
||||
```
|
||||
|
||||
### How It Works
|
||||
|
||||
- Uses `git worktree add` for isolated environments
|
||||
- Each worktree has its own branch
|
||||
- Changes in one worktree don't affect others
|
||||
- Share git history with main repo
|
||||
- Can push from any worktree
|
||||
|
||||
### Performance
|
||||
|
||||
- Worktrees are lightweight (just file system links)
|
||||
- No repository duplication
|
||||
- Shared git objects for efficiency
|
||||
- Much faster than cloning or stashing/switching
|
||||
**Dev tool trust was skipped**: the script prints the manual command. Review the config diff (`git diff <base-ref> -- .envrc`), then run the printed command from the worktree directory.
|
||||
|
||||
Reference in New Issue
Block a user