diff --git a/README.md b/README.md index 5c14cd0..9576da1 100644 --- a/README.md +++ b/README.md @@ -4,1459 +4,193 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![CI](https://github.com/erishforG/git-parsec/actions/workflows/ci.yml/badge.svg)](https://github.com/erishforG/git-parsec/actions) -> Git worktree lifecycle manager for parallel AI agent workflows +> **From ticket to PR. One command.** +> Git worktree lifecycle manager — isolated workspaces tied to your tickets, with stacked PRs, multi-forge support, and clean shipping. -**parsec** manages isolated git worktrees tied to tickets (Jira, GitHub Issues), enabling multiple AI agents or developers to work on the same repository in parallel without lock conflicts. - -![demo](demo.gif) - -## What is parsec? - -**parsec** is a command-line tool (CLI) that automates the full lifecycle of git worktrees: create an isolated workspace from a ticket ID, work in parallel without lock conflicts, then push + create PR + clean up in one command. It integrates with **Jira**, **GitHub Issues**, and **GitLab Issues** for automatic ticket title lookup, and supports **GitHub** and **GitLab** for PR/MR creation. - -Unlike plain `git worktree`, parsec tracks workspace state, detects file conflicts across worktrees, provides operation history with undo, supports stacked PRs, and offers CI status monitoring — all from a single CLI. - ---- - -## Why parsec? - -### What changes day-to-day - -| What you do today | With parsec | -|---|---| -| `git checkout -b feat/xyz`, `git worktree add`, configure manually | `parsec start TICKET` | -| `git push`, `gh pr create`, `git worktree remove`, delete branch | `parsec ship TICKET` | -| Open GitHub web UI to check CI results | `parsec ci --watch` | -| Merge PR on GitHub, delete branch, clean local worktree | `parsec merge TICKET` | - -### Key metrics - -- **PR lead time**: Less time between starting a ticket and opening a PR — no setup friction, no stash management -- **Context switches eliminated**: Jump between tickets without losing state; each ticket lives in its own directory -- **Conflict prevention**: `parsec conflicts` catches cross-ticket file collisions before they become merge problems -- **0 `index.lock` conflicts**: Every worktree has its own `.git` index — no serialized writes - -### Use cases - -**Solo developer** — Work on several tickets in parallel without stashing. Ship complete features (push + PR + cleanup) with one command. See all in-flight work at a glance with `parsec list`. - -**Team** — View the active sprint as a Kanban board with `parsec board`. Detect which tickets touch the same files before review. Monitor all open PRs and their CI status from the terminal. - -**AI agent orchestration** — Run multiple coding agents on the same repo simultaneously. Every agent gets its own isolated worktree with no `index.lock` contention. Use `--json` on every command for structured output agents can parse directly. - ---- - -## The Problem - -Git uses a single working directory with a single `index.lock`. When multiple AI agents (or developers) try to work on the same repo simultaneously: - -- `git add/commit` operations collide on `.git/index.lock` -- Context switching between tasks requires stashing or committing WIP -- Worktrees exist but have poor lifecycle management -- No connection between tickets and working directories - -## The Solution - -```bash -# Create isolated workspaces for two tickets -$ parsec start PROJ-1234 --title "Add user authentication" -Created workspace for PROJ-1234 at /home/user/myapp.PROJ-1234 - Add user authentication - -$ parsec start PROJ-5678 --title "Fix payment timeout" -Created workspace for PROJ-5678 at /home/user/myapp.PROJ-5678 - Fix payment timeout - -# See all active workspaces -$ parsec list -╭───────────┬──────────────────────┬────────┬──────────────────┬──────────────────────────────╮ -│ Ticket │ Branch │ Status │ Created │ Path │ -├───────────┼──────────────────────┼────────┼──────────────────┼──────────────────────────────┤ -│ PROJ-1234 │ feature/PROJ-1234 │ active │ 2026-04-15 09:00 │ /home/user/myapp.PROJ-1234 │ -│ PROJ-5678 │ feature/PROJ-5678 │ active │ 2026-04-15 09:01 │ /home/user/myapp.PROJ-5678 │ -╰───────────┴──────────────────────┴────────┴──────────────────┴──────────────────────────────╯ - -# Check if any workspaces touch the same files -$ parsec conflicts -No conflicts detected. - -# Complete: push, create PR, and clean up in one step -$ parsec ship PROJ-1234 -Shipped PROJ-1234! - PR: https://github.com/org/repo/pull/42 - Workspace cleaned up. - -# Remove all remaining workspaces -$ parsec clean --all -Removed 1 worktree(s): - - PROJ-5678 -``` - -## Features - -- **Ticket-driven workspaces** -- Create worktrees named after Jira/GitHub Issues tickets -- **Zero-conflict parallelism** -- Each workspace has its own index, no lock contention -- **Conflict detection** -- Warns when multiple workspaces modify the same files -- **One-step shipping** -- `parsec ship` pushes, creates a GitHub PR or GitLab MR, and cleans up -- **Adopt existing branches** -- Import branches already in progress with `parsec adopt` -- **Attach to existing branches** -- Start a workspace from an existing local or remote branch with `--branch` -- **Operation history and undo** -- `parsec log` shows what happened, `parsec undo` reverts it -- **Keep branches fresh** -- `parsec sync` rebases or merges the latest base branch into any worktree -- **Agent-friendly output** -- `--json` flag on every command for machine consumption -- **Status dashboard** -- See all parallel work at a glance -- **Auto-cleanup** -- Remove worktrees for merged branches automatically -- **GitHub and GitLab** -- PR and MR creation for both platforms -- **Stacked PRs** -- Create dependent PR chains with `--on` and sync the entire stack -- **Sprint board view** -- See the active sprint as a Kanban board with `parsec board` -- **Environment diagnostics** -- `parsec doctor` validates your setup and shows what needs fixing -- **Pre-ship hooks** -- Run custom commands before shipping with configurable `[hooks]` pre_ship -- **Issue creation** -- Create GitHub/Jira issues and start worktrees in one step with `parsec create` -- **Release workflow** -- Merge, tag, and create GitHub Releases with `parsec release` -- **PR reviewers and labels** -- Assign reviewers and labels on ship with `--reviewer`/`--label` or config defaults -- **Stack submit** -- Ship an entire stack in topological order with `parsec stack --submit` -- **Stack navigation comments** -- Auto-posted "← prev / next →" comments on each PR in a stack -- **PR template auto-fill** -- `parsec ship --template` populates the PR description from `.github/PULL_REQUEST_TEMPLATE.md` -- **Compress branch history** -- `parsec compress` squashes a branch's commits into a single tidy commit before shipping -- **Bitbucket Cloud** -- Full PR lifecycle (create, list, view, merge, comments) and Bitbucket Pipelines CI status -- **Offline mode** -- Global `--offline` flag (and `[workspace].offline` config) skips all network operations (tracker, PR, fetch) so parsec keeps working without connectivity -- **Observability** -- Every command run gets an execution ID with per-step timing; `parsec log --export` emits JSONL for tooling and AI agents to consume -- **Config JSON Schema** -- `parsec config schema` outputs a JSON Schema (also published to schemastore.org) so editors auto-complete `config.toml` -- **Draft-by-default** -- `[ship].draft = true` config or `--draft` flag opens PRs as drafts for WIP work -- **Cross-platform** -- Tested on Linux, macOS, and Windows CI; UNC path handling on Windows - ---- - -## Impact - -### Concrete time savings - -The typical "start ticket, work, ship" flow goes from 5+ commands to 2: - -```bash -# Before parsec -git fetch origin -git checkout -b feature/PROJ-1234 origin/main -# ... open browser, look up Jira ticket title ... -git push -u origin feature/PROJ-1234 -gh pr create --title "Add user authentication" --base main -git checkout main -git worktree remove ../myapp.PROJ-1234 - -# With parsec: 2 commands, no browser -parsec start PROJ-1234 # fetches title from Jira automatically -parsec ship PROJ-1234 # push + PR + cleanup in one step -``` - -### Concrete risk reduction - -- **0 `index.lock` conflicts** — worktree isolation is physical; each workspace has its own `.git/index` -- **Conflict detection before it hurts** — `parsec conflicts` shows cross-worktree file overlap before any push -- **Undo for mistakes** — `parsec undo` reverses the last operation (start, ship, clean) - -### Token efficiency for AI agents - -Traditional AI agents waste tokens calling raw APIs. Each Jira or GitHub API call costs dozens of tokens for auth setup, pagination, and response parsing. **parsec packages git + tracker operations into single commands with structured output.** - -#### Before: Raw API Calls - -```bash -# Agent needs: sprint tickets + status + worktree info + PR status -# Step 1: Authenticate with Jira API -# Step 2: Find active sprint (GET /rest/agile/1.0/board/{id}/sprint?state=active) -# Step 3: Fetch sprint issues (GET /rest/agile/1.0/sprint/{id}/issue) -# Step 4: For each ticket, check local worktrees (git worktree list, parse output) -# Step 5: For each ticket, check PR status (GitHub API) -# → 5+ API calls, 100+ tokens, custom parsing logic -``` - -#### After: One parsec Command - -```bash -parsec board --json -# → Sprint + status-grouped tickets + worktree/PR flags in one structured JSON -``` - -#### Key benefits for AI agents - -| Capability | What it means | -|------------|---------------| -| `--json` on every command | Structured output AI can parse instantly | -| `parsec start` | git worktree + Jira fetch + state management in one call | -| `parsec board --json` | Sprint + tickets + worktree/PR status in one call | -| `parsec ship` | Push + PR creation + cleanup in one call | -| Env var defaults | Zero-arg commands after one-time setup | -| Conflict detection | AI agents can check before parallel edits | - ---- - -## Use Cases - -### Solo developer - -Work on multiple tickets in parallel without stashing or losing context. Each ticket lives in its own sibling directory, so switching is just `cd`. - -```bash -parsec start PROJ-1234 # new worktree from Jira ticket -parsec start PROJ-5678 # second worktree, works in parallel -cd $(parsec switch PROJ-1234) -# ... make changes, commit normally ... -parsec ship PROJ-1234 # push + PR + cleanup -``` - -### Team - -Keep the whole team's sprint visible from the terminal. Catch file conflicts before they become merge problems. Track all open PRs without leaving the shell. - -```bash -parsec board # sprint board: In Progress / In Review / Done -parsec conflicts # which tickets touch the same files? -parsec pr-status # CI and review state for all open PRs -parsec ci PROJ-1234 --watch # wait for CI to go green -``` - -### AI agent orchestration - -Run multiple coding agents on the same repo simultaneously. Each agent calls `parsec start` to get an isolated worktree, uses `--json` for structured output, and calls `parsec ship` when done. No `index.lock` contention, no custom shell parsing. - -```bash -# Agent 1 -parsec start PROJ-100 --json # isolated workspace, structured response - -# Agent 2 (same repo, same time) -parsec start PROJ-101 --json # separate worktree, no collision - -# Coordinator -parsec conflicts --json # detect overlap before agents commit -parsec board --json # full sprint + PR status in one call -``` - ---- - -## Installation - -### Pre-built binaries (recommended) - -Download the latest release for your platform from [GitHub Releases](https://github.com/erishforG/git-parsec/releases): - -```bash -# macOS (Apple Silicon) -curl -LO https://github.com/erishforG/git-parsec/releases/latest/download/parsec-{version}-aarch64-apple-darwin.tar.gz -tar xzf parsec-*-aarch64-apple-darwin.tar.gz -sudo mv parsec /usr/local/bin/ - -# macOS (Intel) -curl -LO https://github.com/erishforG/git-parsec/releases/latest/download/parsec-{version}-x86_64-apple-darwin.tar.gz - -# Linux (x86_64) -curl -LO https://github.com/erishforG/git-parsec/releases/latest/download/parsec-{version}-x86_64-unknown-linux-gnu.tar.gz - -# Windows — download .zip from the Releases page -``` - -### Via Cargo - -```bash -cargo install git-parsec -``` - -### Build from source - -```bash -git clone https://github.com/erishforG/git-parsec.git -cd git-parsec -cargo build --release -# Binary at ./target/release/parsec -``` - -## Quick Start - -```bash -# 1. (Optional) Run interactive setup -$ parsec config init - -# 2. Start work on a ticket -$ parsec start PROJ-1234 --title "Add rate limiting" -Created workspace for PROJ-1234 at /home/user/myapp.PROJ-1234 - Add rate limiting - - Tip: cd $(parsec switch PROJ-1234) - -# 3. Switch into the workspace -$ cd $(parsec switch PROJ-1234) - -# 4. Work, commit as normal... -$ git add . && git commit -m "Implement rate limiter" - -# 5. Start a second ticket in parallel -$ parsec start PROJ-5678 --title "Fix auth bug" - -# 6. Check for file conflicts across workspaces -$ parsec conflicts - -# 7. Ship when done -$ parsec ship PROJ-1234 -Shipped PROJ-1234! - PR: https://github.com/org/repo/pull/42 - Workspace cleaned up. - -# 8. See what happened -$ parsec log -``` - ---- - -## Command Reference - -| Command | What it does | -|---------|-------------| -| [`parsec start`](#parsec-start-ticket) | Create an isolated worktree for a ticket | -| [`parsec adopt`](#parsec-adopt-ticket) | Import an existing branch into parsec management | -| [`parsec list`](#parsec-list) | List all active parsec-managed worktrees | -| [`parsec status`](#parsec-status-ticket) | Show detailed status of a workspace | -| [`parsec ticket`](#parsec-ticket-ticket) | View ticket details from the configured tracker | -| [`parsec ship`](#parsec-ship-ticket) | Push, create PR/MR, and clean up in one step | -| [`parsec clean`](#parsec-clean) | Remove worktrees for merged branches | -| [`parsec conflicts`](#parsec-conflicts) | Detect files modified in more than one worktree | -| [`parsec switch`](#parsec-switch-ticket) | Print (or cd to) a ticket's worktree path | -| [`parsec log`](#parsec-log-ticket) | Show operation history | -| [`parsec undo`](#parsec-undo) | Undo the last parsec operation | -| [`parsec sync`](#parsec-sync-ticket) | Rebase/merge latest base branch into a worktree | -| [`parsec open`](#parsec-open-ticket) | Open PR or ticket page in browser | -| [`parsec pr-status`](#parsec-pr-status-ticket) | Check CI and review status of shipped PRs | -| [`parsec ci`](#parsec-ci-ticket---watch---all) | Check CI pipeline status for a PR | -| [`parsec merge`](#parsec-merge-ticket---rebase---no-wait---no-delete-branch) | Merge a PR from the terminal | -| [`parsec diff`](#parsec-diff-ticket---stat---name-only) | View changes vs base branch | -| [`parsec stack`](#parsec-stack---sync---submit) | View and manage stacked PR dependencies | -| [`parsec board`](#parsec-board) | Show sprint as a Kanban board | -| [`parsec init`](#parsec-init) | Install shell integration | -| [`parsec config`](#parsec-config) | Configure parsec | -| [`parsec doctor`](#parsec-doctor) | Validate environment and configuration | -| [`parsec create`](#parsec-create) | Create a new issue and optionally start a worktree | -| [`parsec new-issue`](#parsec-new-issue) | Create a new issue (alias with extra options) | -| [`parsec release`](#parsec-release-version) | Merge, tag, and create a GitHub Release | -| [`parsec rename`](#parsec-rename-ticket---new-ticket-id) | Re-ticket a workspace to a different ticket ID | -| [`parsec compress`](#parsec-compress-ticket--m-message) | Squash all branch commits into one | - ---- - -### `parsec start ` - -Create an isolated worktree for a ticket. Fetches the ticket title from your configured tracker (Jira, GitHub Issues) or accepts a manual title. - -``` -parsec start [--base ] [--title "text"] [--on ] [--branch ] [--hook "cmd"] -``` - -| Option | Description | -|--------|-------------| -| `-b, --base ` | Base branch to create from (default: main/master) | -| `--title "text"` | Set ticket title manually, skip tracker lookup | -| `--on ` | Stack on another ticket's branch (for dependent PRs) | -| `--branch ` | Use an existing branch instead of creating a new one | -| `--hook "cmd"` | Run a command after worktree creation (one-off hook) | - -```bash -# With Jira integration (title auto-fetched) -$ parsec start CL-2283 -Created workspace for CL-2283 at /home/user/myapp.CL-2283 - Implement rate limiting for API endpoints - - Tip: cd $(parsec switch CL-2283) - -# With manual title -$ parsec start 42 --title "Fix login redirect" -Created workspace for 42 at /home/user/myapp.42 - Fix login redirect - - Tip: cd $(parsec switch 42) - -# From a specific base branch -$ parsec start PROJ-99 --base release/2.0 - -# Attach to an existing branch (local or remote) -$ parsec start CL-2208 --branch feature/CL-2208 - -# Attach to a remote-only branch (auto-fetches and tracks) -$ parsec start CL-2208 --branch origin/feature/CL-2208 - -# Run a setup command after creation -$ parsec start PROJ-42 --hook "npm install" -``` - ---- - -### `parsec adopt ` - -Import an existing branch into parsec management. Useful when you started work before using parsec, or when taking over someone else's branch. - -``` -parsec adopt [--branch ] [--title "text"] -``` - -| Option | Description | -|--------|-------------| -| `-b, --branch ` | Branch to adopt (default: ``) | -| `--title "text"` | Set ticket title manually | - -```bash -# Adopt a branch matching the default prefix -$ parsec adopt PROJ-1234 -Adopted branch 'feature/PROJ-1234' as PROJ-1234 at /home/user/myapp.PROJ-1234 - -# Adopt a branch with a different name -$ parsec adopt PROJ-99 --branch fix/payment-timeout -Adopted branch 'fix/payment-timeout' as PROJ-99 at /home/user/myapp.PROJ-99 -``` - ---- - -### `parsec list` - -List all active parsec-managed worktrees. - -``` -parsec list [--full] [--no-pr] -``` - -```bash -$ parsec list -╭────────┬────────────────┬────────┬──────────────────┬────────────────────────────╮ -│ Ticket │ Branch │ Status │ Created │ Path │ -├────────┼────────────────┼────────┼──────────────────┼────────────────────────────┤ -│ TEST-1 │ feature/TEST-1 │ active │ 2026-04-15 09:00 │ /home/user/myapp.TEST-1 │ -│ TEST-2 │ feature/TEST-2 │ active │ 2026-04-15 09:05 │ /home/user/myapp.TEST-2 │ -╰────────┴────────────────┴────────┴──────────────────┴────────────────────────────╯ - -# Show extended metadata per worktree -$ parsec list --full -╭────────┬────────────────┬────────┬──────────────┬──────────┬─────────────────────┬───────────┬────────────────────────────╮ -│ Ticket │ Branch │ Status │ Ahead/Behind │ Unpushed │ Last Commit │ Age │ Path │ -├────────┼────────────────┼────────┼──────────────┼──────────┼─────────────────────┼───────────┼────────────────────────────┤ -│ TEST-1 │ feature/TEST-1 │ active │ +3 / -0 │ 1 │ Add rate limiting │ 2h ago │ /home/user/myapp.TEST-1 │ -│ TEST-2 │ feature/TEST-2 │ active │ +1 / -2 │ 0 │ Fix auth redirect │ 30m ago │ /home/user/myapp.TEST-2 │ -╰────────┴────────────────┴────────┴──────────────┴──────────┴─────────────────────┴───────────┴────────────────────────────╯ - -$ parsec list --json -[{"ticket":"TEST-1","path":"/home/user/myapp.TEST-1","branch":"feature/TEST-1","base_branch":"main","created_at":"2026-04-15T09:00:00Z","ticket_title":"Add auth","status":"active"}] -``` - -| Option | Description | -|--------|-------------| -| `--full` | Show extended metadata (commits, divergence, last commit) | -| `--no-pr` | Skip PR status lookup (faster, works offline) | - ---- - -### `parsec status [ticket]` - -Show detailed status of a workspace. Shows all workspaces if no ticket is specified. - -``` -parsec status [ticket] -``` - -```bash -$ parsec status PROJ-1234 -────────────────────────────────────────────────── - Ticket: PROJ-1234 - Title: Add user authentication - Branch: feature/PROJ-1234 - Base: main - Status: active - Created: 2026-04-15 09:00 UTC - Path: /home/user/myapp.PROJ-1234 -────────────────────────────────────────────────── -``` - ---- - -### `parsec ticket [ticket]` - -View ticket details from the configured tracker. Auto-detects the ticket from the current worktree if no argument is given. - -``` -parsec ticket [ticket] -``` - -```bash -# Auto-detect from current worktree -$ parsec ticket -CL-2283: Implement rate limiting for API endpoints - Status: In Progress - Assignee: eric.signal - URL: https://jira.example.com/browse/CL-2283 - -# Explicit ticket -$ parsec ticket CL-2283 - -# JSON output -$ parsec ticket CL-2283 --json -{"id":"CL-2283","title":"Implement rate limiting","status":"In Progress","assignee":"eric.signal","url":"https://jira.example.com/browse/CL-2283"} -``` - ---- - -### `parsec ship ` - -Push the branch, create a PR (GitHub) or MR (GitLab), and clean up the worktree. The forge is auto-detected from the remote URL. - -``` -parsec ship [--draft] [--no-pr] [--base ] [--skip-hooks] [--reviewer ]... [--label ]... -``` - -| Option | Description | -|--------|-------------| -| `--draft` | Create the PR/MR as a draft | -| `--no-pr` | Push only, skip PR/MR creation | -| `--base ` | Target base branch for PR (overrides config `default_base` and worktree base) | -| `--skip-hooks` | Skip pre-ship hooks defined in config | -| `-r, --reviewer ` | Request review from a GitHub user (repeatable) | -| `-l, --label ` | Add a label to the PR (repeatable) | - -```bash -# Push + PR + cleanup -$ parsec ship PROJ-1234 -Shipped PROJ-1234! - PR: https://github.com/org/repo/pull/42 - Workspace cleaned up. - -# Draft PR -$ parsec ship PROJ-5678 --draft - -# Push only, no PR -$ parsec ship PROJ-9000 --no-pr - -# Ship with reviewers and labels -$ parsec ship PROJ-1234 --reviewer alice --reviewer bob --label "needs-review" -``` - -Reviewers and labels can also be set as defaults in config: - -```toml -[ship] -default_reviewers = ["alice", "bob"] -default_labels = ["team-backend"] -``` - -Token required: set `PARSEC_GITHUB_TOKEN` (or `GITHUB_TOKEN`, `GH_TOKEN`) for GitHub, or `PARSEC_GITLAB_TOKEN` (or `GITLAB_TOKEN`) for GitLab. - ---- - -### `parsec clean` - -Remove worktrees whose branches have been merged. Use `--all` to remove everything. - -``` -parsec clean [--all] [--dry-run] -``` - -| Option | Description | -|--------|-------------| -| `--all` | Remove all worktrees, including unmerged | -| `--dry-run` | Preview what would be removed | - -```bash -# Preview first -$ parsec clean --dry-run -Would remove 1 worktree(s): - - PROJ-1234 - -# Remove merged worktrees -$ parsec clean -Removed 1 worktree(s): - - PROJ-1234 - -# Remove everything -$ parsec clean --all -Removed 3 worktree(s): - - PROJ-1234 - - PROJ-5678 - - PROJ-9000 -``` - ---- - -### `parsec conflicts` - -Detect files modified in more than one active worktree. Workspaces with no changes are skipped. - -``` -parsec conflicts -``` - -```bash -# No conflicts -$ parsec conflicts -No conflicts detected. - -# Conflicts found -$ parsec conflicts -╭──────────────────┬──────────────────────╮ -│ File │ Worktrees │ -├──────────────────┼──────────────────────┤ -│ src/api/router.rs│ PROJ-1234, PROJ-5678 │ -╰──────────────────┴──────────────────────╯ -``` - ---- - -### `parsec switch [ticket]` - -Print the absolute path to a ticket's worktree. When called without a ticket, shows an interactive picker. Designed for `cd $(parsec switch ...)`. - -``` -parsec switch [ticket] -``` - -```bash -# Direct switch -$ parsec switch PROJ-1234 -/home/user/myapp.PROJ-1234 - -# Interactive picker (no argument) -$ parsec switch -? Switch to workspace › -❯ PROJ-1234 — Add user authentication - PROJ-5678 — Fix payment timeout - -# Use with cd -$ cd $(parsec switch PROJ-1234) -``` - ---- - -### `parsec log [ticket]` - -Show the history of parsec operations. Each mutating command (start, adopt, ship, clean, undo) is recorded with a timestamp. - -``` -parsec log [ticket] [-n, --last N] -``` - -| Option | Description | -|--------|-------------| -| `[ticket]` | Filter to a specific ticket | -| `-n, --last N` | Show last N entries (default: 20) | -| `--export` | Emit the log as JSONL (one JSON object per line). Each entry includes execution ID and per-step timing for observability/debugging | - -```bash -$ parsec log -╭───┬───────┬───────────┬───────────────────────────────────────────────┬──────────────────╮ -│ # │ Op │ Ticket │ Detail │ Time │ -├───┼───────┼───────────┼───────────────────────────────────────────────┼──────────────────┤ -│ 4 │ clean │ PROJ-5678 │ Cleaned workspace for branch 'feature/5678' │ 2026-04-15 14:30 │ -│ 3 │ ship │ PROJ-1234 │ Shipped branch 'feature/PROJ-1234' │ 2026-04-15 14:02 │ -│ 2 │ start │ PROJ-5678 │ Created workspace at /home/user/myapp.5678 │ 2026-04-15 13:55 │ -│ 1 │ start │ PROJ-1234 │ Created workspace at /home/user/myapp.1234 │ 2026-04-15 09:14 │ -╰───┴───────┴───────────┴───────────────────────────────────────────────┴──────────────────╯ - -# Filter by ticket -$ parsec log PROJ-1234 - -# Last 3 entries only -$ parsec log --last 3 - -# Export as JSONL (for tooling / AI agents) -$ parsec log --export -{"execution_id":"01HQ3D8R2K8...","op":"start","ticket":"PROJ-1234","steps":[{"name":"fetch_title","ms":214},{"name":"create_worktree","ms":98}],"started_at":"2026-04-15T09:14:01Z","duration_ms":312} -{"execution_id":"01HQ3D9V7Z2...","op":"ship","ticket":"PROJ-1234","steps":[{"name":"push","ms":820},{"name":"create_pr","ms":1305},{"name":"cleanup","ms":42}],"started_at":"2026-04-15T14:02:18Z","duration_ms":2167} -``` - ---- - -### `parsec undo` - -Undo the last parsec operation. - -- Undo `start` or `adopt`: removes the worktree and deletes the branch -- Undo `ship` or `clean`: re-creates the worktree from the branch (if still available locally or on remote) - -``` -parsec undo [--dry-run] -``` - -| Option | Description | -|--------|-------------| -| `--dry-run` | Preview what would be undone | - -```bash -# Preview -$ parsec undo --dry-run -Would undo: start PROJ-5678 - Would remove worktree at /home/user/myapp.PROJ-5678 - Would delete branch 'feature/PROJ-5678' - -# Execute -$ parsec undo -Undid start for PROJ-5678 - Worktree removed. - -# Nothing to undo -$ parsec undo -Error: nothing to undo. Run `parsec log` to see operation history. -``` - ---- - -### `parsec sync [ticket]` - -Fetch the latest base branch and rebase (or merge) the worktree on top. Detects the current worktree automatically when no ticket is given. - -``` -parsec sync [ticket] [--all] [--strategy rebase|merge] -``` - -| Option | Description | -|--------|-------------| -| `--all` | Sync all active worktrees | -| `--strategy` | `rebase` (default) or `merge` | - -```bash -# Sync current worktree -$ parsec sync -✓ rebase 1 worktree(s): - - PROJ-1234 - -# Sync a specific worktree -$ parsec sync PROJ-5678 - -# Sync all worktrees at once -$ parsec sync --all - -# Use merge instead of rebase -$ parsec sync --strategy merge -``` - ---- - -### `parsec open ` - -Open the associated PR/MR or ticket tracker page in your default browser. If the ticket has been shipped, opens the PR by default; otherwise opens the tracker page. - -``` -parsec open [--pr] [--ticket-page] -``` - -| Option | Description | -|--------|-------------| -| `--pr` | Force open the PR/MR page | -| `--ticket-page` | Force open the ticket tracker page | - -```bash -# Open PR if shipped, otherwise ticket page -$ parsec open PROJ-1234 -Opening https://github.com/org/repo/pull/42 - -# Force open the Jira ticket -$ parsec open PROJ-1234 --ticket-page -Opening https://yourcompany.atlassian.net/browse/PROJ-1234 - -# Force open the PR -$ parsec open PROJ-1234 --pr -Opening https://github.com/org/repo/pull/42 -``` - ---- - -### `parsec pr-status [ticket]` - -Check the CI and review status of shipped PRs. Shows CI check results, review approvals, and merge state in a color-coded table. - -``` -parsec pr-status [ticket] -``` +![demo](demo.gif) ```bash -# Check a specific ticket's PR -$ parsec pr-status PROJ-1234 -┌───────────┬─────┬────────┬──────────┬──────────────┐ -│ Ticket │ PR │ State │ CI │ Reviews │ -├───────────┼─────┼────────┼──────────┼──────────────┤ -│ PROJ-1234 │ #42 │ open │ ✓ passed │ ✓ approved │ -└───────────┴─────┴────────┴──────────┴──────────────┘ - -# Check all shipped PRs -$ parsec pr-status - -# JSON output -$ parsec pr-status PROJ-1234 --json +$ parsec start PROJ-1234 # creates worktree, fetches Jira title, sets up branch +$ parsec ship PROJ-1234 # pushes, opens PR, cleans worktree ``` -Requires: `PARSEC_GITHUB_TOKEN` (or `GITHUB_TOKEN`, `GH_TOKEN`) +That's the whole loop. Plain `git worktree` doesn't track state, doesn't talk to your tracker, doesn't open PRs, doesn't clean up. **parsec** does. --- -### `parsec ci [ticket] [--watch] [--all]` - -Check CI/CD pipeline status for a ticket's PR. Shows individual check runs with status, duration, and an overall summary. - -``` -parsec ci [ticket] [--watch] [--all] -``` - -| Option | Description | -|--------|-------------| -| `ticket` | Ticket identifier (auto-detects current worktree if omitted) | -| `--watch` | Poll CI every 5s until all checks complete | -| `--all` | Show CI for all shipped PRs | - -```bash -# Auto-detect from current worktree -$ parsec ci -CI for PROJ-1234 (PR #42, a1b2c3d) -┌────────────┬───────────┬──────────┐ -│ Check │ Status │ Duration │ -├────────────┼───────────┼──────────┤ -│ Tests │ ✓ passed │ 2m 15s │ -│ Build │ ✓ passed │ 1m 42s │ -│ Lint │ ● running │ running… │ -└────────────┴───────────┴──────────┘ -✓ CI: 2/3 — 2 passed, 1 running - -# Check a specific ticket -$ parsec ci PROJ-1234 +## Why use it -# Watch mode — refreshes every 5s until done -$ parsec ci PROJ-1234 --watch - -# All shipped PRs -$ parsec ci --all - -# JSON output -$ parsec ci PROJ-1234 --json -``` - -Requires: `PARSEC_GITHUB_TOKEN` (or `GITHUB_TOKEN`, `GH_TOKEN`) +- **No `index.lock` collisions** — every workspace has its own `.git/index`, so multiple developers (or AI agents) can run `git add` on the same repo at the same time. +- **One command per phase** — `start` (worktree + tracker fetch), `ship` (push + PR + cleanup), `merge` (merge + branch cleanup), `clean` (sweep merged branches). No web UI round-trips. +- **Stacked PRs that don't melt your brain** — `parsec start FOO --on BAR` chains workspaces; `parsec stack --submit` opens the whole stack in topological order with auto-posted "← prev / next →" navigation comments. +- **Cross-worktree conflict detection** — `parsec conflicts` flags files modified in two workspaces *before* anyone pushes. +- **Multi-forge** — GitHub, GitLab, Bitbucket Cloud. Multi-tracker — Jira, GitHub Issues, GitLab Issues, Bitbucket. +- **Agent-friendly** — `--json` on every command, structured error codes, JSONL execution log, headless/offline modes. --- -### `parsec merge [ticket] [--rebase] [--no-wait] [--no-delete-branch]` - -Merge a ticket's PR directly from the terminal. Waits for CI to pass before merging, then cleans up the local worktree. - -``` -parsec merge [ticket] [--rebase] [--no-wait] [--no-delete-branch] -``` - -| Option | Description | -|--------|-------------| -| `ticket` | Ticket identifier (auto-detects current worktree if omitted) | -| `--rebase` | Use rebase merge instead of squash (default: squash) | -| `--no-wait` | Skip CI check before merging | -| `--no-delete-branch` | Keep remote branch after merge | +## Install ```bash -# Squash merge (default) -$ parsec merge PROJ-1234 -Waiting for CI to pass... ✓ -Merged PR #42 for PROJ-1234! - Method: squash - SHA: a1b2c3d - -# Rebase merge -$ parsec merge PROJ-1234 --rebase - -# Skip CI wait -$ parsec merge PROJ-1234 --no-wait - -# JSON output -$ parsec merge PROJ-1234 --json -``` - -Requires: `PARSEC_GITHUB_TOKEN` (or `GITHUB_TOKEN`, `GH_TOKEN`) +# Homebrew / pre-built binary (recommended) +curl -LO https://github.com/erishforG/git-parsec/releases/latest/download/parsec-x86_64-unknown-linux-gnu.tar.gz +tar xzf parsec-*.tar.gz && sudo mv parsec /usr/local/bin/ ---- - -### `parsec diff [ticket] [--stat] [--name-only]` - -View changes in a worktree compared to its base branch. Uses merge-base for accurate comparison. - -``` -parsec diff [ticket] [--stat] [--name-only] +# Cargo (Rust toolchain required) +cargo install git-parsec ``` -| Option | Description | -|--------|-------------| -| `ticket` | Ticket identifier (auto-detects current worktree if omitted) | -| `--stat` | Show file-level summary only | -| `--name-only` | List changed file names only | - -```bash -# Full diff for current worktree -$ parsec diff - -# File summary -$ parsec diff PROJ-1234 --stat - -# Just file names -$ parsec diff --name-only - -# JSON output (changed files list) -$ parsec diff PROJ-1234 --json -``` +Other targets (macOS arm64/x86_64, Windows x86_64) ship on every release — see [Releases](https://github.com/erishforG/git-parsec/releases). After install, run `parsec config init` for the interactive first-time setup, then `parsec doctor` to validate. --- -### `parsec stack [--sync] [--submit]` - -View and manage stacked PR dependencies. Worktrees created with `--on` form a dependency chain. PRs include a **stack navigation table** showing parent/child relationships. - -``` -parsec stack [--sync] [--submit] -``` - -| Option | Description | -|--------|-------------| -| `--sync` | Rebase the entire stack chain | -| `--submit` | Ship the entire stack in topological order (root first) | +## 60-second tour ```bash -# Create a stack -$ parsec start PROJ-1 --title "Add models" -$ parsec start PROJ-2 --on PROJ-1 --title "Add API endpoints" -$ parsec start PROJ-3 --on PROJ-2 --title "Add frontend" +# Pull a ticket from Jira / GitHub / GitLab / Bitbucket and start work +$ parsec start PROJ-1234 +✓ Worktree: ../myapp.PROJ-1234 + Title: Add rate limiting (fetched from Jira) + Branch: feature/PROJ-1234 -# View the dependency graph -$ parsec stack -Stack dependency graph: -└── PROJ-1 Add models - └── PROJ-2 Add API endpoints - └── PROJ-3 Add frontend +# See everything in flight +$ parsec list +╭───────────┬───────────────────┬────────┬─────────────────────────╮ +│ Ticket │ Branch │ Status │ Path │ +├───────────┼───────────────────┼────────┼─────────────────────────┤ +│ PROJ-1234 │ feature/PROJ-1234 │ active │ ../myapp.PROJ-1234 │ +│ PROJ-5678 │ feature/PROJ-5678 │ active │ ../myapp.PROJ-5678 │ +╰───────────┴───────────────────┴────────┴─────────────────────────╯ + +# Hop in (shell integration auto-cd's) +$ parsec switch PROJ-1234 -# Sync the entire stack -$ parsec stack --sync +# Make commits the normal way, then ship — push + PR + cleanup in one shot +$ parsec ship PROJ-1234 +✓ Pushed feature/PROJ-1234 +✓ PR opened: github.com/org/repo/pull/42 +✓ Worktree cleaned up -# Ship creates PRs with correct base branches -$ parsec ship PROJ-1 # PR to main -$ parsec ship PROJ-2 # PR to feature/PROJ-1 -$ parsec ship PROJ-3 # PR to feature/PROJ-2 +# Watch CI without leaving the terminal +$ parsec ci PROJ-1234 --watch -# Or ship the entire stack at once -$ parsec stack --submit -Submitting stack (3 worktrees): - 1. PROJ-1 - 2. PROJ-2 - 3. PROJ-3 -Stack submit complete: 3/3 shipped +# Merge from terminal once CI is green +$ parsec merge PROJ-1234 ``` -Each PR body includes a stack navigation table: - -| | Ticket | Branch | -|---|--------|--------| -| ⬆ Parent | PROJ-1 | `feature/PROJ-1` | -| **➡ Current** | **PROJ-2** | **`feature/PROJ-2`** | -| ⬇ Child | PROJ-3 | `feature/PROJ-3` | - --- -### `parsec board` - -Show the active sprint as a vertical board view. Fetches tickets from Jira grouped by status column, with worktree and PR indicators. - -``` -parsec board [--project ] [--board-id ] [--assignee ] [--all] -``` - -| Option | Description | -|--------|-------------| -| `-p, --project ` | Jira project key (default from env/config) | -| `--board-id ` | Jira board ID (auto-detected from project) | -| `--assignee ` | Filter by assignee (default from env/config) | -| `--all` | Show all tickets (ignore assignee filter) | +## Top features +### 🌿 Stacked PRs that don't melt your brain ```bash -# Show your tickets (with PARSEC_JIRA_ASSIGNEE configured) -$ parsec board - -26.04.06 ~ 26.04.20 - -In Progress (3) - CL-2283 [wt] 로그 분석 서비스 개발 - CL-2284 [wt] FDE 대시보드 관련 - CL-2291 반품 요청 API 개발 - -In Review (2) - CL-2281 [pr] ai 커피챗 준비 - CL-2280 이관 요청할 API 정리 - -# Show all team tickets -$ parsec board --all - -# JSON output for AI agents -$ parsec board --json -{"sprint":{"id":123,"name":"...","start":"...","end":"..."},"total_count":48,"columns":{"In Progress":[...],...}} +$ parsec start PROJ-2 --on PROJ-1 # new worktree on top of PROJ-1's branch +$ parsec stack --submit # open all PRs in the stack, root first ``` +parsec auto-posts `← previous PR` / `next PR →` navigation comments so reviewers can walk the chain. -Defaults can be set via environment variables or config file (see below). - ---- - -### `parsec init` +### 🔄 Multi-forge, multi-tracker +- **Forges**: GitHub · GitLab · Bitbucket Cloud (full PR lifecycle on each) +- **Trackers**: Jira · GitHub Issues · GitLab Issues · Bitbucket +- **CI status**: GitHub Actions · GitLab CI · Bitbucket Pipelines -Output or install shell integration for auto-cd on `parsec switch` and CWD recovery after `parsec merge`. +`parsec ci` and `pr-status` work the same shape across all of them. -``` -parsec init [shell] [--install] [--yes] -``` +### 🤖 Agent-friendly by design +Every command has `--json`. Errors emit structured codes (E001…E013). `parsec log --export` outputs JSONL with execution IDs and per-step timing for tooling/agents to consume. `--offline` and `[behavior].offline` config skip all network ops for air-gapped or CI environments. -| Option | Description | -|--------|-------------| -| `shell` | Shell type: `zsh` (default) or `bash` | -| `--install` | Auto-append integration to shell config file | -| `-y, --yes` | Skip confirmation prompt (for scripting) | +### 🧹 Lifecycle hygiene +`parsec clean` sweeps worktrees for already-merged branches. `parsec conflicts` flags cross-worktree file overlap before you push. `parsec undo` reverses the last operation (start, ship, clean). `parsec doctor` validates every part of your setup with actionable fix instructions. -```bash -# Print the shell function (pipe to eval) -$ parsec init zsh +### 📂 Worktree build cache sharing +`[worktree].shared_cache = ["target", "node_modules", ".venv"]` lets new worktrees reuse the main repo's caches via symlink (default) or copy. Eliminates cold-build cost on `parsec start` for any project with significant dependency caches. -# Auto-install into ~/.zshrc -$ parsec init --install -Add shell integration to /home/user/.zshrc? [Y/n] y -Shell integration added. Run `source ~/.zshrc` or restart your shell. +### 📋 Sprint board + issue creation +`parsec board` turns your active sprint into a Kanban board in the terminal. `parsec create` and `parsec new-issue` open issues in your tracker without leaving the shell. -# Non-interactive install -$ parsec init --install --yes -``` +> 27 commands total — see the [full command reference](https://erishforg.github.io/git-parsec/reference/) for every flag and example. --- -### `parsec config` - -```bash -# Interactive setup wizard -$ parsec config init - -# Show current configuration -$ parsec config show -[workspace] - layout = sibling - base_dir = .parsec/workspaces - branch_prefix = feature/ - -[tracker] - provider = jira - jira.base_url = https://yourcompany.atlassian.net - -[ship] - auto_pr = true - auto_cleanup = true - draft = false - # default_base = "develop" # Target branch for PRs (default: worktree base) - -# Output shell integration script -$ parsec config shell zsh - -# Generate shell completions -$ parsec config completions zsh - -# Install man page -$ sudo parsec config man - -# Output the JSON Schema for config.toml (also published to schemastore.org) -$ parsec config schema > parsec-schema.json -``` - -The JSON Schema is published to **schemastore.org** so editors with schemastore integration (VS Code, IntelliJ, Helix) auto-complete and validate `~/.config/parsec/config.toml` and per-repo `.parsec.toml` automatically. To pin the schema locally instead, add to your config: +## Configuration (minimal example) ```toml # ~/.config/parsec/config.toml #:schema https://json.schemastore.org/parsec.json -``` - ---- - -### `parsec doctor` - -Validate your environment and configuration. Prints ✓/✗ for each check with actionable fix instructions. - -```bash -$ parsec doctor -parsec doctor - ✓ git version 2.43.0 (worktree support ok) - ✓ config file found at ~/.config/parsec/config.toml - ✓ GitHub token configured (github.com) via gh auth token - ✗ shell integration not found in shell config - Add to ~/.zshrc: eval "$(parsec init zsh)" - ✗ tab completions not configured - Add to ~/.zshrc: eval "$(parsec config completions zsh)" - ✓ remote origin accessible - -2 check(s) failed. - -$ parsec doctor --json -{"checks":[...],"all_ok":false} -``` - -**AI agent mode** — output parsec workflow rules as a Markdown document for AI agents to consume: - -```bash -$ parsec doctor --ai -# Outputs structured Markdown with workflow rules, command patterns, -# and best practices for AI agents using parsec -``` - ---- - -### `parsec create` - -Create a new issue on the configured tracker (GitHub Issues or Jira) and optionally start a worktree for it immediately. - -``` -parsec create --title "text" [--body "text"] [--label "a,b"] [--project KEY] [--start] -``` - -| Option | Description | -|--------|-------------| -| `--title "text"` | Issue title (required) | -| `--body "text"` | Issue body/description | -| `--label "a,b"` | Comma-separated labels | -| `-p, --project KEY` | Jira project key (auto-detected from config) | -| `--start` | Start a worktree after creation | - -```bash -# Create a GitHub issue -$ parsec create --title "Fix login redirect" --label "bug" -Created #145: Fix login redirect - https://github.com/org/repo/issues/145 - -# Create and immediately start working -$ parsec create --title "Add caching layer" --start -Created #146: Add caching layer -Created workspace for #146 at /home/user/myapp.146 -``` - ---- - -### `parsec new-issue` - -Create a new issue on the tracker (alias for `create` with additional options). Supports GitHub Issues and Jira with configurable issue type. - -``` -parsec new-issue --title "text" [--body "text"] [--label "a"] [--project KEY] [--issue-type TYPE] [--start] -``` - -| Option | Description | -|--------|-------------| -| `--title "text"` | Issue title (required) | -| `--body "text"` | Issue body/description | -| `--label "a"` | Labels (can be specified multiple times) | -| `-p, --project KEY` | Jira project key (auto-detected from config) | -| `--issue-type TYPE` | Jira issue type (default: Task) | -| `--start` | Auto-start a worktree for the new issue | - -```bash -# Create with issue type for Jira -$ parsec new-issue --title "Implement API caching" --issue-type Story --project CL - -# Multiple labels -$ parsec new-issue --title "Fix auth bug" --label bug --label priority -``` - ---- - -### `parsec release ` - -Create a release: merge develop to main, create a git tag, and optionally create a GitHub Release with auto-generated changelog. - -``` -parsec release [--from ] [--no-github-release] [--dry-run] -``` - -| Option | Description | -|--------|-------------| -| `` | Version string (e.g., "0.3.0") | -| `--from ` | Source branch to release from (default: develop) | -| `--no-github-release` | Skip creating GitHub Release | -| `--dry-run` | Show what would happen without making changes | - -```bash -# Full release -$ parsec release 0.3.0 -✓ Merged develop → main -✓ Tagged v0.3.0 -✓ GitHub Release created: https://github.com/org/repo/releases/tag/v0.3.0 - -# Dry run first -$ parsec release 0.4.0 --dry-run - -# Skip GitHub Release -$ parsec release 0.3.1 --no-github-release -``` - ---- - -### `parsec rename --new ` - -Re-ticket an existing workspace to a different ticket ID. Renames the branch and updates internal state. Useful when a ticket is split or re-assigned. - -``` -parsec rename --new -``` - -| Option | Description | -|--------|-------------| -| `--new ` | New ticket ID to assign (required) | - -```bash -# Re-ticket a workspace -$ parsec rename PROJ-100 --new PROJ-200 -Renamed PROJ-100 → PROJ-200 - Branch: feature/PROJ-100 → feature/PROJ-200 - Path: /home/user/myapp.PROJ-200 - -# JSON output -$ parsec rename PROJ-100 --new PROJ-200 --json -``` - ---- - -### `parsec compress [ticket] [-m ]` - -Squash all of a branch's commits into a single tidy commit before shipping. The branch is reset to the merge-base with the base branch and the cumulative changes are re-committed as one. Co-author trailers from squashed commits are preserved. - -``` -parsec compress [ticket] [-m ] -``` - -| Option | Description | -|--------|-------------| -| `ticket` | Optional. Auto-detects the current worktree's ticket if omitted. | -| `-m, --message ` | Custom commit message. Default: combines all squashed commit messages. | - -```bash -# Compress the current worktree's branch -$ parsec compress -Compressed 7 commits into one on feature/PROJ-1234. - -# Compress a specific ticket with a custom message -$ parsec compress PROJ-1234 -m "feat: add user authentication" - -# Combine with ship -$ parsec compress && parsec ship -``` - ---- - -## Global Flags - -These flags work on every command: - -| Flag | Description | -|------|-------------| -| `--dry-run` | Preview what a command would do without making changes | -| `--offline` | Skip all network operations (tracker, PR, fetch). Also enabled by `[workspace].offline = true` in config | -| `--json` | Machine-readable JSON output | -| `-q, --quiet` | Suppress non-essential output | -| `--repo ` | Target a different repository | - -```bash -$ parsec list --json -$ parsec ship PROJ-1234 --quiet -$ parsec status --repo /path/to/other-repo -``` - ---- - -## Shell Integration - -`parsec switch` prints a path but cannot `cd` for you. The shell integration wraps `parsec switch` so it changes your directory automatically: - -```bash -# Preferred: auto-install (appends to your shell config with confirmation) -$ parsec init --install -Add shell integration to /home/user/.zshrc? [Y/n] y -Shell integration added to /home/user/.zshrc. Run `source ~/.zshrc` or restart your shell. - -# Or with --yes for scripted setup -$ parsec init --install --yes - -# Manual: add to ~/.zshrc yourself -eval "$(parsec init zsh)" - -# Or for bash -eval "$(parsec init bash)" -``` - -After sourcing, `parsec switch ` will `cd` into the worktree directly: - -```bash -$ parsec switch PROJ-1234 -# Now you're in /home/user/myapp.PROJ-1234 -``` - ---- - -## Shell Completions - -Generate tab-completion scripts for your shell: - -```bash -# Zsh — add to ~/.zshrc -eval "$(parsec config completions zsh)" - -# Bash — add to ~/.bashrc -eval "$(parsec config completions bash)" - -# Fish — add to ~/.config/fish/config.fish -parsec config completions fish | source - -# Other shells -parsec config completions elvish -parsec config completions powershell -``` - ---- - -## Man Page - -Install the man page so `man parsec` works: - -```bash -sudo parsec config man -# Man page installed to /usr/local/share/man/man1/parsec.1 - -# Custom directory -parsec config man --dir ~/.local/share/man -``` - ---- - -## Configuration - -Config file: `~/.config/parsec/config.toml` -```toml [workspace] -# "sibling" (default) creates worktrees next to repo: ../repo.ticket/ -# "internal" creates inside repo: .parsec/workspaces/ticket/ -layout = "sibling" -base_dir = ".parsec/workspaces" -branch_prefix = "feature/" -# Skip all network operations (tracker, PR, fetch). Equivalent to passing -# --offline on every command. Useful for air-gapped / flight-mode dev. -offline = false - -[worktree] -# Directories to share from the main repo into new worktrees so that -# `parsec start` doesn't trigger a cold rebuild. Default is empty (no sharing). -shared_cache = ["target", "node_modules", ".venv"] -# "symlink" (default): fast, zero-disk overhead. All worktrees and the main -# repo share one cache — running parallel builds of the -# same artifact may race. -# "copy": full copy at start time. Each worktree gets an independent cache, -# no race risk, but uses more disk and the initial copy takes time. -cache_strategy = "symlink" +layout = "sibling" # ../repo.ticket/ (alt: "internal") +branch_prefix = "feature/" +offline = false # true = skip all network ops [tracker] -# "jira" | "github" | "gitlab" | "bitbucket" | "none" -provider = "jira" +provider = "jira" # jira | github | gitlab | bitbucket | none [tracker.jira] base_url = "https://yourcompany.atlassian.net" -# Auth: PARSEC_JIRA_TOKEN or JIRA_PAT env var -# project = "CL" # Default project for board -# board_id = 123 # Default board ID -# assignee = "eric.signal" # Default assignee filter - -[tracker.gitlab] -base_url = "https://gitlab.com" -# Auth: PARSEC_GITLAB_TOKEN env var +# Auth: PARSEC_JIRA_TOKEN env var -[tracker.bitbucket] -# workspace = "your-bitbucket-workspace" -# Auth: PARSEC_BITBUCKET_TOKEN (or BITBUCKET_TOKEN) env var -# api_base override: PARSEC_BITBUCKET_API_BASE env var +[ship] +auto_pr = true +auto_cleanup = true +draft = false # true = open PRs as drafts +# template = ".github/PULL_REQUEST_TEMPLATE.md" -[forge] -# Auto-detected from the remote URL when omitted. Override here if multiple -# forges are reachable (e.g., GitHub for PRs, Bitbucket Pipelines for CI). -# provider = "github" | "gitlab" | "bitbucket" +[worktree] +shared_cache = ["target", "node_modules", ".venv"] +cache_strategy = "symlink" # alt: "copy" +``` -[ship] -auto_pr = true # Create PR/MR on ship -auto_cleanup = true # Remove worktree after ship -draft = false # Open PRs as drafts by default -# template = ".github/PULL_REQUEST_TEMPLATE.md" # Auto-fill PR description -# default_reviewers = ["alice", "bob"] # Reviewers added on every ship -# default_labels = ["needs-review"] # Labels added on every ship +**Auth tokens** (set via env vars, all optional): -[observability] -# Enable per-step timing in `parsec log --export` JSONL output. -# Each command run gets a unique execution ID; useful for tooling and AI -# agents to correlate parsec actions with downstream effects. -enabled = true +``` +PARSEC_JIRA_TOKEN PARSEC_GITHUB_TOKEN PARSEC_GITLAB_TOKEN +PARSEC_BITBUCKET_TOKEN GITHUB_TOKEN (fallback) GITLAB_TOKEN (fallback) +PARSEC_OFFLINE=1 — force offline mode globally +``` -[hooks] -# Commands to run in new worktrees after creation -post_create = ["npm install"] -# Commands to run before shipping (pre-push hooks) -pre_ship = ["cargo test", "cargo clippy"] +Full schema and every option: `parsec config schema` (also published to [schemastore.org](https://schemastore.org)). -[release] -# branch = "main" # Target release branch (default: main) -# tag_prefix = "v" # Tag prefix (default: "v") -# changelog = true # Generate changelog in release notes +--- -[policy] -# protected_branches = ["main", "develop", "release/*"] # Branches that cannot be shipped to -# allowed_ship_targets = ["develop"] # Restrict PR target branches -# require_ci = false # Require CI pass before merge +## Comparison -[tracker.auto_transition] -# on_start = "In Progress" # Transition when `parsec start` runs -# on_ship = "In Review" # Transition when `parsec ship` runs -# on_merge = "Done" # Transition when `parsec merge` runs -``` +| | parsec | GitButler | worktrunk | git worktree | git-town | +|---|---|---|---|---|---| +| Tracker integration | Jira + GitHub + GitLab + Bitbucket | — | — | — | — | +| Physical worktree isolation | ✅ | ❌ (virtual) | ✅ | ✅ | ❌ | +| Cross-worktree conflict detection | ✅ | n/a | ❌ | ❌ | ❌ | +| One-step ship (push + PR + cleanup) | ✅ | ❌ | ❌ | ❌ | ✅ | +| Forges | GitHub + GitLab + Bitbucket | Both | GitHub | — | GitHub, GitLab, Gitea, Bitbucket | +| CI integrations | Actions + GitLab CI + Bitbucket Pipelines | — | — | — | — | +| Operation log + undo | ✅ | ✅ | ❌ | ❌ | partial | +| JSON output | ✅ | ✅ | ❌ | ❌ | ❌ | +| Stacked PRs | ✅ | ✅ | ❌ | ❌ | ✅ | +| GUI | CLI only | Desktop + TUI | CLI | CLI | CLI | --- -## Environment Variables - -| Variable | Description | -|----------|-------------| -| `PARSEC_JIRA_TOKEN` | Jira API token (or personal access token) | -| `JIRA_PAT` | Alternative Jira token variable | -| `JIRA_BASE_URL` | Jira URL (overrides config) | -| `PARSEC_GITHUB_TOKEN` | GitHub token for PR creation | -| `GITHUB_TOKEN` | Fallback GitHub token | -| `GH_TOKEN` | Fallback GitHub token | -| `PARSEC_GITLAB_TOKEN` | GitLab token for MR creation | -| `GITLAB_TOKEN` | Fallback GitLab token | -| `PARSEC_BITBUCKET_TOKEN` | Bitbucket Cloud app password / access token | -| `BITBUCKET_TOKEN` | Fallback Bitbucket token | -| `PARSEC_BITBUCKET_API_BASE` | Override Bitbucket API base URL (test/mock servers) | -| `PARSEC_JIRA_PROJECT` | Default Jira project key for `board` | -| `PARSEC_JIRA_BOARD_ID` | Default Jira board ID for `board` | -| `PARSEC_JIRA_ASSIGNEE` | Default assignee filter for `board` | -| `PARSEC_OFFLINE` | Set to `1` to force offline mode (same as `--offline`) | +## Documentation -Token priority: `PARSEC_*_TOKEN` > platform-specific variables. +- 📘 **[Getting Started Guide](https://erishforg.github.io/git-parsec/guide/)** — install, first ship, tracker config, recipes +- 📗 **[Command Reference](https://erishforg.github.io/git-parsec/reference/)** — every command, every flag, with examples +- 🌐 **[Project home](https://erishforg.github.io/git-parsec/)** — features tour and live demo --- -## Error Codes +## Error codes -When using `--json`, errors include a structured error code for programmatic handling: +Every command exits with a structured code. JSON output (`--json`) includes the same code: -| Code | Meaning | Exit Code | -|------|---------|-----------| -| E001 | No authentication token configured | 2 | -| E002 | CI checks failing | 4 | -| E003 | Merge conflicts detected | 3 | -| E004 | PR not mergeable | 5 | -| E005 | Workspace not found | 5 | -| E006 | Workspace already exists | 5 | -| E007 | No active workspaces | 5 | -| E008 | Pre-ship hook failed | 1 | -| E009 | Policy violation | 6 | -| E010 | PR not found | 5 | -| E011 | Tracker not configured | 2 | -| E012 | Ship partially completed | 1 | -| E013 | Cannot undo operation | 1 | +| | | | +|---|---|---| +| `E001` no auth token | `E005` workspace not found | `E009` policy violation | +| `E002` CI failing | `E006` workspace already exists | `E010` PR not found | +| `E003` merge conflict | `E007` no active workspaces | `E011` tracker not configured | +| `E004` PR not mergeable | `E008` pre-ship hook failed | `E012` ship partial | +| | | `E013` cannot undo | ```bash -# JSON error output example $ parsec ship PROJ-1234 --json 2>&1 {"error":{"code":"E001","message":"No GitHub token configured","hint":"Set PARSEC_GITHUB_TOKEN or run gh auth login"}} $ echo $? @@ -1465,63 +199,6 @@ $ echo $? --- -## Comparison with Alternatives - -| Feature | parsec | GitButler | worktrunk | git worktree | git-town | -|---------|--------|-----------|-----------|--------------|----------| -| Ticket tracker integration | Jira + GitHub + GitLab + Bitbucket | No | No | No | No | -| Physical isolation | Yes (worktrees) | No (virtual branches) | Yes (worktrees) | Yes | No | -| Conflict detection | Cross-worktree | N/A | No | No | No | -| One-step ship (push+PR+clean) | Yes | No | No | No | Yes | -| Forges | GitHub + GitLab + Bitbucket | Both | GitHub | No | GitHub, GitLab, Gitea, Bitbucket | -| CI integrations | GitHub Actions + GitLab CI + Bitbucket Pipelines | No | No | No | No | -| Operation history + undo | Yes | Yes | No | No | Yes (undo) | -| JSON output | Yes | Yes | No | No | No | -| CI monitoring | Yes (--watch) | No | No | No | No | -| Stacked PRs | Yes | Yes | No | No | Yes | -| Auto-cleanup merged | Yes | No | No | Manual | No | -| Post-create hooks | Yes | No | Yes | No | No | -| Issue creation from CLI | Yes | No | No | No | No | -| AI token efficiency | Single-command ops | N/A | N/A | N/A | N/A | -| GUI | CLI only | Desktop + TUI | CLI | CLI | CLI | -| Zero config start | Yes | No | Yes | No | No | - ---- - -## FAQ - -**How do I set up parsec with Jira?** -Set `PARSEC_JIRA_TOKEN` (or `JIRA_PAT`) and configure `[tracker.jira]` in `~/.config/parsec/config.toml` with your `base_url` and `project`. Run `parsec config init` for interactive setup, or `parsec doctor` to validate. - -**How do I set up parsec with GitHub Issues?** -Set `provider = "github"` under `[tracker]` in your config. Authentication uses `PARSEC_GITHUB_TOKEN`, `GITHUB_TOKEN`, `GH_TOKEN`, or `gh auth token` automatically. - -**Does parsec support GitLab?** -Yes. parsec supports GitLab for both issue tracking and MR creation. Set `provider = "gitlab"` and configure `[tracker.gitlab]` with your `base_url`. Set `PARSEC_GITLAB_TOKEN` for authentication. - -**Can I use parsec without a ticket tracker?** -Yes. Set `provider = "none"` or use `--title` with `parsec start` to skip tracker lookup entirely. - -**How do stacked PRs work?** -Use `parsec start CHILD --on PARENT` to create dependent worktrees. `parsec ship` automatically sets the correct base branch. `parsec stack --sync` rebases the entire chain. - -**What happens if two worktrees modify the same file?** -`parsec conflicts` detects cross-worktree file overlap before you push. It compares changed files across all active worktrees and warns about collisions. - -**Can I undo a ship or clean?** -Yes. `parsec undo` reverses the last operation. For `ship`, it re-creates the worktree from the branch. For `clean`, it restores from the remote branch if still available. - -**How do I protect branches from accidental shipping?** -Add a `[policy]` section to your config with `protected_branches` and `allowed_ship_targets`. parsec will reject operations that violate these rules. - -**Does parsec work with GitHub Enterprise?** -Yes. parsec auto-detects GitHub Enterprise from the remote URL and routes API calls to the correct host. Token resolution is host-aware. - -**How do AI agents use parsec?** -Every command supports `--json` for structured output. Run `parsec doctor --ai` to get a Markdown document with workflow rules and command patterns optimized for AI agent consumption. - ---- - ## License -MIT +MIT — see [LICENSE](LICENSE). diff --git a/docs/guide/index.html b/docs/guide/index.html index 6d18d77..f73627d 100644 --- a/docs/guide/index.html +++ b/docs/guide/index.html @@ -3,16 +3,64 @@ - Guide — git-parsec - - + Getting Started Guide — git-parsec | Install, configure, ship in 5 minutes + + - + + - - + + + + + + + + + + + + + + + @@ -1019,33 +1067,6 @@ } .version-banner a:hover { color: var(--accent-cyan); } - - - - - @@ -1087,7 +1108,7 @@
  • AI Agent Workflows
  • Stacked PRs
  • New Features
    • -
  • What's New in v0.4
    • +
  • Recipes & Examples
    • @@ -1740,14 +1761,14 @@

    Pre-ship hooks

    -
    +
    -

    What's New in v0.4

    - # +

    Recipes & Examples

    + #

    - v0.4 broadens forge support to Bitbucket Cloud, adds workflow utilities (compress, --template, stack navigation comments), and introduces operational primitives — offline mode, observability JSONL, and a published config schema — designed for tooling and AI agents. + End-to-end examples for the workflow patterns parsec is built around — Bitbucket Cloud setup, history compression, stacked PR navigation, PR templates, offline / headless mode, observability via JSONL, editor autocomplete via the JSON Schema, and worktree build cache sharing. Each recipe is self-contained — copy the snippets and adapt to your repo.

    Bitbucket Cloud — full PR lifecycle

    diff --git a/docs/index.html b/docs/index.html index 5beba37..a12bcf4 100644 --- a/docs/index.html +++ b/docs/index.html @@ -3,36 +3,52 @@ - git-parsec — Full-lifecycle worktree management - - + git-parsec — From ticket to PR. One command. | Git worktree lifecycle manager + + + - - + + + + + + + - - + + + + + + + + + + @@ -926,19 +973,6 @@ } .version-banner a:hover { color: var(--accent-cyan); } - - - - diff --git a/docs/robots.txt b/docs/robots.txt index 4e53dda..891fa51 100644 --- a/docs/robots.txt +++ b/docs/robots.txt @@ -1,4 +1,27 @@ User-agent: * Allow: / +# Explicitly welcome major AI/LLM crawlers — git-parsec is open-source +# and benefits from being surfaced in AI-generated answers. +User-agent: GPTBot +Allow: / + +User-agent: ChatGPT-User +Allow: / + +User-agent: ClaudeBot +Allow: / + +User-agent: anthropic-ai +Allow: / + +User-agent: PerplexityBot +Allow: / + +User-agent: Google-Extended +Allow: / + +User-agent: CCBot +Allow: / + Sitemap: https://erishforg.github.io/git-parsec/sitemap.xml diff --git a/docs/sitemap.xml b/docs/sitemap.xml index 380a220..47968a2 100644 --- a/docs/sitemap.xml +++ b/docs/sitemap.xml @@ -2,22 +2,34 @@ https://erishforg.github.io/git-parsec/ - 2026-04-22 + 2026-05-04 weekly 1.0 https://erishforg.github.io/git-parsec/guide/ - 2026-04-22 + 2026-05-04 weekly 0.8 https://erishforg.github.io/git-parsec/reference/ - 2026-04-22 + 2026-05-04 weekly 0.8 + + https://erishforg.github.io/git-parsec/llms.txt + 2026-05-04 + weekly + 0.7 + + + https://erishforg.github.io/git-parsec/llms-full.txt + 2026-05-04 + weekly + 0.7 + https://erishforg.github.io/git-parsec/v/0.3.3/ 2026-04-23