diff --git a/docs/sitemap.xml b/docs/sitemap.xml index 47968a2..13887fc 100644 --- a/docs/sitemap.xml +++ b/docs/sitemap.xml @@ -30,6 +30,24 @@ weekly 0.7 + + https://erishforg.github.io/git-parsec/v/0.4.0/ + 2026-05-04 + never + 0.3 + + + https://erishforg.github.io/git-parsec/v/0.4.0/guide/ + 2026-05-04 + never + 0.3 + + + https://erishforg.github.io/git-parsec/v/0.4.0/reference/ + 2026-05-04 + never + 0.3 + https://erishforg.github.io/git-parsec/v/0.3.3/ 2026-04-23 diff --git a/docs/v/0.4.0/guide/index.html b/docs/v/0.4.0/guide/index.html new file mode 100644 index 0000000..5093b0d --- /dev/null +++ b/docs/v/0.4.0/guide/index.html @@ -0,0 +1,1987 @@ + + + + + + + Getting Started Guide — git-parsec | Install, configure, ship in 5 minutes + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+
+ + +
+
Documentation
+

Getting Started

+

+ Everything you need to go from zero to shipping PRs with parsec. Installation, configuration, and key workflows explained. +

+
+ + +
+
+

Installation

+ # +
+ +

+ parsec is a single Rust binary with no runtime dependencies. Install via cargo, or build from source. +

+ +

Via cargo (recommended)

+

+ The fastest path. Requires Rust and cargo to be installed. +

+ +
+
+
+ install via cargo +
+
+$ cargo install git-parsec + Compiling git-parsec v0.2.4 +✓ Installed ~/.cargo/bin/parsec +  +# Verify installation +$ parsec --version + parsec 0.3.3 +
+
+ +

Build from source

+

+ Clone the repository and build with cargo build --release. The compiled binary is at ./target/release/parsec. +

+ +
+
+
+ build from source +
+
+$ git clone https://github.com/erishforG/git-parsec.git +$ cd git-parsec +$ cargo build --release +✓ Binary at ./target/release/parsec +  +# Move to a directory on your $PATH +$ cp ./target/release/parsec /usr/local/bin/ +
+
+ +

Shell completions

+

+ Generate tab completions for your shell. Completions cover all commands and flags. +

+ +
+
+
+ shell completions +
+
+# zsh — add to fpath +$ parsec config completions zsh > ~/.zsh/completions/_parsec +  +# bash +$ parsec config completions bash > ~/.local/share/bash-completion/completions/parsec +  +# fish +$ parsec config completions fish > ~/.config/fish/completions/parsec.fish +
+
+
+ + +
+
+

Shell Integration

+ # +
+ +

+ Shell integration is the single most impactful quality-of-life improvement parsec offers. It hooks into your shell to enable seamless directory switching and automatic working-directory recovery. +

+ +
+
+
+ enable shell integration +
+
+# Add to ~/.zshrc (or ~/.bashrc for bash) +eval "$(parsec init zsh)" +  +# Reload your shell +$ source ~/.zshrc +
+
+ +

What shell integration does

+ +
    +
  1. +
    1
    +
    +

    Auto-cd on switch

    +

    When you run parsec switch TICKET, your shell automatically changes directory into the worktree. Without integration, parsec can only print the path — your shell script would need to call cd $(parsec switch TICKET) manually.

    +
    +
    2. +
  2. +
    2
    +
    +

    CWD recovery after merge/clean

    +

    When parsec removes a worktree you're currently inside (e.g. after parsec merge), your shell would normally be stranded in a deleted directory. Shell integration detects this and automatically moves you back to the main repository root.

    +
    +
    3. +
+ +
+
✓
+
+
Recommended for all users
+

Shell integration has no downsides and makes the switch/merge workflow significantly smoother. Add the eval line to your rc file during first-time setup.

+
+
+
+ + +
+
+

Quick Start Workflow

+ # +
+ +

+ The core parsec lifecycle follows a simple loop: start → code → ship → merge → clean. Each step is one command. +

+ +
+
+
start
+
create workspace
+
+
→
+
+
code
+
work & commit
+
+
→
+
+
ship
+
push + open PR
+
+
→
+
+
merge
+
merge PR
+
+
→
+
+
clean
+
remove worktrees
+
+
+ +
+
+
+ full lifecycle demo +
+
+# 1. Create an isolated workspace from a Jira ticket +$ parsec start PROJ-123 +✓ Created worktree for PROJ-123 + Branch: feature/PROJ-123 + Path: ../myrepo.PROJ-123 +  +# 2. Switch into the worktree (auto-cd with shell integration) +$ parsec switch PROJ-123 +# shell: → cd ../myrepo.PROJ-123 +  +# 3. Do your work, commit as usual +$ git add . && git commit -m "feat: auth flow" +  +# 4. Check for conflicts with parallel work +$ parsec conflicts +✓ No conflicts across 3 worktrees +  +# 5. Ship: push + open PR + clean worktree +$ parsec ship PROJ-123 +✓ Pushed feature/PROJ-123 (3 commits) +✓ PR #42 created: github.com/org/myrepo/pull/42 +✓ Worktree cleaned up +  +# 6. After review — merge and clean up remote branch +$ parsec merge PROJ-123 +✓ PR #42 merged into main +  +# 7. Tidy up any remaining worktrees +$ parsec clean +✓ Removed 1 merged worktree +
+
+ +
+
ⓘ
+
+
First-time setup
+

Before running parsec start for the first time, run parsec config init to configure your issue tracker and GitHub token. See Tracker Configuration below.

+
+
+
+ + +
+
+

Tracker Configuration

+ # +
+ +

+ parsec integrates with three issue trackers. Run parsec config init for an interactive setup wizard, or edit ~/.config/parsec/config.toml directly. +

+ +
+
+

Jira

+

Connect to Jira Cloud or Jira Server. parsec fetches ticket titles, statuses, and assignees automatically.

+ Cloud & Server +
+
+

GitHub Issues

+

Works out of the box when your remote is GitHub. Uses the same token as your GitHub API access.

+ github.com +
+
+

GitLab

+

Connects to GitLab.com or self-hosted GitLab instances via personal access token.

+ Cloud & Self-hosted +
+
+ +

Jira setup

+ +
+
+
+ parsec config init — Jira +
+
+$ parsec config init + ? Tracker type: jira + ? Jira base URL: https://myorg.atlassian.net + ? Jira email: you@company.com + ? Jira API token: *** + ? GitHub token: ghp_*** + ? Default branch: main +✓ Config saved to ~/.config/parsec/config.toml +
+
+ +
+
ⓘ
+
+
Jira API token
+

Generate a Jira API token at id.atlassian.com/manage-profile/security/api-tokens. parsec uses it for read-only ticket lookups; it never writes to Jira.

+
+
+ +

GitHub Issues setup

+

+ When your repo remote is GitHub, parsec automatically uses GitHub Issues as the tracker. Provide a personal access token with repo scope. +

+ +
+
+
+ parsec config init — GitHub Issues +
+
+$ parsec config init + ? Tracker type: github + ? GitHub token: ghp_*** + ? Default branch: main +✓ Config saved +  +# Ticket IDs are GitHub issue numbers +$ parsec start 42 +✓ Created worktree for issue #42: Fix pagination bug +
+
+ +

