auto-build/plugin/commands/worktree.md

description: Manage git worktrees for feature isolation argument-hint: [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

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 .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 .auto-build/scripts/worktree-list.sh

switch

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 .auto-build/scripts/worktree-cleanup.sh [feature-name]

Registry Format

.auto-build-data/worktrees/worktree-registry.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