147 lines
3.7 KiB
Markdown
147 lines
3.7 KiB
Markdown
---
|
|
description: Manage git worktrees for feature isolation
|
|
argument-hint: <action> [name] - Actions: create, list, switch, cleanup
|
|
---
|
|
|
|
# Git Worktree Management
|
|
|
|
Manage isolated git worktrees for feature development. Worktrees provide complete isolation between features, preventing conflicts during parallel development.
|
|
|
|
## Actions
|
|
|
|
### create <feature-name>
|
|
|
|
Create a new isolated worktree for a feature.
|
|
|
|
**Workflow:**
|
|
1. Validate feature name provided
|
|
2. Determine project name from current directory
|
|
3. Create branch: `feature/ab-{feature-name}`
|
|
4. Create worktree at: `../ab-worktrees/{project}-{feature-name}/`
|
|
5. Register in `.auto-build-data/worktrees/worktree-registry.json`
|
|
6. Display success message with path
|
|
|
|
**Command:**
|
|
```bash
|
|
bash .auto-build/scripts/worktree-create.sh {feature-name}
|
|
```
|
|
|
|
**Output:**
|
|
```
|
|
Created worktree for: feature-name
|
|
Branch: feature/ab-feature-name
|
|
Path: ../ab-worktrees/project-feature-name/
|
|
|
|
To work in this worktree:
|
|
cd ../ab-worktrees/project-feature-name/
|
|
```
|
|
|
|
### list
|
|
|
|
List all active worktrees.
|
|
|
|
**Workflow:**
|
|
1. Read `.auto-build-data/worktrees/worktree-registry.json`
|
|
2. Verify each worktree still exists (git worktree list)
|
|
3. Display table:
|
|
```
|
|
Active Worktrees:
|
|
| Feature | Branch | Path | Created |
|
|
|---------|--------|------|---------|
|
|
| user-dashboard | feature/ab-user-dashboard | ../ab-worktrees/project-user-dashboard/ | 2h ago |
|
|
```
|
|
|
|
**Command:**
|
|
```bash
|
|
bash .auto-build/scripts/worktree-list.sh
|
|
```
|
|
|
|
### switch <feature-name>
|
|
|
|
Provide instructions to switch to a worktree.
|
|
|
|
**Workflow:**
|
|
1. Look up worktree path from registry
|
|
2. Verify worktree exists
|
|
3. Display switch instructions:
|
|
```
|
|
To switch to feature-name worktree:
|
|
|
|
cd ../ab-worktrees/project-feature-name/
|
|
|
|
Or start a new Claude Code session in that directory.
|
|
```
|
|
|
|
**Note:** Claude Code sessions are directory-bound, so actual switching requires changing the working directory.
|
|
|
|
### cleanup [feature-name]
|
|
|
|
Remove completed worktrees.
|
|
|
|
**Workflow:**
|
|
If feature-name provided:
|
|
1. Look up worktree in registry
|
|
2. Check if branch is merged to main
|
|
3. If merged or user confirms: Remove worktree and branch
|
|
4. Update registry
|
|
|
|
If no feature-name:
|
|
1. List all worktrees
|
|
2. Check which branches are merged
|
|
3. Offer to cleanup merged ones:
|
|
```
|
|
Found 2 merged worktrees:
|
|
- old-feature (merged 3 days ago)
|
|
- bug-fix (merged 1 week ago)
|
|
|
|
Remove these? [Yes] [Select] [No]
|
|
```
|
|
|
|
**Command:**
|
|
```bash
|
|
bash .auto-build/scripts/worktree-cleanup.sh [feature-name]
|
|
```
|
|
|
|
## Registry Format
|
|
|
|
`.auto-build-data/worktrees/worktree-registry.json`:
|
|
```json
|
|
{
|
|
"worktrees": [
|
|
{
|
|
"name": "user-dashboard",
|
|
"branch": "feature/ab-user-dashboard",
|
|
"path": "../ab-worktrees/project-user-dashboard/",
|
|
"created": "2025-01-15T10:30:00Z",
|
|
"status": "active",
|
|
"spec": ".auto-build-data/specs/user-dashboard/"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Worktree Location
|
|
|
|
Worktrees are created **outside** the project directory to avoid:
|
|
- Nested git repository issues
|
|
- IDE confusion
|
|
- Accidental commits from wrong directory
|
|
|
|
Structure:
|
|
```
|
|
/projects/
|
|
├── my-project/ # Main project
|
|
│ ├── .auto-build/
|
|
│ └── .auto-build-data/
|
|
└── ab-worktrees/ # Worktrees directory
|
|
├── my-project-user-dashboard/
|
|
└── my-project-api-refactor/
|
|
```
|
|
|
|
## Error Cases
|
|
|
|
- **Branch already exists**: Ask to use existing or create new
|
|
- **Worktree path exists**: Ask to reuse or choose different path
|
|
- **Not a git repository**: Inform user and abort
|
|
- **Uncommitted changes**: Warn user before creating worktree
|