ace-git 0.18.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michal Czyz
+
+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,48 @@
+<div align="center">
+  <h1> ACE - Git </h1>
+
+  Git workflows and context commands for developers and AI agents.
+
+  <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"><img alt="Gem Version" src="https://img.shields.io/gem/v/ace-git.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 demo](docs/demo/ace-git-getting-started.gif)
+
+`ace-git` gives developers and coding agents focused git context commands and guided workflows that keep history operations traceable, review-friendly, and safe to execute from the terminal. It handles status, diff, branch, PR context, and structured rebase and reorganization flows.
+
+## How It Works
+
+1. Query repository state with context commands for status, diff, branch, and pull request metadata.
+2. Run guided workflows for changelog-preserving rebases, commit reorganization, and PR creation or update.
+3. Review results with smart diff output in summary and grouped-stats formats before publishing.
+
+## Use Cases
+
+**Check repo and PR context without leaving the CLI** - inspect branch, change, and pull request state quickly with [`ace-git`](docs/usage.md) before running higher-risk history operations.
+
+**Rebase with changelog-safe workflow guardrails** - use the `as-git-rebase` agent workflow to run structured rebase flows that preserve package release metadata and reduce manual conflict-prone steps.
+
+**Prepare clean review history before publishing** - run the `as-git-reorganize-commits` workflow to reorganize commit stacks, then use `as-github-pr-create` or `as-github-pr-update` to manage PR metadata in a predictable workflow sequence. See [Handbook](docs/handbook.md) for the full skill and workflow catalog.
+
+**Coordinate with commit and worktree tools** - pair with [ace-git-commit](../ace-git-commit) for scoped commit authoring, [ace-git-worktree](../ace-git-worktree) for task-oriented worktree management, and [ace-bundle](../ace-bundle) for loading workflow instructions.
+
+## Installation
+
+```bash
+gem install ace-git
+```
+
+See [Getting Started](docs/getting-started.md) for setup and first steps.
+
+---
+[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 "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+  t.warning = false
+  t.verbose = false
+end
+
+# Keep build as default for backward compatibility
+task default: :build

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

@@ -0,0 +1,18 @@
+---
+description: Show ace-git repository context and diff summary
+tags:
+- ace-git
+- git
+- getting-started
+settings:
+  font_size: 16
+  width: 1200
+  height: 700
+  format: gif
+scenes:
+- name: Main flow
+  commands:
+  - type: ace-git status
+    sleep: 4s
+  - type: ace-git diff --format summary
+    sleep: 4s

data/docs/demo/fixtures/README.md

@@ -0,0 +1,3 @@
+# Demo fixtures for ace-git
+
+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,87 @@
+---
+doc-type: user
+title: ace-git Getting Started
+purpose: Tutorial for ace-git first-run workflows
+ace-docs:
+  last-updated: 2026-03-22
+  last-checked: 2026-03-22
+---
+
+# Getting Started with ace-git
+
+This walkthrough shows the core `ace-git` loop: inspect repository context, review a diff, and jump into a
+guided workflow.
+
+## Prerequisites
+
+- Ruby 3.2+
+- Git 2.23+
+- `ace-git` installed
+- Optional: GitHub CLI (`gh`) for PR-aware commands and workflows
+
+## Installation
+
+```bash
+gem install ace-git
+```
+
+## 1. Check Repository Context
+
+Start with the repo snapshot command:
+
+```bash
+ace-git status
+```
+
+This shows your current branch, tracking state, recent commits, and PR context when available.
+
+## 2. Inspect the Diff
+
+Use the summary format when you want a quick read on what changed:
+
+```bash
+ace-git diff --format summary
+```
+
+Switch to raw diff output later with `ace-git diff` when you need the full patch.
+
+## 3. Open a Guided Workflow
+
+Use `ace-nav` when you want to discover or load the rebase workflow entry point:
+
+```bash
+ace-nav wfi://git/rebase
+```
+
+When you are ready to run it directly, load the workflow with `ace-bundle wfi://git/rebase`.
+
+## 4. Set Basic Preferences
+
+Add project or user defaults in `.ace/git/config.yml`:
+
+```yaml
+git:
+  default_branch: main
+  remote: origin
+  status:
+    commits_limit: 5
+```
+
+Use this for preferences, not for redefining the workflow logic.
+
+## Common Commands
+
+| Goal | Command |
+|------|---------|
+| Show repo context | `ace-git status` |
+| Show a quick diff summary | `ace-git diff --format summary` |
+| Show branch tracking info | `ace-git branch` |
+| Show PR metadata | `ace-git pr` |
+| Show package version | `ace-git version` |
+
+## Next Steps
+
+- Load `wfi://github/pr/create` to open a structured PR workflow
+- Load `wfi://github/pr/update` to refresh an existing PR description
+- Load `wfi://git/reorganize-commits` to clean up branch history before review
+- Run `ace-git --help` to browse command-level examples

data/docs/handbook.md

@@ -0,0 +1,50 @@
+---
+doc-type: user
+title: ace-git Handbook Catalog
+purpose: Catalog of ace-git workflows, skills, guides, and templates
+ace-docs:
+  last-updated: 2026-03-22
+  last-checked: 2026-03-22
+---
+
+# ace-git Handbook Catalog
+
+Reference for package-owned handbook resources in `ace-git/handbook/`.
+
+## Skills
+
+| Skill | What it does |
+|-------|--------------|
+| `as-git-rebase` | Guide changelog-preserving rebases |
+| `as-git-reorganize-commits` | Rework commit history into reviewable logical groups |
+| `as-github-pr-create` | Create pull requests with the package templates and workflow |
+| `as-github-pr-update` | Refresh an existing PR body from current branch context |
+| `as-github-release-publish` | Publish a GitHub release from the ACE workflow |
+
+## Workflow Instructions
+
+| Protocol Path | Purpose | Invoked by |
+|--------------|---------|------------|
+| `wfi://git/rebase` | Rebase a branch while preserving changelog/version files | `as-git-rebase` |
+| `wfi://git/reorganize-commits` | Consolidate or regroup commit history before review | `as-git-reorganize-commits` |
+| `wfi://github/pr/create` | Create a PR with the package templates | `as-github-pr-create` |
+| `wfi://github/pr/update` | Update a PR description from current state | `as-github-pr-update` |
+| `wfi://github/release-publish` | Publish a GitHub release | `as-github-release-publish` |
+
+## Guides
+
+- `handbook/guides/version-control-system-git.g.md`
+- `handbook/guides/version-control/ruby.md`
+- `handbook/guides/version-control/rust.md`
+- `handbook/guides/version-control/typescript.md`
+
+## Templates
+
+- PR templates: `handbook/templates/pr/default.template.md`, `handbook/templates/pr/feature.template.md`, `handbook/templates/pr/bugfix.template.md`
+- Commit templates: `handbook/templates/commit/squash.template.md`
+
+## Related Docs
+
+- [Getting Started](getting-started.md)
+- [CLI Usage Reference](usage.md)
+- Load workflows directly with `ace-bundle`, for example `ace-bundle wfi://git/rebase`

data/docs/usage.md

@@ -0,0 +1,259 @@
+---
+doc-type: user
+title: ace-git CLI Usage Reference
+purpose: Command reference for ace-git
+ace-docs:
+  last-updated: 2026-03-22
+  last-checked: 2026-03-22
+---
+
+# ace-git CLI Usage Reference
+
+Reference for `ace-git` commands, options, and configuration.
+
+## Installation
+
+```bash
+# In Gemfile
+gem 'ace-git'
+
+# Or install directly
+gem install ace-git
+```
+
+## Command Overview
+
+`ace-git` ships five commands:
+
+- `diff` for filtered or formatted git diffs
+- `status` for repository context and PR activity
+- `branch` for current branch and tracking state
+- `pr` for PR metadata lookup
+- `version` for the installed package version
+
+`ace-git` with no arguments shows help. Git range shorthand such as `HEAD~5..HEAD` routes to `diff`.
+
+## Commands
+
+### `ace-git --help`
+
+Show formatted command help and examples.
+
+```bash
+ace-git --help
+ace-git -h
+```
+
+`ace-git` with no arguments also shows help.
+
+### `ace-git diff [RANGE]`
+
+Generate git diff with configurable filtering and formatting.
+
+```bash
+# Smart defaults (unstaged changes OR branch diff)
+ace-git diff
+ace-git diff --since "7d"
+
+# Specific range
+ace-git diff HEAD~10..HEAD
+ace-git diff origin/main...HEAD
+
+# Range shorthand (routes to diff)
+ace-git HEAD~5..HEAD
+ace-git HEAD
+
+# Time-based filtering
+ace-git diff --since "1 week ago"
+ace-git diff --since "2025-01-01"
+
+# Path filtering (glob patterns)
+ace-git diff --paths "lib/**/*.rb" "src/**/*.js"
+ace-git diff --exclude "test/**/*" "vendor/**/*"
+
+# Save to file
+ace-git diff --output changes.diff
+ace-git diff HEAD~5..HEAD --output /tmp/my-changes.diff
+
+# Summary format (human-readable)
+ace-git diff --format summary
+
+# Grouped stats format (package/layer grouped)
+ace-git diff --format grouped-stats
+
+# Raw unfiltered diff
+ace-git diff --raw
+```
+
+**Options:**
+- `--format, -f` - Output format: `diff` (default), `summary`, `grouped-stats`
+- `--since, -s` - Changes since date/duration (e.g., "7d", "1 week ago")
+- `--paths, -p` - Include only these glob patterns
+- `--exclude, -e` - Exclude these glob patterns
+- `--output, -o` - Write diff to file instead of stdout
+- `--config, -c` - Load config from specific file
+- `--raw` - Raw unfiltered output (no exclusions)
+
+### `ace-git status`
+
+Display comprehensive repository context including current branch, associated PR information, recent commits, and PR activity (merged/open PRs).
+
+```bash
+# Full status output (markdown)
+ace-git status
+
+# Skip PR lookups (faster, local-only)
+ace-git status --no-pr
+ace-git status -n
+
+# Control recent commits shown
+ace-git status --commits 5    # Show 5 recent commits
+ace-git status --commits 0    # Disable recent commits
+
+# JSON output
+ace-git status --format json
+
+# Include PR diff in output
+ace-git status --with-diff
+```
+
+**Options:**
+- `--format, -f` - Output format: `markdown` (default), `json`
+- `--no-pr, -n` - Skip PR metadata and activity lookups (faster)
+- `--commits N` - Number of recent commits to show (default: 3 from config)
+- `--with-diff` - Include PR diff in output
+
+**Output includes:**
+- Current branch name with git status -sb output
+- Remote tracking status (ahead/behind)
+- Detected task pattern (from branch name)
+- Recent commits (configurable count)
+- Associated PR metadata (if found)
+- PR activity: recently merged PRs and open PRs
+
+### `ace-git branch`
+
+Display current branch name and remote tracking status.
+
+```bash
+ace-git branch
+# Output: 140-feature-name (tracking: origin/140-feature-name)
+
+ace-git branch --format json
+# Output:
+# {
+#   "name": "140-feature-name",
+#   "detached": false,
+#   "tracking": "origin/140-feature-name",
+#   "ahead": 2,
+#   "behind": 0,
+#   "up_to_date": false,
+#   "status_description": "2 ahead"
+# }
+```
+
+**Options:**
+- `--format, -f` - Output format: `text` (default), `json`
+
+### `ace-git pr [NUMBER]`
+
+Fetch and display PR metadata using GitHub CLI.
+
+```bash
+# Auto-detect PR from current branch
+ace-git pr
+
+# Specific PR number
+ace-git pr 123
+
+# Cross-repository PR
+ace-git pr owner/repo#456
+
+# JSON output
+ace-git pr --format json
+```
+
+**Options:**
+- `--format, -f` - Output format: `markdown` (default), `json`
+- `--with-diff` - Include PR diff in output
+
+**PR Number Formats:**
+- Simple number: `123`
+- Qualified: `owner/repo#456`
+- GitHub URL: `https://github.com/owner/repo/pull/789`
+
+**Requirements:** GitHub CLI (`gh`) must be installed and authenticated.
+
+```bash
+# Install gh
+brew install gh
+
+# Authenticate
+gh auth login
+```
+
+### `ace-git version`
+
+Print the installed `ace-git` version.
+
+```bash
+ace-git version
+ace-git --version
+```
+
+## Configuration
+
+ace-git uses the ACE configuration cascade:
+
+- **Global config:** `~/.ace/git/config.yml`
+- **Project config:** `.ace/git/config.yml`
+- **Example config:** `ace-git/.ace-defaults/git/config.yml`
+
+### Example Configuration
+
+```yaml
+# .ace/git/config.yml
+diff:
+  exclude_patterns:
+    - "vendor/**/*"
+    - "node_modules/**/*"
+    - "*.lock"
+  exclude_whitespace: true
+  exclude_renames: false
+  max_lines: 10000
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `exclude_patterns` | Array | See below | Glob patterns to exclude from diff |
+| `exclude_whitespace` | Boolean | `true` | Ignore whitespace-only changes |
+| `exclude_renames` | Boolean | `false` | Exclude renamed files from diff |
+| `exclude_moves` | Boolean | `false` | Exclude moved files from diff |
+| `max_lines` | Integer | `10000` | Maximum lines in diff output |
+| `timeout` | Integer | `30` | Command timeout in seconds |
+| `grouped_stats.layers` | Array | `["lib","test","handbook"]` | Preferred layer grouping order |
+| `grouped_stats.collapse_above` | Integer | `5` | Collapse markdown groups above this file count |
+| `grouped_stats.show_full_tree` | String | `collapsible` | Tree rendering strategy hint |
+| `grouped_stats.dotfile_groups` | Array | `[".ace-taskflow",".ace"]` | Dot-directories to prioritize in grouping |
+
+**Default exclude_patterns** (from `.ace-defaults/git/config.yml`):
+- Lock files: `**/*.lock`, `package-lock.json`, `yarn.lock`, `Gemfile.lock`
+- Vendored deps: `vendor/**/*`, `node_modules/**/*`
+- Build artifacts: `coverage/**/*`, `dist/**/*`, `build/**/*`, `.cache/**/*`
+- Test fixtures: `**/fixtures/**/*`, `**/testdata/**/*`
+
+Note: `test/**/*` and `spec/**/*` are NOT excluded by default - test changes are typically important to review.
+
+## Exit Codes
+
+- `0` - Success
+- `1` - Error (configuration error, git error, etc.)
+
+## Related Tools
+
+- **ace-git-commit** - Smart git commit generation
+- **ace-git-worktree** - Git worktree management
+- **ace-bundle** - Load ACE workflow instructions directly
+- **ace-nav** - Discover workflow and template protocol paths

data/exe/ace-git

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require_relative "../lib/ace/git"
+require_relative "../lib/ace/git/cli"
+
+def git_range_pattern?(arg)
+  return false if arg.nil?
+
+  return true if arg.match?(/\.\.\.?/) # Range operators: .. or ...
+  return true if arg.match?(/[~^]\d*/) # Ref modifiers: ~, ~2, ^, ^2
+  return true if arg == "HEAD"         # Exact HEAD match
+  return true if arg.match?(/@\{/)     # Reflog: @{1}, @{yesterday}
+
+  false
+end
+
+def normalized_args(argv)
+  return ["--help"] if argv.empty?
+  return ["diff"] + argv if git_range_pattern?(argv.first)
+
+  argv
+end
+
+# Start ace-support-cli with exception-based exit code handling (per ADR-023)
+begin
+  Ace::Support::Cli::Runner.new(Ace::Git::CLI).call(args: normalized_args(ARGV))
+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

data/handbook/guides/version-control/ruby.md

@@ -0,0 +1,41 @@
+# Ruby Version Control Examples
+
+This file provides Ruby-specific examples and considerations related to the main [Version Control Git Guide](../version-control-system-git.g.md).
+
+* **.gitignore:** Ensure standard Ruby/Rails files are ignored (e.g., `log/*`, `tmp/*`, `.bundle/`, `coverage/`,
+  `.env`). Tools like [gitignore.io](https://www.toptal.com/developers/gitignore) can generate good starting points.
+* **Pre-commit Hooks:** Use tools like `overcommit` or `lefthook` to run linters (`RuboCop`), formatters
+  (`RuboCop -a`), and tests (`RSpec`, `Minitest`) before committing.
+* **Dependency Locking:** Always commit `Gemfile.lock` to ensure consistent dependencies across environments.
+* **Branching Strategy:** Standard Git workflows (like Gitflow or GitHub Flow) apply. No Ruby-specific branching requirements.
+
+```yaml
+# Example .overcommit.yml snippet
+PreCommit:
+  RuboCop:
+    enabled: true
+    command: ['bundle', 'exec', 'rubocop', '--parallel']
+  RSpec:
+    enabled: true
+    command: ['bundle', 'exec', 'rspec']
+
+CommitMsg:
+  CapitalizedSubject:
+    enabled: true
+  EmptyMessage:
+    enabled: true
+  TextWidth:
+    enabled: true
+```
+
+```gitignore
+# Example additions to .gitignore for a Ruby project
+/.bundle
+/log/*
+!/log/.keep
+/tmp/*
+!/tmp/.keep
+/coverage/
+*.gem
+.env*
+```

data/handbook/guides/version-control/rust.md

@@ -0,0 +1,49 @@
+# Rust Version Control Examples
+
+This file provides Rust-specific examples and considerations related to the main [Version Control Git Guide](../version-control-system-git.g.md).
+
+* **.gitignore:** Ensure the standard Rust build directory (`target/`) is ignored. Tools like
+  [gitignore.io](https://www.toptal.com/developers/gitignore) are helpful.
+* **Pre-commit Hooks:** Use tools like `husky` (if in a mixed project or preferred) or simple shell script hooks
+  (`.git/hooks/pre-commit`) to run the formatter (`cargo fmt --check`) and linter (`cargo clippy -- -D warnings`)
+  before committing.
+* **Dependency Locking:** Always commit `Cargo.lock` to ensure reproducible builds and consistent dependencies.
+* **Branching Strategy:** Standard Git workflows apply.
+
+```sh
+#!/bin/sh
+# Example .git/hooks/pre-commit script for Rust
+
+echo "Running pre-commit hook..."
+
+# Check formatting
+cargo fmt --check
+if [ $? -ne 0 ]; then
+  echo "Code formatting issues found. Run 'cargo fmt' to fix."
+  exit 1
+fi
+
+# Check linting (deny warnings)
+cargo clippy -- -D warnings
+if [ $? -ne 0 ]; then
+  echo "Clippy issues found. Address them before committing."
+  exit 1
+fi
+
+# Optionally run tests
+# cargo test
+# if [ $? -ne 0 ]; then
+#   echo "Tests failed. Fix tests before committing."
+#   exit 1
+# fi
+
+echo "Pre-commit checks passed."
+exit 0
+```
+
+```gitignore
+# Example additions to .gitignore for a Rust project
+/target
+```
+
+**Note:** Make the pre-commit script executable: `chmod +x .git/hooks/pre-commit`.

data/handbook/guides/version-control/typescript.md

@@ -0,0 +1,47 @@
+# TypeScript Version Control Examples
+
+This file provides TypeScript/Node.js specific examples and considerations related to the main [Version Control Git Guide](../version-control-system-git.g.md).
+
+* **.gitignore:** Ensure standard Node.js/TypeScript files are ignored (e.g., `node_modules/`, `dist/`, `build/`,
+  `.env`, `*.tsbuildinfo`, `coverage/`). Tools like [gitignore.io](https://www.toptal.com/developers/gitignore) can
+  generate good starting points.
+* **Pre-commit Hooks:** Use tools like `husky` with `lint-staged` to run linters (`ESLint`), formatters (`Prettier`),
+  type checkers (`tsc --noEmit`), and tests (`Jest`, `Mocha`) on staged files before committing.
+* **Dependency Locking:** Always commit `package-lock.json` (for npm) or `yarn.lock` (for Yarn) to ensure consistent dependencies.
+* **Branching Strategy:** Standard Git workflows apply.
+
+```json
+// Example .lintstagedrc.json (used with husky)
+{
+  "*.{js,jsx,ts,tsx}": [
+    "eslint --fix",
+    "prettier --write"
+  ],
+  "*.{json,md,yml,yaml}": [
+    "prettier --write"
+  ],
+  "*.ts?(x)": [
+    "bash -c 'tsc --noEmit'"
+  ]
+}
+```
+
+```gitignore
+# Example additions to .gitignore for a TypeScript/Node project
+/node_modules
+/dist
+/build
+/.env*
+*.tsbuildinfo
+/coverage/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+```
+
+```bash
+# Example husky setup command (run once)
+npx husky init && npm install
+# Add hooks like:
+npx husky add .husky/pre-commit "npx lint-staged"
+```