Config file reference

+

+ The config file lives at ~/.config/parsec/config.toml. You can edit it directly. +

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionExample
tracker.typeIssue tracker backend."jira" / "github" / "gitlab" / "bitbucket"
tracker.base_urlBase URL for Jira/GitLab self-hosted."https://myorg.atlassian.net"
tracker.tokenAPI token for the tracker.Jira API token or GitLab PAT
github.tokenGitHub personal access token (for PR creation)."ghp_..."
git.default_branchDefault base branch for new worktrees."main" / "develop"
git.worktree_prefixDirectory prefix for new worktrees.".." (sibling dirs)
+
+ +
+
!
+
+
No tracker configured
+

parsec still works without a tracker configured. Use --title "My description" with parsec start to provide a description manually. Ticket IDs become local labels only.

+
+
+
+ + +
+
+

AI Agent Workflows

+ # +
+ +

+ parsec was built from day one for parallel AI agent execution. Each worktree is an isolated git environment — agents can run git add, git commit, and git push simultaneously without index.lock collisions. +

+ +
+
+
+
🔒
+

Zero index.lock conflicts

+
+

Each worktree has its own .git/index. Parallel agents never contend on the same file. No retries, no wasted tokens.

+
+
+
+
📈
+

JSON output for scripting

+
+

Every command supports --json for machine-readable output. Poll pr-status, check ci, trigger merge — all scriptable.

+
+
+
+
🔍
+

Conflict detection

+
+

parsec conflicts surfaces which files are modified by multiple agents before any PR is opened — catch issues early.

+
+
+
+
📄
+

Operation history & undo

+
+

parsec log shows every action. parsec undo rolls back the last step — useful when an agent ships prematurely.

+
+
+ +

Running multiple agents in parallel

+

+ Each agent gets its own worktree. Launch them concurrently from a coordinator script — parsec handles isolation so agents never need to coordinate on git state. +

+ +
+
+
+ parallel agent launch script +
+
+#!/bin/bash +# Each ticket becomes an isolated, independent workspace +  +parsec start PROJ-120 --quiet & +parsec start PROJ-121 --quiet & +parsec start PROJ-122 --quiet & +wait +  +# Agent 1 works in ./myrepo.PROJ-120 +# Agent 2 works in ./myrepo.PROJ-121 ← no conflicts +# Agent 3 works in ./myrepo.PROJ-122 +
+
+ +

JSON output for automation

+

+ Use --json on any command to get structured output suitable for piping into jq or a coordinator agent. +

+ +
+
+
+ JSON output examples +
+
+# Check if PR is mergeable +$ parsec pr-status PROJ-120 --json | jq '.mergeable' + true +  +# Wait for CI then merge +$ parsec ci PROJ-120 --watch --json +# polls until complete, exits 0 on success +$ parsec merge PROJ-120 +  +# List all worktrees as JSON +$ parsec list --json | jq '.[].ticket' + "PROJ-120" + "PROJ-121" + "PROJ-122" +
+
+ +
+
✓
+
+
Agent best practices
+

Run parsec conflicts before any agent calls parsec ship. This surfaces file-level overlaps between parallel workstreams before they become merge conflicts.

+
+
+
+ + +
+
+

Stacked PRs

+ # +
+ +

+ Stacked PRs let you build a chain of dependent changes — each PR targets the previous ticket's branch rather than main. This is useful when a feature spans multiple tickets, or when you want incremental review of a large change. +

+ +

Creating a stack with --on

+

+ Pass --on <TICKET> to parsec start to create a worktree whose base is another ticket's branch. +

+ +
+
+
+ stacked PR workflow +
+
+# Base ticket — targets main +$ parsec start PROJ-100 +✓ Created worktree, base: main +  +# Second ticket — stacks on PROJ-100 +$ parsec start PROJ-101 --on PROJ-100 +✓ Created worktree, base: feature/PROJ-100 +  +# Third in the chain +$ parsec start PROJ-102 --on PROJ-101 +✓ Created worktree, base: feature/PROJ-101 +  +# Visualize the stack +$ parsec stack + main + └── feature/PROJ-100 PR #10 open + └── feature/PROJ-101 PR #11 open + └── feature/PROJ-102 PR #12 open +
+
+ +

After merging a stacked PR

+

+ When the base PR in a stack is merged, the child PR's target becomes stale — it still points to the merged branch. Use parsec stack --sync to automatically re-target all stacked PRs to their correct new bases. +

+ +
+
+
+ parsec stack --sync +
+
+# PROJ-100 was merged to main +# Now re-target PROJ-101 to main +$ parsec stack --sync +✓ PR #11 retargeted: feature/PROJ-100 → main +✓ Stack synchronized +
+
+ +
+
ⓘ
+
+
Merge order matters
+

Always merge stacked PRs from the bottom of the stack upward — merge the base first, then parsec stack --sync, then merge the next PR. Skipping --sync results in child PRs targeting already-merged branches.

+
+
+
+ +
+
+

New Features

+ # +
+ +

+ Recent additions to parsec that extend the workflow beyond worktree management into issue creation, release automation, and customizable hooks. +

+ +

Issue creation with parsec create

+

+ Create issues directly from the terminal without leaving your workflow. Works with GitHub Issues and Jira. Use --start to immediately begin work on the new issue. +

+ +
+
+
+ parsec create +
+
+# Create a GitHub issue +$ parsec create --title "Fix login redirect" --label "bug" +✓ Created #145: Fix login redirect +  +# Create and start working immediately +$ parsec create --title "Add caching layer" --start +✓ Created #146: Add caching layer +✓ Created workspace at ~/myrepo.146 +  +# For Jira with issue type +$ parsec new-issue --title "API caching" --issue-type Story --project CL +✓ Created CL-42: API caching +
+
+ +

Release workflow with parsec release

+

+ Automate the entire release process: merge develop to main, create a version tag, and publish a GitHub Release with auto-generated changelog — all in one command. +

+ +
+
+
+ parsec release +
+
+$ parsec release 0.3.3 +✓ Merged develop → main +✓ Tagged v0.3.3 +✓ GitHub Release: github.com/org/repo/releases/tag/v0.3.3 +  +# Always preview first with --dry-run +$ parsec release 0.4.0 --dry-run +Would merge develop → main +Would tag v0.4.0 +
+
+ +

Pre-ship hooks

+

+ Define commands that run automatically before parsec ship pushes your branch. Great for ensuring tests pass and linting is clean before creating a PR. +

+ +
+
+
+ config.toml +
+
+# ~/.config/parsec/config.toml +[hooks] +post_create = ["npm install"] +pre_ship = ["cargo test", "cargo clippy"] +  +# Skip hooks when needed +$ parsec ship PROJ-123 --skip-hooks +
+
+ +
+
ⓘ
+
+
Release configuration
+

Customize the release workflow in your config file with [release] section: set the target branch, tag prefix, and whether to include a changelog.

+
+
+
+ + +
+
+

Recipes & Examples

+ # +
+ +

+ 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

+

+ parsec now speaks Bitbucket Cloud's API: parsec ship opens PRs, parsec pr-status reports CI from Bitbucket Pipelines, parsec ci tails build status, and parsec merge merges from the terminal. Tracker integration uses the same tracker.bitbucket config block. +

