ace-git-worktree 0.19.0

data/handbook/workflow-instructions/git/worktree-manage.wf.md

@@ -0,0 +1,384 @@
+---
+doc-type: workflow
+title: Manage Worktree Workflow Instruction
+purpose: Documentation for ace-git-worktree/handbook/workflow-instructions/git/worktree-manage.wf.md
+ace-docs:
+  last-updated: 2026-02-22
+  last-checked: 2026-03-21
+---
+
+# Manage Worktree Workflow Instruction
+
+## Purpose
+
+Manage existing git worktrees including listing, switching between, removing, and cleaning up worktrees. This workflow provides comprehensive worktree lifecycle management.
+
+## Prerequisites
+
+- Existing worktrees in the repository
+- ace-git-worktree installed and configured
+- Appropriate permissions for worktree operations
+
+## Variables
+
+$identifier: Worktree identifier (task ID, branch name, directory, or path)
+$action: Management action (list, switch, remove, prune)
+
+## Instructions
+
+### 1. List Worktrees
+
+**Basic Listing:**
+
+```bash
+# List all worktrees in table format
+ace-git-worktree list
+
+# List with task associations
+ace-git-worktree list --show-tasks
+
+# List in different formats
+ace-git-worktree list --format json
+ace-git-worktree list --format simple
+```
+
+**Filtered Listing:**
+
+```bash
+# List only task-associated worktrees
+ace-git-worktree list --task-associated
+
+# List only non-task worktrees
+ace-git-worktree list --no-task-associated
+
+# List only usable worktrees
+ace-git-worktree list --usable
+
+# Search by branch pattern
+ace-git-worktree list --search auth
+```
+
+### 2. Switch Between Worktrees
+
+**By Various Identifiers:**
+
+```bash
+# Switch by task ID
+cd $(ace-git-worktree switch 081)
+
+# Switch by branch name
+cd $(ace-git-worktree switch feature-branch)
+
+# Switch by directory name
+cd $(ace-git-worktree switch task.081)
+
+# Switch by full path
+cd $(ace-git-worktree switch /path/to/worktree)
+```
+
+**Alternative Navigation:**
+
+```bash
+# Get worktree path and store in variable
+WORKTREE_PATH=$(ace-git-worktree switch 081)
+echo "Worktree path: $WORKTREE_PATH"
+cd "$WORKTREE_PATH"
+
+# List available worktrees first
+ace-git-worktree switch --list
+```
+
+### 3. Remove Worktrees
+
+**Task-Aware Removal:**
+
+```bash
+# Remove task worktree
+ace-git-worktree remove --task 081
+
+# Force remove (with uncommitted changes)
+ace-git-worktree remove --task 081 --force
+
+# Keep directory (remove git tracking only)
+ace-git-worktree remove --task 081 --keep-directory
+```
+
+**Traditional Removal:**
+
+```bash
+# Remove by branch name
+ace-git-worktree remove feature-branch
+
+# Remove by identifier
+ace-git-worktree remove task.081
+
+# Remove with dry-run preview
+ace-git-worktree remove --task 081 --dry-run
+```
+
+### 4. Clean Up Deleted Worktrees
+
+**Basic Pruning:**
+
+```bash
+# Prune git metadata for deleted worktrees
+ace-git-worktree prune
+
+# Remove orphaned directories too
+ace-git-worktree prune --cleanup-directories
+
+# Dry run to preview changes
+ace-git-worktree prune --dry-run
+
+# Verbose output
+ace-git-worktree prune --verbose
+```
+
+### 5. Configuration Management
+
+**Show Configuration:**
+
+```bash
+# Show current configuration
+ace-git-worktree config
+
+# Validate configuration
+ace-git-worktree config --validate
+
+# Show configuration file locations
+ace-git-worktree config --files
+
+# Show detailed configuration
+ace-git-worktree config --show
+```
+
+## Advanced Operations
+
+### Bulk Management
+
+```bash
+# Get worktree status for all tasks
+ace-git-worktree list --format json --show-tasks | jq '.worktrees'
+
+# Count worktrees by type
+ace-git-worktree list --show-tasks | grep "Task" | wc -l
+
+# Find worktrees with specific patterns
+ace-git-worktree list --search "bug" --format simple
+```
+
+### Search and Filter
+
+```bash
+# Search worktrees by multiple criteria
+ace-git-worktree list --search auth --task-associated --format json
+
+# Filter by usability
+ace-git-worktree list --usable --format simple
+
+# Show only worktrees with branches
+ace-git-worktree list | grep -v "bare\|detached"
+```
+
+### Status and Monitoring
+
+```bash
+# Get comprehensive status
+ace-git-worktree list --show-tasks --format json
+
+# Check specific worktree
+ace-git-worktree switch 081 --verbose
+
+# Validate setup
+ace-git-worktree config --validate
+```
+
+## Automation and Scripting
+
+### JSON Output for Scripts
+
+```bash
+# Get all worktrees as JSON
+WORKTREES=$(ace-git-worktree list --format json --show-tasks)
+
+# Extract specific information
+echo "$WORKTREES" | jq '.worktrees[] | select(.task_id == "081")'
+echo "$WORKTREES" | jq '.worktrees[] | .path'
+echo "$WORKTREES" | jq '.worktrees | length'
+```
+
+### Batch Operations
+
+```bash
+# Remove multiple worktrees
+for task_id in 081 082 083; do
+  ace-git-worktree remove --task "$task_id" --force
+done
+
+# Switch between worktrees
+WORKTREES=("081" "082" "083")
+for task_id in "${WORKTREES[@]}"; do
+  echo "Switching to task $task_id"
+  cd "$(ace-git-worktree switch "$task_id")"
+  # Do work in each worktree...
+  cd ..
+done
+```
+
+### Conditional Operations
+
+```bash
+# Only remove if worktree exists
+if ace-git-worktree switch 081 --help > /dev/null 2>&1; then
+  ace-git-worktree remove --task 081
+fi
+
+# Check if worktrees need cleanup
+if ace-git-worktree prune --dry-run | grep -q "Pruning"; then
+  ace-git-worktree prune --cleanup-directories
+fi
+```
+
+## Error Recovery
+
+### Common Issues
+
+**Worktree Not Found:**
+
+```bash
+# List available worktrees
+ace-git-worktree list
+
+# Search for similar identifiers
+ace-git-worktree list --search "081"
+
+# Try different identifier formats
+ace-git-worktree switch task.081
+ace-git-worktree switch 081-fix-auth
+```
+
+**Permission Issues:**
+
+```bash
+# Check worktree directory permissions
+ls -la .ace-wt/
+
+# Fix permissions if needed
+chmod -R 755 .ace-wt/
+```
+
+**Git Repository Issues:**
+
+```bash
+# Check git status in worktree
+cd $(ace-git-worktree switch 081)
+git status
+
+# Fix git issues if needed
+git checkout main
+git branch -D 081-fix-auth  # if needed
+```
+
+### Safety Checks
+
+```bash
+# Check removal safety before removing
+ace-git-worktree switch 081 --help > /dev/null
+if [ $? -eq 0 ]; then
+  echo "Worktree exists, proceeding with removal"
+  ace-git-worktree remove --task 081 --dry-run
+else
+  echo "Worktree not found, skipping removal"
+fi
+
+# Check for uncommitted changes
+cd $(ace-git-worktree switch 081)
+if [ -n "$(git status --porcelain)" ]; then
+  echo "Worktree has uncommitted changes"
+  git status
+else
+  echo "Worktree is clean"
+fi
+```
+
+## Integration with Development Workflow
+
+### Daily Workflow Management
+
+```bash
+#!/bin/bash
+# Daily worktree management script
+
+# 1. Check current worktree status
+echo "=== Current Worktree Status ==="
+ace-git-worktree list --show-tasks --format simple
+
+# 2. Clean up if needed
+echo "=== Cleanup Check ==="
+if ace-git-worktree prune --dry-run | grep -q "Pruning"; then
+  echo "Cleaning up deleted worktrees..."
+  ace-git-worktree prune --cleanup-directories
+else
+  echo "No cleanup needed"
+fi
+
+# 3. Show configuration
+echo "=== Configuration ==="
+ace-git-worktree config --validate
+```
+
+### Task Completion Workflow
+
+```bash
+#!/bin/bash
+# Complete task and cleanup worktree
+
+TASK_ID="$1"
+if [ -z "$TASK_ID" ]; then
+  echo "Usage: $0 <task-id>"
+  exit 1
+fi
+
+# 1. Switch to worktree and check status
+echo "Checking worktree for task $TASK_ID..."
+WORKTREE_PATH=$(ace-git-worktree switch "$TASK_ID")
+cd "$WORKTREE_PATH"
+
+# 2. Check for uncommitted changes
+if [ -n "$(git status --porcelain)" ]; then
+  echo "WARNING: Worktree has uncommitted changes"
+  git status
+  read -p "Continue with removal? (y/N): " -n 1 -r
+  echo
+  if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+    echo "Aborting removal"
+    exit 1
+  fi
+fi
+
+# 3. Return to main and remove worktree
+cd ..
+echo "Removing worktree for task $TASK_ID..."
+ace-git-worktree remove --task "$TASK_ID"
+
+# 4. Clean up if needed
+ace-git-worktree prune
+```
+
+## Success Criteria
+
+- Worktrees listed with correct information
+- Successfully switched to target worktree
+- Worktrees removed cleanly with proper cleanup
+- Deleted worktree metadata pruned from git
+- Configuration validated and accessible
+- Automation scripts work correctly
+- Error conditions handled gracefully
+
+## Response Template
+
+**Action:** [list/switch/remove/prune/config]
+**Worktree(s):** [Count and type of worktrees affected]
+**Location(s):** [Paths involved]
+**Status:** [Current state after operation]
+**Next Steps:** [Recommended follow-up actions]

