ace-git-worktree 0.19.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ACE Development Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,40 @@
+<div align="center">
+  <h1> ACE - Git Worktree </h1>
+
+  Task-aware git worktree management for isolated environments in one command.
+
+  <img src="https://raw.githubusercontent.com/cs3b/ace/main/docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
+  <br><br>
+
+  <a href="https://rubygems.org/gems/ace-git-worktree"><img alt="Gem Version" src="https://img.shields.io/gem/v/ace-git-worktree.svg" /></a>
+  <a href="https://www.ruby-lang.org"><img alt="Ruby" src="https://img.shields.io/badge/Ruby-3.2+-CC342D?logo=ruby" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg" /></a>
+
+</div>
+
+> Works with: Claude Code, Codex CLI, OpenCode, Gemini CLI, pi-agent, and more.
+
+[Getting Started](docs/getting-started.md) | [Usage Guide](docs/usage.md) | [Handbook - Skills, Agents, Templates](docs/handbook.md)
+
+![ace-git-worktree demo](docs/demo/ace-git-worktree-getting-started.gif)
+
+`ace-git-worktree` gives each task, PR, or branch its own workspace so you can move faster without carrying local state between changes. It handles naming, post-create hooks (commands run after worktree creation), cleanup, and navigation with configurable conventions across the team.
+
+## How It Works
+
+1. Create an isolated worktree from a task ID, PR number, or branch name with one command.
+2. Work inside the worktree with task metadata and status kept in sync automatically.
+3. Clean up stale worktrees when done, with path resolution for seamless `cd` navigation.
+
+## Use Cases
+
+**Start task work in an isolated environment** - run [`ace-git-worktree`](docs/usage.md) with a task ID to create a linked worktree, update task status, and set up the branch. Use the `as-git-worktree-create` agent workflow for guided setup.
+
+**Review pull requests in dedicated directories** - create a worktree from a PR number instead of switching branches in your main checkout, keeping review work cleanly separated.
+
+**Manage worktree lifecycle across a team** - use the `as-git-worktree-manage` workflow with configurable naming, hooks, upstream push, and draft-PR automation to standardize workflows across the team.
+
+**Orchestrate parallel task work with ace-overseer** - pair with [ace-overseer](../ace-overseer) to spin up worktrees per task, drive agents in parallel, and prune finished worktrees automatically.
+
+---
+[Getting Started](docs/getting-started.md) | [Usage Guide](docs/usage.md) | [Handbook - Skills, Agents, Templates](docs/handbook.md) | Part of [ACE](https://github.com/cs3b/ace)

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+desc "Run tests using ace-test"
+task :test do
+  sh "ace-test"
+end
+
+desc "Run tests directly (CI mode)"
+Minitest::TestTask.create(:ci)
+
+task default: :test

data/docs/demo/ace-git-worktree-getting-started.tape.yml

@@ -0,0 +1,28 @@
+---
+description: Preview task-aware worktree creation and listing
+tags:
+- docs
+- worktree
+settings:
+  font_size: 16
+  width: 960
+  height: 480
+  format: gif
+setup:
+- sandbox
+- git-init
+- copy-fixtures
+- run: git add -A && git commit -qm "initial commit"
+scenes:
+- name: Create a worktree from a branch
+  commands:
+  - type: ace-git-worktree create feature/demo
+    sleep: 4s
+- name: List worktrees
+  commands:
+  - type: clear
+    sleep: 1s
+  - type: ace-git-worktree list
+    sleep: 3s
+teardown:
+- cleanup

data/docs/demo/fixtures/README.md

@@ -0,0 +1,3 @@
+# Demo fixtures for ace-git-worktree
+
+Seed data used by YAML demo setup.

data/docs/demo/fixtures/sample.txt

@@ -0,0 +1 @@
+sample fixture content

data/docs/getting-started.md

@@ -0,0 +1,114 @@
+---
+doc-type: user
+title: ace-git-worktree Getting Started
+purpose: Tutorial for first-run ace-git-worktree workflows
+ace-docs:
+  last-updated: 2026-03-22
+  last-checked: 2026-03-22
+---
+
+# Getting Started with ace-git-worktree
+
+This walkthrough shows the core `ace-git-worktree` loop: create an isolated task workspace, jump into it, inspect what
+exists, and clean it up when the work is done.
+
+## Prerequisites
+
+* Ruby 3.2+
+* Git 2.0+ or any modern Git with `git worktree` support
+* `ace-git-worktree` installed
+* Optional: `ace-task` for task metadata and status updates
+* Optional: `mise` when your projects use `mise.toml` files that should be trusted automatically
+* Optional: GitHub CLI (`gh`) for PR-based worktrees
+
+## Installation
+
+```bash
+gem install ace-git-worktree
+```
+
+## 1. Create Your First Task Worktree
+
+Start with a task-aware worktree:
+
+```bash
+ace-git-worktree create --task 081
+```
+
+This creates a separate worktree directory, derives a branch name from the task, and can update task metadata based on
+your current worktree configuration.
+
+## 2. Switch Into the Worktree
+
+Resolve the path and enter it:
+
+```bash
+cd "$(ace-git-worktree switch 081)"
+```
+
+This keeps your shell history simple while avoiding hard-coded worktree paths.
+
+## 3. Inspect Active Worktrees
+
+List worktrees with task context when you want a quick overview:
+
+```bash
+ace-git-worktree list --show-tasks
+```
+
+Use `--search auth` or `--format json` later when you want filtering or machine-readable output.
+
+## 4. Create a PR Worktree
+
+Open a pull request in its own workspace:
+
+```bash
+ace-git-worktree create --pr 26
+```
+
+This is useful for review work, branch comparisons, or patching an existing PR without touching your current checkout.
+
+## 5. Clean Up When You Finish
+
+Remove the task worktree:
+
+```bash
+ace-git-worktree remove --task 081
+```
+
+Use `ace-git-worktree prune --dry-run` first when you want to preview stale-reference cleanup.
+
+## Configuration Basics
+
+Project overrides live in `.ace/git/worktree.yml`. User overrides live in `~/.ace/git/worktree.yml`. Start small:
+
+```yaml
+git:
+  worktree:
+    root_path: ".ace-wt"
+    task:
+      directory_format: "task.{task_id}"
+      branch_format: "{id}-{slug}"
+    cleanup:
+      on_delete: true
+```
+
+Add hooks, auto-push, tmux launch, or PR automation only after the basic create/switch/remove loop feels right.
+
+## Common Commands
+
+| Goal | Command |
+|------|---------|
+| Create a task worktree | `ace-git-worktree create --task 081` |
+| Create a PR worktree | `ace-git-worktree create --pr 26` |
+| Switch into a worktree | `cd "$(ace-git-worktree switch 081)"` |
+| List worktrees with task info | `ace-git-worktree list --show-tasks` |
+| Remove a task worktree | `ace-git-worktree remove --task 081` |
+| Preview stale cleanup | `ace-git-worktree prune --dry-run` |
+
+## Next Steps
+
+* Run `ace-git-worktree config --files` to see which config files are active
+* Add `hooks.after_create` commands to trust `mise` or bootstrap dependencies
+* Use `ace-git-worktree create --from origin/feature/name` for branch-based work
+* Run `ace-git-worktree --help` to browse subcommand examples

data/docs/handbook.md

@@ -0,0 +1,38 @@
+---
+doc-type: user
+title: ace-git-worktree Handbook Catalog
+purpose: Catalog of ace-git-worktree workflows, skills, and agents
+ace-docs:
+  last-updated: 2026-03-22
+  last-checked: 2026-03-22
+---
+
+# ace-git-worktree Handbook Catalog
+
+Reference for package-owned handbook resources in `ace-git-worktree/handbook/`.
+
+## Skills
+
+| Skill | What it does |
+|-------|--------------|
+| `as-git-worktree` | Run the top-level task-aware worktree workflow |
+| `as-git-worktree-create` | Create task-aware, PR-aware, or branch-based worktrees |
+| `as-git-worktree-manage` | List, switch, prune, and remove existing worktrees |
+
+## Workflow Instructions
+
+| Protocol Path | Purpose | Invoked by |
+|---------------|---------|------------|
+| `wfi://git/worktree` | Load the main worktree workflow entry point | `as-git-worktree` |
+| `wfi://git/worktree-create` | Guide task-aware or branch-based creation flows | `as-git-worktree-create` |
+| `wfi://git/worktree-manage` | Guide list, switch, remove, prune, and config flows | `as-git-worktree-manage` |
+
+## Agents
+
+* `handbook/agents/worktree.ag.md` for focused worktree command execution
+
+## Related Docs
+
+* [Getting Started](getting-started.md)
+* [CLI Usage Reference](usage.md)
+* Load workflows directly with `ace-bundle`, for example `ace-bundle wfi://git/worktree`

data/docs/usage.md

@@ -0,0 +1,334 @@
+---
+doc-type: user
+title: ace-git-worktree CLI Usage Reference
+purpose: Command reference for ace-git-worktree
+ace-docs:
+  last-updated: 2026-03-22
+  last-checked: 2026-03-22
+---
+
+# ace-git-worktree CLI Usage Reference
+
+Reference for `ace-git-worktree` commands, options, and configuration.
+
+## Installation
+
+```bash
+gem install ace-git-worktree
+```
+
+## Command Overview
+
+`ace-git-worktree` ships six commands:
+
+* `create` for task-aware, PR-aware, and branch-based worktree creation
+* `list` for active worktree inventory and filtering
+* `switch` for resolving a worktree path you can `cd` into
+* `remove` for safe worktree removal
+* `prune` for stale-reference cleanup
+* `config` for configuration inspection and validation
+
+Run `ace-git-worktree --help` for the top-level summary and examples.
+
+## Quick Start (5 Minutes)
+
+Create a task worktree, list active worktrees, and resolve the path for shell navigation:
+
+```bash
+ace-git-worktree create --task 081
+ace-git-worktree list --show-tasks
+ace-git-worktree switch 081
+```
+
+**Expected output:**
+
+```text
+Created worktree for task 081
+... task-associated worktree appears in list output ...
+/path/to/project/.ace-wt/task.081
+```
+
+Success looks like a new worktree directory exists and `switch` returns a path you can `cd` into.
+
+## Common Scenarios
+
+### Scenario 1: Start Isolated Work on a Task
+
+**Goal:** Create a task-specific workspace without touching your current checkout.
+
+**Commands:**
+
+```bash
+ace-git-worktree create --task 081
+ace-git-worktree list --show-tasks
+```
+
+**Expected output:**
+
+```text
+Created task worktree and branch for 081
+... task.081 appears in the worktree list ...
+```
+
+**Next steps:** Run `cd "$(ace-git-worktree switch 081)"` to move into the new worktree.
+
+### Scenario 2: Review a Pull Request in Its Own Worktree
+
+**Goal:** Create a dedicated workspace for PR review or patching.
+
+**Commands:**
+
+```bash
+ace-git-worktree create --pr 26
+ace-git-worktree list
+```
+
+**Expected output:**
+
+```text
+Created PR worktree for #26
+... ace-pr-26 appears in the worktree list ...
+```
+
+**Next steps:** Enter the PR worktree or remove it later with `ace-git-worktree remove pr-26`.
+
+### Scenario 3: Clean Up Stale Worktrees Safely
+
+**Goal:** See what cleanup would do before removing anything.
+
+**Commands:**
+
+```bash
+ace-git-worktree prune --dry-run
+ace-git-worktree remove --task 081 --dry-run
+```
+
+**Expected output:**
+
+```text
+Would prune stale references
+Would remove task.081
+```
+
+**Next steps:** Re-run either command without `--dry-run` once the preview looks correct.
+
+## Commands
+
+### `ace-git-worktree create [BRANCH]`
+
+Create a new worktree from a task, PR, explicit branch, or positional branch argument.
+
+```bash
+ace-git-worktree create --task 081
+ace-git-worktree create --pr 123
+ace-git-worktree create --from origin/feature/auth
+ace-git-worktree create feature/new-auth
+ace-git-worktree create --task 081 --dry-run
+```
+
+**Options:**
+
+* `--task` - Task ID for a task-aware worktree
+* `--pr`, `--pull-request` - PR number for a PR-aware worktree
+* `--from`, `-b` - Create from a specific local or remote branch
+* `--path` - Override the destination worktree path
+* `--source` - Override the git ref used as the start point
+* `--dry-run` - Show what would be created
+* `--no-status-update` - Skip marking the task in progress
+* `--no-commit` - Skip committing task metadata changes
+* `--no-push` - Skip pushing task changes
+* `--no-upstream` - Skip pushing the new branch with upstream tracking
+* `--no-pr` - Skip automatic draft-PR creation when enabled
+* `--push-remote` - Override the remote used for task-related pushes
+* `--no-auto-navigate` - Stay in the current directory after creation
+* `--commit-message` - Use a custom commit message for task metadata updates
+* `--target-branch` - Override the PR target branch
+* `--force` - Create even when the worktree already exists
+* `-q`, `--quiet` - Suppress non-essential output
+* `-v`, `--verbose` - Show verbose output
+* `-d`, `--debug` - Show debug output
+
+### `ace-git-worktree list`
+
+List active worktrees with optional task metadata and filters.
+
+```bash
+ace-git-worktree list
+ace-git-worktree list --show-tasks
+ace-git-worktree list --format json
+ace-git-worktree list --search auth
+```
+
+**Options:**
+
+* `--format` - Output format: `table`, `json`, or `simple`
+* `--show-tasks` - Include task associations
+* `--task-associated` - Show only task-associated worktrees
+* `--usable` - Show only usable worktrees
+* `--search` - Filter by branch-name pattern
+* `-q`, `--quiet` - Suppress non-essential output
+* `-v`, `--verbose` - Show verbose output
+* `-d`, `--debug` - Show debug output
+
+### `ace-git-worktree switch [IDENTIFIER]`
+
+Resolve a worktree path for shell navigation.
+
+```bash
+ace-git-worktree switch 081
+ace-git-worktree switch feature-branch
+ace-git-worktree switch --list
+```
+
+`IDENTIFIER` can be a task ID, branch name, directory name, or explicit path.
+
+**Options:**
+
+* `--list`, `-l` - List available worktrees instead of returning one path
+* `-q`, `--quiet` - Suppress non-essential output
+* `-v`, `--verbose` - Show verbose output
+* `-d`, `--debug` - Show debug output
+
+### `ace-git-worktree remove [IDENTIFIER]`
+
+Remove a worktree by task, branch, directory, or path.
+
+```bash
+ace-git-worktree remove --task 081
+ace-git-worktree remove feature-branch
+ace-git-worktree remove --task 081 --force
+ace-git-worktree remove --task 081 --dry-run
+```
+
+**Options:**
+
+* `--task` - Remove the worktree for a specific task
+* `--force` - Remove even with uncommitted changes
+* `--keep-directory` - Keep the worktree directory after removal
+* `--delete-branch`, `-D` - Also delete the associated branch
+* `--dry-run` - Show what would be removed
+* `-q`, `--quiet` - Suppress non-essential output
+* `-v`, `--verbose` - Show verbose output
+* `-d`, `--debug` - Show debug output
+
+### `ace-git-worktree prune`
+
+Prune deleted worktrees from git metadata and optionally remove orphaned directories.
+
+```bash
+ace-git-worktree prune
+ace-git-worktree prune --dry-run
+ace-git-worktree prune --cleanup-directories
+```
+
+**Options:**
+
+* `--dry-run` - Preview what would be pruned
+* `--cleanup-directories` - Remove orphaned worktree directories
+* `--force` - Force cleanup
+* `-q`, `--quiet` - Suppress non-essential output
+* `-v`, `--verbose` - Show verbose output
+* `-d`, `--debug` - Show debug output
+
+### `ace-git-worktree config [SUBCOMMAND]`
+
+Show current configuration, validate it, or list the config files in play.
+
+```bash
+ace-git-worktree config
+ace-git-worktree config --show
+ace-git-worktree config --validate
+ace-git-worktree config --files
+ace-git-worktree config validate
+```
+
+**Options:**
+
+* `--show` - Show current configuration
+* `--validate` - Validate configuration
+* `--files` - Show configuration file locations
+* `-q`, `--quiet` - Suppress non-essential output
+* `-v`, `--verbose` - Show verbose output
+* `-d`, `--debug` - Show debug output
+
+## Configuration
+
+`ace-git-worktree` uses the ACE configuration cascade:
+
+* Project config: `.ace/git/worktree.yml`
+* User config: `~/.ace/git/worktree.yml`
+* Package defaults: `ace-git-worktree/.ace-defaults/git/worktree.yml`
+
+### Common Settings
+
+```yaml
+git:
+  worktree:
+    root_path: ".ace-wt"
+    auto_navigate: true
+    tmux: false
+    task:
+      directory_format: "task.{task_id}"
+      branch_format: "{id}-{slug}"
+      auto_mark_in_progress: true
+      auto_commit_task: true
+      auto_push_task: true
+      auto_setup_upstream: false
+      auto_create_pr: false
+    pr:
+      directory_format: "ace-pr-{number}"
+      branch_format: "pr-{number}-{slug}"
+      fetch_before_create: true
+    cleanup:
+      on_delete: true
+```
+
+The defaults file also documents timeout controls, hook execution, current-task symlink creation, push remotes, and PR
+title formatting.
+
+## Troubleshooting
+
+### Problem: `create --task` cannot find the task
+
+**Symptom:** The command reports that the task does not exist.
+
+**Solution:**
+
+```bash
+ace-task show 081
+```
+
+Use a task reference that exists in the current repository, or run the command from the project root where the ACE task
+data is available.
+
+### Problem: PR worktree creation fails
+
+**Symptom:** `create --pr` reports a GitHub or authentication error.
+
+**Solution:**
+
+```bash
+gh auth status
+gh auth login
+```
+
+PR-based creation depends on `gh` being installed and authenticated.
+
+### Problem: `switch` returns nothing useful
+
+**Symptom:** The identifier does not resolve to a worktree path.
+
+**Solution:**
+
+```bash
+ace-git-worktree list --show-tasks
+```
+
+Confirm the identifier matches a task ID, branch name, directory name, or path shown in the current worktree list.
+
+## Related Tools
+
+* [ace-task](../ace-task) for task metadata and status updates
+* [ace-git](../ace-git) for repository and PR context
+* [ace-git-commit](../ace-git-commit) for commits inside worktrees
+* [ace-bundle](../ace-bundle) for loading worktree workflow instructions directly

data/exe/ace-git-worktree

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Add lib directory to load path
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+# Load the ace-git-worktree gem
+require "ace/git/worktree"
+require "ace/support/cli"
+
+args = ARGV.empty? ? ["--help"] : ARGV
+
+# Start ace-support-cli with exception-based exit code handling (per ADR-023)
+begin
+  exit(Ace::Git::Worktree::CLI.start(args))
+rescue SystemExit => e
+  exit(e.status)
+rescue Ace::Support::Cli::Error => e
+  warn e.message
+  exit(e.exit_code)
+rescue Ace::Support::Cli::CommandNotFoundError => e
+  warn "unknown command: #{e.message}"
+  exit(1)
+end