+ +
+
+
+ Bitbucket setup +
+
+# Auth via env var +$ export PARSEC_BITBUCKET_TOKEN="<app-password>" +  +# Configure in ~/.config/parsec/config.toml +[tracker] +provider = "bitbucket" +[tracker.bitbucket] +workspace = "my-team" +  +$ parsec ship CL-2208 +✓ PR opened: bitbucket.org/my-team/repo/pull-requests/142 +✓ Bitbucket Pipelines: BUILD #318 in_progress +
+
+ +

Compress branch history with parsec compress

+

+ Squash a branch's commits into one tidy commit before shipping. Co-author trailers from squashed commits are preserved automatically. +

+ +
+
+
+ parsec compress +
+
+# Squash all branch commits into one +$ parsec compress +✓ Compressed 7 commits into one on feature/PROJ-123 +  +# With a custom message +$ parsec compress -m "feat: add user authentication" +  +# Compose: tidy history then ship +$ parsec compress && parsec ship +
+
+ +

Stack navigation comments

+

+ When you ship a stacked PR, parsec auto-posts "← previous PR" / "next PR →" navigation comments on every PR in the stack. Reviewers can walk the chain without leaving the PR view. +

+ +

PR template auto-fill — ship --template

+

+ Use the repository's .github/PULL_REQUEST_TEMPLATE.md (or the first match under .github/PULL_REQUEST_TEMPLATE/) as the PR description automatically. Combine with ship.template in config.toml to make it the default. +

+ +
+
+
+ ship --template +
+
+$ parsec ship PROJ-123 --template +Loaded .github/PULL_REQUEST_TEMPLATE.md (348 chars) +✓ PR opened with template body +
+
+ +

Offline mode — --offline / [workspace].offline

+

+ Skip all network operations: tracker lookups, PR creation, fetches. Use a global --offline flag, the PARSEC_OFFLINE=1 env var, or set offline = true under [workspace] in config.toml. Per-command escapes (--no-pr, --no-tracker) remain available for finer control. +

+ +
+
+
+ offline mode +
+
+# Per-invocation +$ parsec start CL-2208 --offline --title "Add login retry" +  +# Persistent — flight mode +[workspace] +offline = true +
+
+ +

Observability — execution IDs + JSONL export

+

+ Every command run gets a unique execution ID and per-step timing. parsec log --export emits one JSON object per line for tooling and AI agents to consume. Combined with --json on individual commands, parsec is fully introspectable. +

+ +
+
+
+ parsec log --export +
+
+$ parsec log --export | jq 'select(.duration_ms > 1000)' +{ + "execution_id": "01HQ3D9V7Z2...", + "op": "ship", + "ticket": "PROJ-123", + "steps": [ + {"name":"push","ms":820}, + {"name":"create_pr","ms":1305}, + {"name":"cleanup","ms":42} + ], + "duration_ms": 2167 +} +
+
+ +

Config JSON Schema — editor autocomplete

+

+ The schema for config.toml is published to schemastore.org, so VS Code, IntelliJ, Helix, and any editor with schemastore integration auto-complete and validate every key. parsec config schema emits the schema for offline use. +

+ +
+
+
+ config schema +
+
+$ parsec config schema > parsec-schema.json +  +# Pin schema in your config for editor support +#:schema https://json.schemastore.org/parsec.json +
+
+ +

Worktree build cache sharing — [worktree].shared_cache

+

+ New worktrees can reuse target/, node_modules/, .venv/, etc. from the main repo via symlink (default) or recursive copy. Eliminates cold-build cost on parsec start for any project with significant dependency caches. +

+ +
+
+
+ [worktree] config +
+
+[worktree] +shared_cache = ["target", "node_modules", ".venv"] +# "symlink" (default) — fast, zero-disk; parallel build of same artifact may race +# "copy" — independent caches per worktree, no race risk, more disk +cache_strategy = "symlink" +
+
+ +

Draft-by-default — ship.draft

+

+ Set [ship].draft = true in config.toml to open every PR as a draft, or pass --draft per ship. Useful for iterative WIP review flows where you want CI feedback before requesting human review. +

+
+ +
+ +
+
+ + + + + + + + + diff --git a/docs/v/0.4.0/index.html b/docs/v/0.4.0/index.html new file mode 100644 index 0000000..0ba17c2 --- /dev/null +++ b/docs/v/0.4.0/index.html @@ -0,0 +1,2286 @@ + + + + + + + git-parsec — From ticket to PR. One command. | Git worktree lifecycle manager + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+
+
+
Built with Rust
+
AI-Native
+
+

+ From ticket to PR
+ in one command. +

+

+ Run 5 AI agents in parallel — zero index.lock conflicts. git-parsec gives every agent its own isolated worktree, tied to your issue tracker. No retries, no wasted tokens, no merge chaos. +

+
+ + Get Started + + + + + View on GitHub + + + GitHub Stars + +
+
+
+
+
+
+
+
parsec -- zsh
+
+
+# Run 5 AI agents in parallel — no lock conflicts +$ parsec start CL-2283 +✓ Created worktree for CL-2283 + Title: Collect HeuristicCompletionException handling + Branch: feature/CL-2283 + Path: ../myproject.CL-2283 +  +# Each agent gets its own isolated worktree +$ parsec start CL-2290 +✓ Created worktree for CL-2290 +  +# Ship it -- push, create PR, cleanup +$ parsec ship CL-2283 +✓ Pushed feature/CL-2283 +✓ PR created: github.com/org/repo/pull/42 +✓ Worktree cleaned up +  +
+
+
+
+
+ + +
+
+
+
The Problem
+
Git wasn't built for
AI agent workflows.
+

+ When AI agents run in parallel on the same repo, they collide on .git/index.lock — crashing mid-task, burning tokens on retries, and leaving broken state. Worktrees solve isolation, but lack the lifecycle management agents need. +

+
+ +
+
+
+ Without parsec +
+
    +
  • +
    + +
    +
    +

    Lock contention

    +

    Parallel git operations collide on .git/index.lock, blocking agents and developers.

    +
    +
    • +
  • +
    + +
    +
    +

    Manual worktree management

    +

    Create branch, add worktree, remember paths, clean up manually. Error-prone and tedious.

    +
    +
    • +
  • +
    + +
    +
    +

    No ticket connection

    +

    Branches and worktrees have no link to your issue tracker. Context gets lost.

    +
    +
    • +
  • +
    + +
    +
    +

    Invisible conflicts

    +

    Parallel work silently edits the same files. You only find out at merge time.

    +
    +
    • +
+
+ +
+
+ With parsec +
+
    +
  • +
    + +
    +
    +

    Zero-conflict parallelism

    +

    Each ticket gets its own isolated worktree. No lock contention, ever.

    +
    +
    • +
  • +
    + +
    +
    +

    One-command lifecycle

    +

    parsec start creates everything. parsec ship pushes, PRs, and cleans up.

    +
    +
    • +
  • +
    + +
    +
    +

    Ticket tracker integration

    +

    Jira and GitHub Issues built in. Branches auto-named, PR titles auto-filled.

    +
    +
    • +
  • +
    + +
    +
    +

    Early conflict detection

    +

    parsec conflicts warns when worktrees touch the same files -- before you merge.

    +
    +
    • +
  • +
    + +
    +
    +

    Full operation history

    +

    parsec log shows everything parsec has done. parsec undo rolls back the last step if something goes wrong.

    +
    +
    • +