data/handbook/workflow-instructions/git/worktree.wf.md

@@ -0,0 +1,224 @@
+---
+doc-type: workflow
+title: Worktree Workflow
+purpose: worktree workflow instruction
+ace-docs:
+  last-updated: 2026-03-06
+  last-checked: 2026-03-21
+---
+
+# Worktree Workflow
+
+## Purpose
+
+Manage git worktrees with task-aware automation and traditional operations using ace-git-worktree CLI.
+
+## Primary Tool: ace-git-worktree
+
+All operations use the **ace-git-worktree** command.
+
+## Task-Aware Operations
+
+### Create Worktree for Task
+```bash
+# Create worktree for task (recommended)
+ace-git-worktree create --task 081
+
+# With dry-run preview
+ace-git-worktree create --task 081 --dry-run
+
+# Skip automatic operations
+ace-git-worktree create --task 081 --no-commit --no-status-update
+```
+
+### Switch to Task Worktree
+```bash
+# Switch by task ID
+ace-git-worktree switch 081
+
+# Verbose output
+ace-git-worktree switch 081 --verbose
+```
+
+### Remove Task Worktree
+```bash
+# Remove task worktree
+ace-git-worktree remove --task 081
+
+# Preview removal
+ace-git-worktree remove --task 081 --dry-run
+
+# Force removal with uncommitted changes
+ace-git-worktree remove --task 081 --force
+```
+
+## Traditional Worktree Operations
+
+### Create Worktree for Branch
+```bash
+# Create for branch
+ace-git-worktree create feature-branch
+
+# Custom path
+ace-git-worktree create feature-branch --path ../custom-path
+
+# Without mise trust
+ace-git-worktree create feature-branch --no-mise-trust
+```
+
+### List Worktrees
+```bash
+# List all worktrees
+ace-git-worktree list
+
+# Show task associations
+ace-git-worktree list --show-tasks
+
+# Filter by task association
+ace-git-worktree list --task-associated
+
+# Output formats
+ace-git-worktree list --format json
+ace-git-worktree list --format table
+ace-git-worktree list --format simple
+
+# Search/filter
+ace-git-worktree list --search "081"
+```
+
+### Switch Worktree
+```bash
+# By branch name
+ace-git-worktree switch feature-branch
+
+# By directory name
+ace-git-worktree switch task.081
+
+# By path
+ace-git-worktree switch ../as-task.081
+```
+
+### Remove Worktree
+```bash
+# By branch name
+ace-git-worktree remove feature-branch
+
+# Keep directory
+ace-git-worktree remove feature-branch --keep-directory
+
+# Force removal
+ace-git-worktree remove feature-branch --force
+```
+
+## Cleanup Operations
+
+### Prune Deleted Worktrees
+```bash
+# Prune git worktree metadata
+ace-git-worktree prune
+
+# Also remove orphaned directories
+ace-git-worktree prune --cleanup-directories
+
+# Dry-run preview
+ace-git-worktree prune --cleanup-directories --dry-run
+
+# Verbose output
+ace-git-worktree prune --verbose
+```
+
+## Configuration
+
+### Show Configuration
+```bash
+# Show current configuration
+ace-git-worktree config --show
+
+# Validate configuration
+ace-git-worktree config --validate
+
+# Show configuration file locations
+ace-git-worktree config --files
+```
+
+### Configuration File
+
+Configuration from `.ace/git/worktree.yml`:
+
+```yaml
+git:
+  worktree:
+    root_path: ".ace-wt"
+    mise_trust_auto: true
+    task:
+      directory_format: "task.{id}"
+      branch_format: "{id}-{slug}"
+      auto_mark_in_progress: true
+      auto_commit_task: true
+      add_worktree_metadata: true
+```
+
+## Command Reference
+
+### create
+- `--task <task-id>`: Create worktree for specific task
+- `--path <path>`: Custom worktree path
+- `--dry-run`: Preview without creating
+- `--no-mise-trust`: Skip automatic mise trust
+- `--no-status-update`: Skip task status update
+- `--no-commit`: Skip committing task changes
+
+### list
+- `--format <format>`: Output format (table, json, simple)
+- `--show-tasks`: Include task associations
+- `--task-associated`: Filter by task association
+- `--search <pattern>`: Filter by search pattern
+
+### switch
+- `identifier`: Worktree identifier (task ID, branch name, directory, path)
+- `--verbose`: Show detailed information
+
+### remove
+- `--task <task-id>`: Remove task worktree
+- `--force`: Force removal with uncommitted changes
+- `--keep-directory`: Keep worktree directory
+- `--dry-run`: Preview without removing
+
+### prune
+- `--cleanup-directories`: Remove orphaned directories
+- `--dry-run`: Preview changes
+- `--verbose`: Detailed output
+
+### config
+- `--show`: Show current configuration
+- `--validate`: Validate configuration
+- `--files`: Show configuration file locations
+
+## Error Handling
+
+The CLI handles common error conditions:
+- **Task not found**: Validates task ID existence before creation
+- **Not in git repository**: Checks git repository status
+- **Configuration invalid**: Validates configuration before operations
+- **Worktree conflicts**: Detects existing worktrees and provides alternatives
+- **Permission issues**: Validates directory permissions and access
+- **Uncommitted changes**: Warns about changes before removal
+
+## Best Practices
+
+1. **Use task-aware creation** for ACE workflow integration
+2. **Validate configuration** before operations
+3. **Use dry-run** to preview changes
+4. **Clean up worktrees** when tasks are complete
+5. **Prune regularly** to maintain clean repository state
+6. **Check git status** before removing worktrees with changes
+
+## Response Format
+
+```markdown
+**Operation:** [create/list/switch/remove/prune/config]
+**Worktree(s):** [Worktree information]
+**Status:** [Success/Failure with details]
+**Location(s):** [Relevant paths]
+**Next Steps:** [Recommended follow-up actions]
+```