+
+
+
+
+ + +
+
+
+
See it in action
+
From ticket to PR in 60 seconds.
+
+
+ git-parsec demo showing start, list, switch, log, undo, and clean commands +
+
+
+ + +
+
+
+
Features
+
Everything you need.
Nothing you don't.
+

+ A focused toolset for the complete worktree lifecycle -- from creating isolated workspaces to shipping production-ready PRs. +

+
+ +
+ +
+
+ +
+

Ticket-driven worktrees

+

+ parsec start PROJ-123 creates an isolated worktree, fetches the title from your tracker (Jira · GitHub Issues · GitLab Issues · Bitbucket), and names the branch consistently. parsec adopt and --branch bring existing branches under management. Sibling layout (../repo.ticket/) keeps directories clean and IDE-friendly. +

+
$ parsec start PROJ-123   # worktree + tracker fetch + branch in one call
+
+ + +
+
+ +
+

Stacked PRs done right

+

+ Chain workspaces with parsec start CHILD --on PARENT. parsec stack --submit opens every PR in the stack in topological order. Auto-posted "← prev / next →" navigation comments let reviewers walk the chain without leaving the PR view. --sync rebases the whole chain when the base moves. +

+
$ parsec stack --submit   # root first, with nav comments
+
+ + +
+
+ +
+

Multi-forge, multi-CI

+

+ Full PR lifecycle on GitHub, GitLab, and Bitbucket Cloud. CI status from Actions, GitLab CI, and Bitbucket Pipelines — all surfaced through the same parsec ci and parsec pr-status commands. Auto-detected from the remote URL. +

+
$ parsec ci --watch   # works the same on any forge
+
+ + +
+
+ +
+

One-step ship + lifecycle

+

+ parsec ship pushes, opens the PR, and removes the worktree. parsec merge waits for CI, merges, and cleans up. parsec clean sweeps already-merged branches. parsec conflicts flags cross-worktree file overlap before push. parsec undo reverses the last operation. Every mutating command supports --dry-run. +

+
$ parsec ship PROJ-1234   # push + PR + cleanup, one command
+
+ + +
+
+ +
+

Built for agents

+

+ --json on every command. Structured error codes (E001–E013) for programmatic handling. parsec log --export emits JSONL with execution IDs and per-step timing. --offline and headless modes for CI / air-gapped environments. The config JSON Schema is published to schemastore.org for editor autocomplete. +

+
$ parsec log --export | jq 'select(.duration_ms > 1000)'
+
+ + +
+
+ +
+

Build cache + ergonomics

+

+ [worktree].shared_cache shares target/, node_modules/, .venv/ from the main repo to new worktrees via symlink (default) or copy — eliminates cold-build cost on parsec start. Shell integration auto-cd's, tab completions ship for zsh / bash / fish / powershell, parsec doctor validates your setup. +

+
shared_cache = ["target", "node_modules", ".venv"]
+
+
+ + +
+ + + + More features + — 16 additional capabilities + + +
+
Branch sync — parsec sync rebases or merges the latest base branch into one or all worktrees.
+
Operation history — parsec log shows every action with timestamps; filter by ticket or last N.
+
Undo — parsec undo reverses the last start / ship / clean. Use --dry-run to preview.
+
Open in browser — parsec open launches the PR or ticket page (GitHub / GitLab / Jira / Bitbucket).
+
Worktree diff — parsec diff compares any worktree to its base branch (--stat, --name-only).
+
Compress branch — parsec compress squashes commits into one tidy commit before shipping.
+
PR template auto-fill — ship --template reads .github/PULL_REQUEST_TEMPLATE.md.
+
Reviewers + labels — ship --reviewer / --label at PR creation time, or set defaults in config.
+
Draft-by-default — [ship].draft = true opens every PR as a draft for WIP review.
+
Pre-ship hooks — run cargo test, npm run lint, etc. before ship via [hooks].pre_ship.
+
Sprint board — parsec board renders the active Jira sprint as a Kanban board in the terminal.
+
Issue creation — parsec create / new-issue opens tickets in your tracker; --start immediately creates a worktree.
+
Release workflow — parsec release merges develop → main, tags, and creates a GitHub Release.
+
Policy guard — [policy] blocks ships to protected branches and restricts allowed targets.
+
Headless mode — --yes and TTY auto-detection skip prompts in CI / agent environments.
+
Cross-platform — Linux / macOS / Windows. Windows UNC path handling via the dunce crate.
+
+
+ See the full command reference for every flag and example, or read the getting started guide. +
+
+
+
+ + +
+
+
+
Comparison
+
How parsec stacks up.
+

+ parsec fills the gap between bare git worktree commands and tools that don't connect to your issue tracker. +

+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Featureparsecworktrunkgit worktreegit-townGitButler
Ticket tracker integrationJira + GitHub Issues--------
Physical isolation (worktrees)YesYesYes--Virtual branches
Cross-worktree conflict detectionYes--------
One-step ship (push + PR/MR + clean)GitHub + GitLab----Yes--
Operation history & undoYes----Yes (undo)Yes
JSON output for AI agentsYes------Yes
CI monitoringYes (--watch)--------
Stacked PRsYes----YesYes
Post-create hooksYesYes------
Auto-cleanup merged worktreesYes--Manual----
Forge supportGitHub + GitLabGitHub--GH, GL, Gitea, BBGitHub + GitLab
Zero config startYesYes------
+
+
+
+ + +
+
+
+
Quick Start
+
Up and running in 60 seconds.
+

+ Three commands from install to your first PR. +

+
+ +
+
+
01
+

Install

+

Install via cargo. A single binary, no runtime dependencies.

+
cargo install git-parsec
+
+
+
02
+

Configure

+

Run interactive setup. Enable shell integration for auto-cd and merge recovery.

+
parsec config init
eval "$(parsec init zsh)"
+
+
+
03
+

Start building

+

Create a worktree from any ticket. Code, commit, and ship when ready.

+
parsec start PROJ-42
+
+
+ + +
+
+
+
+
+
full workflow demo
+
+
+# Create isolated workspace from Jira ticket +$ parsec start CL-2283 +✓ Created worktree for CL-2283 + Branch: feature/CL-2283 + Path: ../myproject.CL-2283 +  +# Switch into the worktree +$ parsec switch CL-2283 + cd ../myproject.CL-2283 +  +# ... do your work, commit as usual ... +  +# Check for conflicts with other worktrees +$ parsec conflicts +✓ No file conflicts across 3 active worktrees +  +# Ship it -- push, create PR, cleanup +$ parsec ship CL-2283 +✓ Pushed feature/CL-2283 (4 commits) +✓ PR #42 created: github.com/org/repo/pull/42 +✓ Worktree cleaned up +
+
+
+
+ + +
+
+
+
+
Installation
+
Install parsec.
+

+ A single Rust binary. No runtime dependencies, no node_modules, no Python virtualenvs. +

+
+ +
+
+ Cargo + cargo install git-parsec + Available +
+
+ Homebrew + brew install git-parsec + Coming soon +
+
+ From source + git clone && cargo build --release + Available +
+
+
+
+
+ + +
+
+
+
+ Let your AI agents run.
+ Zero conflicts. Zero wasted tokens. +
+

+ Join developers and AI teams who use parsec to run parallel agents on the same repo — isolated worktrees, no index.lock fights, fewer retries. +

+
+ + + Star on GitHub + +
+ $ cargo install git-parsec +
+
+
+
+
+ + + + + + + + + + diff --git a/docs/v/0.4.0/reference/index.html b/docs/v/0.4.0/reference/index.html new file mode 100644 index 0000000..dcee65e --- /dev/null +++ b/docs/v/0.4.0/reference/index.html @@ -0,0 +1,2645 @@ + + + + + + + Command Reference — git-parsec | All 27 commands, every flag, with examples + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + +
+
+ + +
+
Documentation
+

Command Reference

+

+ Complete reference for all parsec commands. Every option, argument, and example in one place. +

+
+ + +
+

Global Options — available on every command

+
+
--json machine-readable output
+
-q / --quiet suppress non-essential output
+
--repo <PATH> target repository path
+
--dry-run preview changes without executing
+
--offline skip all network ops (tracker, PR, fetch)
+
+
+ + +
+
+

Core Workflow

+
+ + +
+
+ start + Create a new worktree for a ticket + # +
+

+ Creates a new git worktree tied to a ticket ID. Fetches the ticket title from your configured tracker (Jira, GitHub Issues, or GitLab), names the branch consistently, and sets up an isolated workspace directory alongside your main repo. +

+
+ Usage + parsec start <TICKET> [OPTIONS] +
+ +
+ + + + + + + + + + +
ArgumentDescription
<TICKET> requiredTicket ID to create a worktree for (e.g. PROJ-123, 42).
+
+ +
+ + + + + + + + + + +
OptionDescription
--base <BRANCH>Base branch to create the worktree from. Defaults to the repo's default branch.
--title <TEXT>Override the ticket title (useful when offline or using an unsupported tracker).
--on <TICKET>Set this worktree's base to another ticket's branch, creating a stacked PR dependency.
--branch <NAME>Override the generated branch name.
+
+ +
+
+
+ parsec start +
+
+# Create workspace from a Jira ticket +$ parsec start PROJ-123 +✓ Created worktree for PROJ-123 + Title: Add user authentication flow + Branch: feature/PROJ-123 + Path: ../myrepo.PROJ-123 +  +# Stack on another ticket (for dependent PRs) +$ parsec start PROJ-124 --on PROJ-123 +✓ Created worktree, base: feature/PROJ-123 +  +# Offline — override title manually +$ parsec start PROJ-125 --title "Fix login redirect" +
+
+
+ + +
+
+ list + List all active worktrees + # +
+

+ Displays all active parsec-managed worktrees with their ticket IDs, branch names, PR status, and paths. Use --full to include unpushed commit counts, ahead/behind divergence, and last commit metadata per worktree. +

+
+ Usage + parsec list [--full] [--no-pr] +
+ +
+ + + + + + + + +
OptionDescription
--fullShow extended metadata: unpushed commits, ahead/behind divergence, last commit message and age.
--no-prSkip fetching PR status from GitHub/GitLab (faster output, works offline).
+
+ +
+
+
+ parsec list +
+
+$ parsec list + TICKET BRANCH STATUS PATH + ───────────────────────────────────────────────────────────── + PROJ-123 feature/PROJ-123 open PR ../myrepo.PROJ-123 + PROJ-125 feature/PROJ-125 no PR ../myrepo.PROJ-125 + PROJ-130 feature/PROJ-130 merged ../myrepo.PROJ-130 +  +# Extended metadata per worktree +$ parsec list --full + TICKET BRANCH STATUS AHEAD/BEHIND UNPUSHED LAST COMMIT AGE + ────────────────────────────────────────────────────────────────────────────────────── + PROJ-123 feature/PROJ-123 open PR +3 / -0 1 Add rate limiting 2h ago + PROJ-125 feature/PROJ-125 no PR +1 / -2 0 Fix auth redirect 30m ago +
+
+
+ + +
+
+ switch + Print workspace path (auto-cd with shell integration) + # +
+

+ Prints the path to a ticket's worktree. With shell integration active (eval "$(parsec init zsh)"), your shell automatically cds into that directory. Without shell integration it prints the path for use in scripts. +

+
+ Usage + parsec switch [TICKET] [OPTIONS] +
+ +
+ + + + + + + + + + +
ArgumentDescription
[TICKET]Ticket ID to switch to. If omitted, shows an interactive picker.
+
+ +
+
+
+ parsec switch +
+
+# With shell integration — auto-cd into the worktree +$ parsec switch PROJ-123 + ~/projects/myrepo.PROJ-123 +# shell: cd ~/projects/myrepo.PROJ-123 +  +# Without shell integration — use in a subshell +$ cd $(parsec switch PROJ-123) +
+
+
+ + +
+
+ ship + Push, create PR/MR, and clean up + # +
+

+ The one-command shipping workflow. Pushes your branch to the remote, creates a Pull Request (or Merge Request on GitLab) with the ticket title pre-filled, and removes the worktree. All in a single step. +

+
+ Usage + parsec ship <TICKET> [OPTIONS] +
+ +
+ + + + + + + +
ArgumentDescription
<TICKET> requiredTicket ID of the worktree to ship.
+
+ +
+ + + + + + + + + + + + +
OptionDescription
--draftOpen the PR as a draft (GitHub only).
--no-prPush the branch but skip creating a PR/MR.
--base <BRANCH>Override the target base branch for the PR.
--skip-hooksSkip pre-ship hooks defined in [hooks] config.
-r, --reviewer <USER>Request review from a GitHub user (repeatable).
-l, --label <NAME>Add a label to the PR (repeatable).
+
+ +
+
+
+ parsec ship +
+
+$ parsec ship PROJ-123 +✓ Pushed feature/PROJ-123 (7 commits) +✓ PR #42 created: github.com/org/myrepo/pull/42 +✓ Worktree cleaned up +  +# Open as draft PR +$ parsec ship PROJ-125 --draft +✓ Draft PR created: github.com/org/myrepo/pull/43 +  +# Ship with reviewers and labels +$ parsec ship PROJ-126 --reviewer alice --reviewer bob --label needs-review +✓ PR #44 created with reviewers and labels +
+
+
+ + +
+
+ merge + Merge PR on GitHub and clean up + # +
+

+ Merges the PR associated with a ticket via the GitHub API, waits for the merge to complete, deletes the remote branch, and removes the local worktree. Returns you to the main repository. +

+
+ Usage + parsec merge [TICKET] [OPTIONS] +
+ +
+ + + + + + + + + +
OptionDescription
--rebaseUse rebase strategy instead of merge commit.
--no-waitTrigger the merge and return immediately without waiting.
--no-delete-branchKeep the remote branch after merging.
+
+ +
+
+
+ parsec merge +
+
+$ parsec merge PROJ-123 +✓ PR #42 merged into main +✓ Remote branch deleted +✓ Worktree removed +
+
+
+ + +
+
+ clean + Remove merged or stale worktrees + # +
+

+ Scans all parsec-managed worktrees and removes those whose PRs have been merged or whose branches no longer exist on the remote. Use --dry-run to preview what would be removed. +