data/lib/ace/git/worktree/atoms/git_command.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Ace
+  module Git
+    module Worktree
+      module Atoms
+        # Git command execution atom
+        #
+        # Provides a thin wrapper around ace-git's CommandExecutor
+        # for safe git command execution with proper error handling.
+        # This adapter maintains backward compatibility with the original API
+        # while delegating to the consolidated ace-git package.
+        #
+        # @example Execute a git worktree command
+        #   GitCommand.execute("worktree", "add", "/path/to/worktree", "-b", "feature-branch")
+        #
+        # @example Handle command failures
+        #   result = GitCommand.execute("worktree", "add", "/invalid/path")
+        #   unless result[:success]
+        #     puts "Error: #{result[:error]}"
+        #   end
+        class GitCommand
+          # Fallback timeout for git commands (30 seconds)
+          # Used only when config is unavailable
+          FALLBACK_TIMEOUT = 30
+
+          class << self
+            # Get default timeout from config or fallback
+            # @return [Integer] Timeout in seconds
+            def default_timeout
+              Ace::Git::Worktree.default_timeout
+            rescue
+              FALLBACK_TIMEOUT
+            end
+
+            # Execute a git command safely using ace-git's CommandExecutor
+            #
+            # @param args [Array<String>] Command arguments (command and its arguments)
+            # @param timeout [Integer, nil] Timeout in seconds (uses config default if nil)
+            # @return [Hash] Result hash with :success, :output, :error, :exit_code keys
+            #
+            # @example
+            #   result = GitCommand.execute("worktree", "list")
+            #   # => { success: true, output: "/path/to/worktree abc123 [branch-name]\n", error: "", exit_code: 0 }
+            def execute(*args, timeout: nil)
+              timeout ||= default_timeout
+              # Ensure all arguments are strings
+              string_args = args.map(&:to_s)
+
+              # Delegate to ace-git's CommandExecutor
+              # Note: CommandExecutor expects "git" as first argument
+              result = Ace::Git::Atoms::CommandExecutor.execute("git", *string_args, timeout:)
+
+              # Normalize ace-git result keys for legacy compatibility
+              {
+                success: result[:success],
+                output: result[:output].to_s,
+                error: result[:error].to_s,
+                exit_code: result[:exit_code] || 0
+              }
+            rescue => e
+              # Handle unexpected exceptions from ace-git to maintain defensive behavior
+              {
+                success: false,
+                output: "",
+                error: "Unexpected error: #{e.message}",
+                exit_code: 1
+              }
+            end
+
+            # Execute a git worktree command
+            #
+            # @param args [Array<String>] Worktree subcommand arguments
+            # @param timeout [Integer, nil] Timeout in seconds (uses config default if nil)
+            # @return [Hash] Result hash with command execution details
+            #
+            # @example
+            #   result = GitCommand.worktree("add", "/path/to/worktree", "-b", "feature-branch")
+            def worktree(*args, timeout: nil)
+              execute("worktree", *args, timeout: timeout)
+            end
+
+            # Check if git repository exists
+            #
+            # @return [Boolean] true if current directory is a git repository
+            def git_repository?
+              Ace::Git::Atoms::CommandExecutor.in_git_repo?
+            end
+
+            # Get current git branch name or commit SHA if in detached HEAD state
+            #
+            # @return [String, nil] Current branch name, commit SHA (if detached), or nil on error
+            def current_branch
+              # ace-git's current_branch now handles detached HEAD state
+              # and returns SHA directly when detached
+              Ace::Git::Atoms::CommandExecutor.current_branch
+            end
+
+            # Check if a git ref (branch, tag, commit SHA) exists
+            #
+            # @param ref [String] Git ref to validate
+            # @return [Boolean] true if ref exists
+            def ref_exists?(ref)
+              result = execute("rev-parse", "--verify", "--quiet", ref, timeout: 5)
+              result[:success]
+            end
+
+            # Get git repository root directory
+            #
+            # Delegates to ace-git's CommandExecutor for repository root detection
+            #
+            # @return [String, nil] Path to git repository root or nil if not in a git repo
+            def git_root
+              Ace::Git::Atoms::CommandExecutor.repo_root
+            end
+          end
+        end
+      end
+    end
+  end
+end