+
+ Usage + parsec clean [OPTIONS] +
+ +
+ + + + + + + + + +
OptionDescription
--allRemove ALL parsec worktrees regardless of PR status.
--dry-runPreview what would be removed without deleting anything.
--orphansAlso remove worktrees not tracked by parsec.
+
+ +
+
+
+ parsec clean +
+
+# Preview first +$ parsec clean --dry-run + Would remove: ../myrepo.PROJ-123 (merged) + Would remove: ../myrepo.PROJ-130 (merged) +  +$ parsec clean +✓ Removed 2 merged worktrees +
+
+
+
+ + +
+
+

Inspection

+
+ + +
+
+ status + Show detailed workspace status + # +
+

+ Shows the full status of a worktree: uncommitted changes, commits ahead of base, PR state, CI checks, and ticket metadata. +

+
+ Usage + parsec status [TICKET] [OPTIONS] +
+ +
+
+
+ parsec status +
+
+$ parsec status PROJ-123 + Ticket: PROJ-123 — Add user authentication flow + Branch: feature/PROJ-123 + Ahead: 3 commits ahead of main + Changed: 2 files modified, 1 untracked + PR: #42 open — 1 review approved + CI: passing (3/3 checks) +
+
+
+ + +
+
+ ticket + View ticket details from tracker + # +
+

+ Fetches and displays full ticket details from your configured issue tracker (Jira, GitHub Issues, or GitLab). Optionally shows comments. +

+
+ Usage + parsec ticket [TICKET] [OPTIONS] +
+ +
+ + + + + + + +
OptionDescription
--commentInclude comments in the output.
+
+ +
+
+
+ parsec ticket +
+
+$ parsec ticket PROJ-123 + [PROJ-123] Add user authentication flow + Status: In Progress + Priority: High + Assignee: you + ... +
+
+
+ + +
+
+ diff + View changes vs base branch + # +
+

+ Shows the diff between the worktree's current state and its base branch. Defaults to full diff output; use --stat or --name-only for a summary. +

+
+ Usage + parsec diff [TICKET] [OPTIONS] +
+ +
+ + + + + + + + +
OptionDescription
--statShow diffstat summary (files changed, insertions, deletions).
--name-onlyShow only the names of changed files.
+
+ +
+
+
+ parsec diff +
+
+$ parsec diff PROJ-123 --stat + src/auth/mod.rs | 84 ++++++++++++++++++++++ + src/auth/session.rs | 42 +++++++++++ + tests/auth_test.rs | 28 ++++++++ + 3 files changed, 154 insertions(+) +
+
+
+ + +
+
+ conflicts + Detect file conflicts across worktrees + # +
+

+ Scans all active worktrees and reports files modified by more than one of them. Surfaces potential merge conflicts before you open a PR — essential when running multiple parallel agents. +

+
+ Usage + parsec conflicts [OPTIONS] +
+ +
+
+
+ parsec conflicts +
+
+$ parsec conflicts + Checking 4 active worktrees... + ⚠ src/config.rs modified in PROJ-123 and PROJ-130 +✓ No other conflicts found +
+
+
+ + +
+
+ pr-status + Check PR CI and review status + # +
+

+ Fetches the current PR state: review approvals, requested changes, CI check results, and merge readiness. Useful in agent scripts to poll before triggering a merge. +

+
+ Usage + parsec pr-status [TICKET] [OPTIONS] +
+ +
+
+
+ parsec pr-status +
+
+$ parsec pr-status PROJ-123 + PR #42 Add user authentication flow + Reviews: 2 approved + CI: all checks passing + Mergeable: yes +  +# Machine-readable for agent scripts +$ parsec pr-status PROJ-123 --json +
+
+
+ + +
+
+ ci + Check CI/CD status + # +
+

+ Shows CI/CD pipeline status for a ticket's branch. With --watch it polls continuously until all checks complete or fail. +

+
+ Usage + parsec ci [TICKET] [OPTIONS] +
+ +
+ + + + + + + + +
OptionDescription
--watchPoll CI status until completion (useful in scripts).
--allShow CI status for all active worktrees.
+
+ +
+
+
+ parsec ci +
+
+$ parsec ci PROJ-123 --watch + Watching CI for feature/PROJ-123... + [ 5s] build running + [ 32s] build passed + [ 38s] test passed + [ 41s] lint passed +✓ All CI checks passed +
+
+
+
+ + +
+
+

Advanced

+
+ + +
+
+ sync + Sync worktree with base branch + # +
+

+ Updates a worktree by fetching and merging (or rebasing) changes from its base branch. Keeps long-running feature branches current without manually switching contexts. +

+
+ Usage + parsec sync [TICKET] [OPTIONS] +
+ +
+ + + + + + + + +
OptionDescription
--allSync all active worktrees at once.
--strategy <merge|rebase>Integration strategy. Defaults to merge.
+
+ +
+
+
+ parsec sync +
+
+# Sync one worktree +$ parsec sync PROJ-123 +✓ Synced feature/PROJ-123 with main (fast-forward) +  +# Sync all worktrees with rebase strategy +$ parsec sync --all --strategy rebase +✓ Synced 3 worktrees +
+
+
+ + +
+
+ open + Open PR or ticket in browser + # +
+

+ Opens the associated PR or ticket page in your default browser. By default opens the PR; use --ticket-page to open the issue tracker instead. +

+
+ Usage + parsec open <TICKET> [OPTIONS] +
+ +
+ + + + + + + + +
OptionDescription
--prOpen the PR/MR page (default).
--ticket-pageOpen the issue tracker page instead.
+
+ +
+
+
+ parsec open +
+
+$ parsec open PROJ-123 # opens PR +$ parsec open PROJ-123 --ticket-page # opens Jira +
+
+
+ + +
+
+ adopt + Import existing branch into parsec + # +
+

+ Registers an existing git branch as a parsec-managed worktree, linking it to a ticket ID. Use this when you've already started work on a branch outside of parsec. +

+
+ Usage + parsec adopt <TICKET> [OPTIONS] +
+ +
+ + + + + + + + +
OptionDescription
--branch <NAME>Branch name to adopt (if different from the ticket-derived name).
--title <TEXT>Override ticket title for display.
+
+ +
+
+
+ parsec adopt +
+
+$ parsec adopt PROJ-123 --branch my-old-branch +✓ Adopted branch my-old-branch as PROJ-123 +
+
+
+ + +
+
+ stack + Show or manage stacked PR dependencies + # +
+

+ Displays the dependency graph of stacked PRs created with parsec start --on. With --sync, updates all PRs in the stack to use their correct base branches after an upstream merge. +

+
+ Usage + parsec stack [OPTIONS] +
+ +
+ + + + + + + + +
OptionDescription
--syncRe-target stacked PRs after an upstream PR was merged.
--submitShip the entire stack in topological order (root first). Stops on first failure.
+
+ +
+
+
+ parsec stack +
+
+$ parsec stack + main + └── feature/PROJ-123 (PROJ-123) PR #42 open + └── feature/PROJ-124 (PROJ-124) PR #43 open +  +# Ship the entire stack at once +$ parsec stack --submit +Submitting stack (2 worktrees): + 1. PROJ-123 + 2. PROJ-124 +✓ Stack submit complete: 2/2 shipped +
+
+
+ + +
+
+ inbox + List assigned tickets without worktrees + # +
+

+ Fetches tickets assigned to you from the configured tracker that don't yet have a parsec worktree. Use --pick to interactively select and immediately run parsec start on one. +

+
+ Usage + parsec inbox [OPTIONS] +
+ +
+ + + + + + + +
OptionDescription
--pickInteractive mode: select a ticket to immediately start a worktree.
+
+ +
+
+
+ parsec inbox +
+
+$ parsec inbox + PROJ-128 Fix pagination bug in search results + PROJ-131 Upgrade dependency: serde 1.0.195 + PROJ-135 Add dark mode toggle +
+
+
+ + +
+
+ board + Sprint board Kanban view + # +
+

+ Renders a Kanban-style sprint board in the terminal, pulling data from your configured tracker. Shows ticket titles, statuses, and assignees. +

+
+ Usage + parsec board [OPTIONS] +
+ +
+ + + + + + + + + + +
OptionDescription
--board-id <ID>Target a specific board by ID.
--project <KEY>Filter by project key.
--assignee <USER>Filter tickets by assignee.
--allShow tickets for all assignees.
+
+ +
+
+
+ parsec board +
+
+$ parsec board + TODO IN PROGRESS REVIEW DONE + ───────────────────────────────────────────────────── + PROJ-128 PROJ-123 PROJ-119 PROJ-111 + PROJ-131 PROJ-125 PROJ-112 +
+
+
+
+ + +
+
+

History

+
+ + +
+
+ log + Show operation history + # +
+

+ Displays a chronological log of all parsec operations: start, ship, merge, clean, undo, etc. Use --last N to limit output. +

+
+ Usage + parsec log [TICKET] [OPTIONS] +
+ +
+ + + + + + + + +
OptionDescription
--last <N>Show only the last N operations.
--exportEmit the log as JSONL (one JSON object per line). Each entry includes execution_id and per-step timing for observability/debugging by tooling and AI agents.
+
+ +
+
+
+ parsec log +
+
+$ parsec log --last 5 + 2024-01-15 14:32 merge PROJ-119 PR #38 merged + 2024-01-15 11:20 ship PROJ-123 PR #42 created + 2024-01-15 09:05 start PROJ-123 worktree created + 2024-01-14 17:44 start PROJ-125 worktree created + 2024-01-14 16:30 clean 3 worktrees removed +  +# JSONL export — one JSON object per line, with execution_id and per-step timing +$ parsec log --export +{"execution_id":"01HQ3D8R2K8...","op":"start","ticket":"PROJ-123","steps":[{"name":"fetch_title","ms":214},{"name":"create_worktree","ms":98}],"duration_ms":312} +{"execution_id":"01HQ3D9V7Z2...","op":"ship","ticket":"PROJ-123","steps":[{"name":"push","ms":820},{"name":"create_pr","ms":1305},{"name":"cleanup","ms":42}],"duration_ms":2167} +
+
+
+ + +
+
+ undo + Undo last operation + # +
+

+ Rolls back the most recent parsec operation. For example, undoing a ship removes the PR and restores the worktree. Use --dry-run to see what would happen without committing. +

+
+ Usage + parsec undo [OPTIONS] +
+ +
+ + + + + + + +
OptionDescription
--dry-runPreview what undo would do without making any changes.
+
+ +
+
+
+ parsec undo +
+
+$ parsec undo --dry-run + Would undo: ship PROJ-123 + - Close PR #42 + - Restore worktree ../myrepo.PROJ-123 +  +$ parsec undo +✓ Undid: ship PROJ-123 +
+
+
+
+ + +
+
+

Setup

+
+ + +
+
+ root + Print main repo root path + # +
+

+ Prints the absolute path of the main (non-worktree) repository root. Useful in scripts to navigate back to the primary workspace from any worktree. +

+
+ Usage + parsec root [OPTIONS] +
+ +
+
+
+ parsec root +
+
+$ parsec root + /Users/you/projects/myrepo +  +# Navigate back from a worktree +$ cd $(parsec root) +
+
+
+ + +
+
+ init + Output or install shell integration + # +
+

+ Prints a shell integration script that enables automatic cd when using parsec switch, and automatic working-directory recovery after parsec merge removes a worktree you were inside. Use --install to auto-append the integration to your shell config file instead of managing it manually. +

+
+ Usage + parsec init [SHELL] [--install] [--yes] +
+ +
+ + + + + + + + + +
Argument / OptionDescription
[SHELL]Shell to generate integration for. Supported: zsh, bash, fish. Defaults to zsh.
--installAuto-append eval "$(parsec init <shell>)" to your shell config file with a confirmation prompt.
-y, --yesSkip the confirmation prompt. Useful for scripted or non-interactive environments.
+
+ +
+
+
+ parsec init +
+
+# Preferred: 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. +  +# Non-interactive install (scripted setup) +$ parsec init --install --yes +  +# Manual: print and eval yourself +$ eval "$(parsec init zsh)" +  +# bash users +$ eval "$(parsec init bash)" +  +# fish users +$ parsec init fish | source +
+
+
+ + +
+
+ config + Configure parsec + # +
+

+ Top-level configuration command with subcommands for initial setup, showing current config, generating shell completions, and reading the manual. +

+
+ Usage + parsec config <SUBCOMMAND> [OPTIONS] +
+ +
+ + + + + + + + + + + + +
SubcommandDescription
initRun interactive first-time setup (tracker URL, API tokens, default branch).
showDisplay current configuration (redacts sensitive tokens).
manOpen the parsec manual in your pager.
completions <SHELL>Generate shell completion script for zsh, bash, or fish.
schemaOutput the JSON Schema for config.toml. The schema is also published to schemastore.org so editors auto-complete configuration files.
shellDeprecated. Use parsec init <SHELL> instead.
+
+ +
+
+
+ parsec config +
+
+# First-time setup wizard +$ parsec config init + ? Tracker type: jira + ? Jira base URL: https://myorg.atlassian.net + ? Jira API token: *** +✓ Config saved to ~/.config/parsec/config.toml +  +# Install shell completions (zsh) +$ parsec config completions zsh > ~/.zsh/completions/_parsec +  +# Show current config +$ parsec config show +  +# Output the JSON Schema (also at https://json.schemastore.org/parsec.json) +$ parsec config schema > parsec-schema.json +
+
+
+ + +
+
+ doctor + Validate environment and configuration + # +
+

+ Checks your environment and prints ✓/✗ for each item with actionable fix instructions. Verifies git version, config file, API tokens, tracker connectivity, shell integration, tab completions, and remote access. +

+
+ Usage + parsec doctor [OPTIONS] +
+ +
+ + + + + + + + +
OptionDescription
--jsonOutput results as JSON ({"checks":[...],"all_ok":bool}).
--aiInclude AI-powered diagnostic suggestions for failed checks.
+
+ +
+
+
+ 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. +  +# Machine-readable output +$ parsec doctor --json +{"checks":[...],"all_ok":false} +
+
+
+ + +
+
+ create + Create a new issue on the tracker + # +
+

+ Creates a new ticket on GitHub Issues or Jira and optionally starts a worktree for it immediately. Auto-detects the tracker from your config. +

+
+ Usage + parsec create [OPTIONS] +
+ +
+ + + + + + + + + + + +
OptionDescription
--title <TEXT> requiredIssue title.
--body <TEXT>Issue body / description.
--label <A,B>Comma-separated labels to apply.
-p, --project <KEY>Jira project key (auto-detected from config if omitted).
--startStart a worktree for the new issue immediately after creation.
+
+ +
+
+
+ parsec create +
+
+$ 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" --start +✓ Created #146: Add caching +✓ Created workspace at ~/myrepo.146 +
+
+
+ + +
+
+ new-issue + Create a new issue (extended) + # +
+

+ Extended issue creation with multi-label support and Jira issue type control. Auto-detects GitHub or Jira from config. +

+
+ Usage + parsec new-issue [OPTIONS] +
+ +
+ + + + + + + + + + + + +
OptionDescription
--title <TEXT> requiredIssue title.
--body <TEXT>Issue body / description.
--label <LABEL>Label (can be specified multiple times).
-p, --project <KEY>Jira project key (auto-detected from config if omitted).
--issue-type <TYPE>Jira issue type (default: Task).
--startAuto-start a worktree for the new issue.
+
+ +
+
+
+ parsec new-issue +
+
+$ parsec new-issue --title "Implement caching" --issue-type Story --project CL +✓ Created CL-42: Implement caching + https://jira.example.com/browse/CL-42 +  +# Multiple labels on GitHub +$ parsec new-issue --title "Fix auth" --label bug --label priority +✓ Created #147: Fix auth +
+
+
+ + +
+
+ rename + Re-ticket an existing workspace + # +
+

+ Reassigns an existing worktree to a different ticket ID. Updates the branch name, directory symlink, and internal state — useful when a ticket is split, renumbered, or moved between trackers. +

+
+ Usage + parsec rename <OLD-TICKET> <NEW-TICKET> [OPTIONS] +
+ +
+ + + + + + + + +
ArgumentDescription
<OLD-TICKET> requiredThe current ticket ID of the workspace to rename.
<NEW-TICKET> requiredThe new ticket ID to assign to the workspace.
+
+ +
+ + + + + + + +
OptionDescription
--dry-runPreview what would be renamed without making changes.
+
+ +
+
+
+ parsec rename +
+
+$ parsec rename PROJ-123 PROJ-456 +✓ Branch renamed: feature/PROJ-123-fix-login → feature/PROJ-456-fix-login +✓ Workspace directory updated +✓ State updated for PROJ-456 +  +# Preview changes first +$ parsec rename OLD-99 NEW-100 --dry-run +Would rename branch feature/OLD-99-… → feature/NEW-100-… +Would update workspace directory and state file +
+
+
+ + +
+
+ compress + Squash all branch commits into one + # +
+

+ Resets the branch to the merge-base with the base branch and re-commits all changes as a single commit. Co-author trailers from squashed commits are preserved. Useful before parsec ship to keep PR history tidy. +

+
+ Usage + parsec compress [TICKET] [OPTIONS] +
+ +
+ + + + + + + +
ArgumentDescription
[TICKET]Optional. Auto-detects the current worktree's ticket if omitted.
+
+ +
+ + + + + + + +
OptionDescription
-m, --message <TEXT>Custom commit message. Default: combines all squashed commit messages.
+
+ +
+
+
+ parsec compress +
+
+# Compress current worktree's branch +$ parsec compress +✓ Compressed 7 commits into one on feature/PROJ-1234 +  +# Compress with custom message +$ parsec compress PROJ-1234 -m "feat: add user authentication" +  +# Combine with ship +$ parsec compress && parsec ship +
+
+
+ + +
+
+ release + Create a versioned release + # +
+

+ Merges the develop branch into the release branch (default: main), creates a version tag, and creates a GitHub Release with auto-generated changelog from commit messages since the last tag. +

+
+ Usage + parsec release <VERSION> [OPTIONS] +
+ +
+ + + + + + + +
ArgumentDescription
<VERSION> requiredVersion string (e.g., 0.3.0).
+
+ +
+ + + + + + + + + +
OptionDescription
--from <BRANCH>Source branch to release from (default: develop).
--no-github-releaseSkip creating a GitHub Release.
--dry-runShow what would happen without making changes.
+
+ +
+
+
+ parsec release +
+
+$ parsec release 0.3.0 +✓ Merged develop → main +✓ Tagged v0.3.0 +✓ GitHub Release: github.com/org/repo/releases/tag/v0.3.0 +  +# Preview first +$ parsec release 0.4.0 --dry-run +Would merge develop → main +Would tag v0.4.0 +Would create GitHub Release +
+
+
+ +
+ + + +
+
+

Error Codes

+
+ +
+

+ All parsec commands exit with a structured exit code. Use these in scripts to handle failures precisely. JSON output (--json) also includes an "error_code" field on failure. +

+ +
+ + + + + + + + + + + + + + + +
Exit CodeNameDescription
0SuccessCommand completed successfully.
1GeneralErrorUnspecified error — check stderr for details.
2ConfigErrorMissing or invalid configuration (run parsec config init).
3TrackerErrorCould not reach or authenticate with the issue tracker.
4GitErrorGit operation failed (merge conflict, missing remote, etc.).
5WorktreeErrorWorktree already exists, is missing, or is in a bad state.
6NotFoundTicket or workspace not found.
7AuthErrorAPI token missing or insufficient permissions.
8PolicyViolationOperation blocked by an active policy rule.
+
+ +
+
+
+ exit code in scripts +
+
+$ parsec ship PROJ-123 --json +{"error_code":3,"message":"Could not reach Jira: connection refused"} +$ echo $? +3 +
+
+
+
+ + + +
+
+

Policy Config

+
+ +
+

+ The [policy] table in ~/.config/parsec/config.toml lets teams enforce guardrails on parsec operations. Violations exit with code 8 (PolicyViolation) and print an actionable message. +

+ +
+ + + + + + + + + + + +
KeyTypeDescription
require_ticket_prefixStringAll ticket IDs must match this prefix (e.g., "PROJ-"). Prevents freeform branch names.
max_open_workspacesu32Block parsec start when open workspace count reaches this limit.
protected_branches[String]Branches that parsec ship and parsec merge will refuse to target (e.g., ["main", "production"]).
require_pr_reviewboolWhen true, parsec ship checks that at least one review is approved before merging.
allow_force_pushboolWhen false (default), parsec ship refuses to push with --force.
+
+ +
+
+
+ ~/.config/parsec/config.toml +
+
+[policy] +require_ticket_prefix = "PROJ-" +max_open_workspaces = 5 +protected_branches = ["main", "production"] +require_pr_review = true +allow_force_push = false +  +# Policy violation example +$ parsec start my-feature +✗ Policy violation: ticket ID must start with "PROJ-" +
+
+
+
+ + +
+ +
+
+ + + + + + + + + diff --git a/docs/versions.json b/docs/versions.json index 0c9cedf..bc0fac3 100644 --- a/docs/versions.json +++ b/docs/versions.json @@ -1,6 +1,11 @@ { - "latest": "0.3.3", + "latest": "0.4.0", "versions": [ + { + "version": "0.4.0", + "date": "2026-05-04", + "path": "/git-parsec/v/0.4.0/" + }, { "version": "0.3.3", "date": "2026-04-23", @@ -52,4 +57,4 @@ "path": "/git-parsec/v/0.1.1/" } ] -} +} \ No newline at end of file