From a5f97f9c91907ec94f098ca64577853cacbbc9d2 Mon Sep 17 00:00:00 2001 From: erish Date: Thu, 23 Apr 2026 01:08:53 +0900 Subject: [PATCH 1/2] docs: AEO optimization and v0.3.3 feature documentation (#227) (#228) - Update README with rename, --dry-run, doctor --ai, error codes, policy config, FAQ - Fix docs site: version 0.3.3, downloadUrl, expanded FAQPage (10 Q&A) - Add BreadcrumbList and HowTo schemas to guide/reference pages - Add CHANGELOG.md, sitemap.xml, robots.txt - Add documentation field to Cargo.toml Co-authored-by: Claude Opus 4.6 --- CHANGELOG.md | 120 +++++++++++++++++++++++++ Cargo.toml | 1 + README.md | 104 ++++++++++++++++++++++ docs/guide/index.html | 35 +++++++- docs/index.html | 56 +++++++++++- docs/reference/index.html | 180 ++++++++++++++++++++++++++++++++++++++ docs/robots.txt | 4 + docs/sitemap.xml | 21 +++++ 8 files changed, 513 insertions(+), 8 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 docs/robots.txt create mode 100644 docs/sitemap.xml diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..b326ae4 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,120 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [0.3.3] - 2026-04-22 + +### Added +- Global `--dry-run` flag for all mutating commands (start, ship, clean, sync, merge, rename) +- Policy guard for protected branches and allowed ship targets (`[policy]` config) +- `parsec doctor --ai` — output workflow rules as Markdown for AI agents +- Standard error codes (E001–E013) with structured JSON error format +- PR number stored as first-class field in operation log +- `parsec ship --title` flag for custom PR titles + +### Fixed +- reqwest 0.13 missing `rustls` TLS backend feature +- rustls-webpki vulnerabilities (RUSTSEC-2026-0098/0099/0104) +- `parsec open --pr` fails on GitHub Enterprise (hardcoded github.com) +- Doctor command token handling and GHE support +- `.atlassian-env` parser does not strip shell-style quotes +- `unwrap()` panic paths in tracker and stack sync + +### Changed +- Major dependency upgrades (reqwest 0.13, colored 3, indicatif 0.18, tabled 0.20, toml 1) +- Extracted Jira config boilerplate into helper function +- Ticket ID validation to prevent path traversal and invalid branch names + +## [0.3.2] - 2026-04-21 + +### Fixed +- Windows binary release upload (use bash shell) + +## [0.3.1] - 2026-04-21 + +### Added +- `parsec rename` command to re-ticket a workspace +- `parsec create` and `parsec new-issue` for creating tracker issues from CLI +- `parsec release` command for automated release workflow +- `parsec doctor` for environment validation +- `parsec list --full` with richer worktree metadata +- `parsec init --install` for automatic shell integration setup +- `parsec switch pr:NUMBER` to checkout PR branches +- `parsec start --hook` for post-create automation +- Pre-ship hooks support (`[hooks] pre_ship`) +- `parsec ci` accepts multiple tickets +- `parsec merge --batch` for merging multiple PRs sequentially +- `parsec clean` supports cleaning a specific ticket +- `parsec ship` auto-closes issues on merge +- Automated multi-platform binary releases +- Documentation site with guide and reference pages + +### Fixed +- Jira integration improvements (config token, HTML error, status display) +- Proper error propagation in CI + +### Changed +- Output module refactored with `dispatch_output!` macro +- Split monolithic `commands.rs` into per-command modules +- Unified Create and NewIssue into single command +- Typed response structs replace raw `serde_json::Value` +- HTTP client timeout and retry for transient failures +- Idempotency guarantees for ship/merge re-execution +- Expanded integration test coverage + +## [0.3.0] - 2026-04-16 + +### Added +- `parsec board` — sprint as vertical Kanban board +- `parsec ticket` command for tracker lookup with `--comment` +- `parsec inbox` for viewing assigned tickets +- `parsec init` and `parsec root` for shell integration +- Automatic ticket status transitions +- `parsec ship --base` flag and `default_base` config +- `gh auth token` fallback for GitHub token resolution +- Host-aware GitHub token resolution for GitHub Enterprise + +### Fixed +- Merge/pr-status work with adopted branches +- Conflicts detection with origin fallback +- Prune stale remote-tracking references after merge + +### Security +- Pinned GitHub Actions to SHA hashes +- Added cargo audit job + +## [0.2.4] - 2026-04-15 + +### Added +- `parsec ci` to check CI/CD pipeline status +- `parsec merge` to merge PRs from terminal +- `parsec diff` to view worktree changes +- `parsec stack` for stacked PR dependency tracking +- `parsec start --branch` for existing branches + +## [0.2.3] - 2026-04-15 + +### Added +- `parsec open` to open PR or ticket page in browser +- `parsec pr-status` for CI and review status +- `parsec sync` to rebase/merge base branch +- `parsec adopt` to import existing branches + +## [0.2.0] - 2026-04-14 + +### Added +- Initial release with core commands (start, list, status, ship, clean, conflicts, switch, log, undo) +- Jira and GitHub Issues integration +- `--json` output on all commands +- Sibling and internal worktree layouts + +[0.3.3]: https://github.com/erishforG/git-parsec/compare/v0.3.2...v0.3.3 +[0.3.2]: https://github.com/erishforG/git-parsec/compare/v0.3.1...v0.3.2 +[0.3.1]: https://github.com/erishforG/git-parsec/compare/v0.3.0...v0.3.1 +[0.3.0]: https://github.com/erishforG/git-parsec/compare/v0.2.4...v0.3.0 +[0.2.4]: https://github.com/erishforG/git-parsec/compare/v0.2.3...v0.2.4 +[0.2.3]: https://github.com/erishforG/git-parsec/compare/v0.2.0...v0.2.3 +[0.2.0]: https://github.com/erishforG/git-parsec/releases/tag/v0.2.0 diff --git a/Cargo.toml b/Cargo.toml index 78b5ba0..9f3fc9d 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -7,6 +7,7 @@ description = "Git worktree lifecycle manager — ticket to PR in one command. P license = "MIT" repository = "https://github.com/erishforG/git-parsec" homepage = "https://erishforg.github.io/git-parsec/" +documentation = "https://erishforg.github.io/git-parsec/" keywords = ["git", "worktree", "cli", "jira", "github"] categories = ["command-line-utilities", "development-tools"] readme = "README.md" diff --git a/README.md b/README.md index 3dcf0cf..176a0d9 100644 --- a/README.md +++ b/README.md @@ -323,6 +323,7 @@ $ parsec log | [`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 | --- @@ -1029,6 +1030,14 @@ $ 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` @@ -1119,12 +1128,38 @@ $ 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 +``` + +--- + ## Global Flags These flags work on every command: | Flag | Description | |------|-------------| +| `--dry-run` | Preview what a command would do without making changes | | `--json` | Machine-readable JSON output | | `-q, --quiet` | Suppress non-essential output | | `--repo ` | Target a different repository | @@ -1244,6 +1279,11 @@ pre_ship = ["cargo test", "cargo clippy"] # 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 + [tracker.auto_transition] # on_start = "In Progress" # Transition when `parsec start` runs # on_ship = "In Review" # Transition when `parsec ship` runs @@ -1272,6 +1312,36 @@ Token priority: `PARSEC_*_TOKEN` > platform-specific variables. --- +## Error Codes + +When using `--json`, errors include a structured error code for programmatic handling: + +| 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 | + +```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 $? +2 +``` + +--- + ## Comparison with Alternatives | Feature | parsec | GitButler | worktrunk | git worktree | git-town | @@ -1294,6 +1364,40 @@ Token priority: `PARSEC_*_TOKEN` > platform-specific variables. --- +## 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 diff --git a/docs/guide/index.html b/docs/guide/index.html index ea4602b..d4ce392 100644 --- a/docs/guide/index.html +++ b/docs/guide/index.html @@ -945,6 +945,33 @@ } .reveal.visible { opacity: 1; transform: translateY(0); } + + + + + @@ -1041,7 +1068,7 @@

Via cargo (recommended)

  # Verify installation $ parsec --version - parsec 0.2.4 + parsec 0.3.3 @@ -1593,10 +1620,10 @@

Release workflow with parsec release

parsec release
-$ parsec release 0.3.0 +$ parsec release 0.3.3 ✓ Merged develop → main -✓ Tagged v0.3.0 -✓ GitHub Release: github.com/org/repo/releases/tag/v0.3.0 +✓ 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 diff --git a/docs/index.html b/docs/index.html index a91b22c..88fb60b 100644 --- a/docs/index.html +++ b/docs/index.html @@ -31,8 +31,8 @@ "operatingSystem": "macOS, Linux, Windows", "description": "Git worktree lifecycle manager for parallel AI agent workflows. Create isolated workspaces from ticket IDs (Jira, GitHub Issues, GitLab), work in parallel without lock conflicts, ship with one command (push + PR + cleanup). Supports CI monitoring, stacked PRs, conflict detection, and operation history with undo.", "url": "https://erishforg.github.io/git-parsec/", - "downloadUrl": "https://crates.io/crates/git-parsec", - "softwareVersion": "0.2.4", + "downloadUrl": "https://github.com/erishforG/git-parsec/releases", + "softwareVersion": "0.3.3", "author": { "@type": "Person", "name": "erishforG", @@ -75,7 +75,7 @@ "name": "Can multiple AI agents use parsec on the same repository?", "acceptedAnswer": { "@type": "Answer", - "text": "Yes. Each parsec workspace is a separate git worktree with its own index, so multiple AI agents (or developers) can run git add, commit, and push simultaneously without index.lock conflicts. parsec also detects when multiple workspaces modify the same files." + "text": "Yes. Each parsec workspace is a separate git worktree with its own index, so multiple AI agents (or developers) can run git add, commit, and push simultaneously without index.lock conflicts. Every command supports --json for structured output, and parsec doctor --ai outputs workflow rules optimized for AI consumption." } }, { @@ -83,7 +83,55 @@ "name": "How do I install parsec?", "acceptedAnswer": { "@type": "Answer", - "text": "Install via cargo: cargo install git-parsec. Or build from source: git clone https://github.com/erishforG/git-parsec.git && cd git-parsec && cargo build --release. The binary is at ./target/release/parsec." + "text": "Install via cargo: cargo install git-parsec. Or download pre-built binaries for macOS (Apple Silicon, Intel), Linux, and Windows from the GitHub Releases page. Or build from source: git clone and cargo build --release." + } + }, + { + "@type": "Question", + "name": "Does parsec support GitLab?", + "acceptedAnswer": { + "@type": "Answer", + "text": "Yes. parsec supports GitLab for both issue tracking and merge request creation. Set provider = gitlab in your config and configure the base_url. Authentication uses PARSEC_GITLAB_TOKEN or GITLAB_TOKEN environment variables." + } + }, + { + "@type": "Question", + "name": "How do stacked PRs work in parsec?", + "acceptedAnswer": { + "@type": "Answer", + "text": "Use parsec start CHILD --on PARENT to create dependent worktrees. When you ship, parsec automatically sets the correct base branch for each PR. Use parsec stack to view the dependency graph and parsec stack --sync to rebase the entire chain." + } + }, + { + "@type": "Question", + "name": "Does parsec work with GitHub Enterprise?", + "acceptedAnswer": { + "@type": "Answer", + "text": "Yes. parsec auto-detects GitHub Enterprise from the git remote URL and routes API calls to the correct host. Token resolution is host-aware, supporting both github.com and GitHub Enterprise instances." + } + }, + { + "@type": "Question", + "name": "Can I undo a parsec operation?", + "acceptedAnswer": { + "@type": "Answer", + "text": "Yes. parsec log shows all operations with timestamps, and parsec undo reverses the last one. Undoing a start removes the worktree; undoing a ship or clean re-creates it from the branch if still available." + } + }, + { + "@type": "Question", + "name": "How do I protect branches from accidental shipping?", + "acceptedAnswer": { + "@type": "Answer", + "text": "Add a [policy] section to ~/.config/parsec/config.toml with protected_branches and allowed_ship_targets. parsec will reject ship and merge operations that violate these rules, returning error code E009." + } + }, + { + "@type": "Question", + "name": "What are parsec error codes?", + "acceptedAnswer": { + "@type": "Answer", + "text": "When using --json mode, parsec returns structured error codes (E001 through E013) with specific exit codes for programmatic handling. For example, E001 means no token configured (exit 2), E002 means CI failing (exit 4), E003 means conflicts detected (exit 3). This enables AI agents and scripts to handle errors precisely." } } ] diff --git a/docs/reference/index.html b/docs/reference/index.html index ec6c7a3..3e41bf7 100644 --- a/docs/reference/index.html +++ b/docs/reference/index.html @@ -852,6 +852,19 @@ transform: translateY(0); } + + + + @@ -896,6 +909,7 @@
  • clean
  • create
  • new-issue
    • +
  • rename
  • release
    • @@ -945,6 +959,15 @@
  • doctor
    • + + +
    +
    Reference
    + +
    @@ -967,6 +990,7 @@

    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
    @@ -2032,6 +2056,7 @@

    Setup

    --jsonOutput results as JSON ({"checks":[...],"all_ok":bool}). + --aiInclude AI-powered diagnostic suggestions for failed checks. @@ -2157,6 +2182,63 @@

    Setup

    + +
    +
    + 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 +
    +
    +
    +
    @@ -2219,6 +2301,104 @@

    Setup

    + +
    +
    +

    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/robots.txt b/docs/robots.txt new file mode 100644 index 0000000..4e53dda --- /dev/null +++ b/docs/robots.txt @@ -0,0 +1,4 @@ +User-agent: * +Allow: / + +Sitemap: https://erishforg.github.io/git-parsec/sitemap.xml diff --git a/docs/sitemap.xml b/docs/sitemap.xml new file mode 100644 index 0000000..78151ab --- /dev/null +++ b/docs/sitemap.xml @@ -0,0 +1,21 @@ + + + + https://erishforg.github.io/git-parsec/ + 2026-04-22 + weekly + 1.0 + + + https://erishforg.github.io/git-parsec/guide/ + 2026-04-22 + weekly + 0.8 + + + https://erishforg.github.io/git-parsec/reference/ + 2026-04-22 + weekly + 0.8 + + From 314e79b8b3de206c6282e4864fe2f92361ffc316 Mon Sep 17 00:00:00 2001 From: erishforG Date: Thu, 23 Apr 2026 08:34:36 +0900 Subject: [PATCH 2/2] feat: versioned documentation with version switcher (#231) - Add version-switcher dropdown to all docs pages - Create versioned snapshots for all releases (v0.1.1 ~ v0.3.3) - Add snapshot-docs CI job to auto-create snapshots on release - Add versions.json manifest and sitemap entries - Add CLAUDE.md with project conventions and release checklist - Add .claude/ to .gitignore Co-Authored-By: Claude Opus 4.6 --- .github/workflows/release.yml | 56 + .gitignore | 1 + CLAUDE.md | 90 + docs/guide/index.html | 77 +- docs/index.html | 77 +- docs/reference/index.html | 77 +- docs/sitemap.xml | 96 ++ docs/v/0.1.1/index.html | 1869 +++++++++++++++++++++ docs/v/0.2.0/index.html | 1869 +++++++++++++++++++++ docs/v/0.2.1/index.html | 1939 ++++++++++++++++++++++ docs/v/0.2.2/index.html | 1976 ++++++++++++++++++++++ docs/v/0.2.3/index.html | 2000 +++++++++++++++++++++++ docs/v/0.2.4/index.html | 2137 ++++++++++++++++++++++++ docs/v/0.3.0/index.html | 2145 ++++++++++++++++++++++++ docs/v/0.3.1/guide/index.html | 1705 +++++++++++++++++++ docs/v/0.3.1/index.html | 2151 ++++++++++++++++++++++++ docs/v/0.3.1/reference/index.html | 2289 ++++++++++++++++++++++++++ docs/v/0.3.2/guide/index.html | 1705 +++++++++++++++++++ docs/v/0.3.2/index.html | 2151 ++++++++++++++++++++++++ docs/v/0.3.2/reference/index.html | 2289 ++++++++++++++++++++++++++ docs/v/0.3.3/guide/index.html | 1792 ++++++++++++++++++++ docs/v/0.3.3/index.html | 2259 ++++++++++++++++++++++++++ docs/v/0.3.3/reference/index.html | 2529 +++++++++++++++++++++++++++++ docs/version-switcher.js | 115 ++ docs/versions.json | 55 + 25 files changed, 33446 insertions(+), 3 deletions(-) create mode 100644 CLAUDE.md create mode 100644 docs/v/0.1.1/index.html create mode 100644 docs/v/0.2.0/index.html create mode 100644 docs/v/0.2.1/index.html create mode 100644 docs/v/0.2.2/index.html create mode 100644 docs/v/0.2.3/index.html create mode 100644 docs/v/0.2.4/index.html create mode 100644 docs/v/0.3.0/index.html create mode 100644 docs/v/0.3.1/guide/index.html create mode 100644 docs/v/0.3.1/index.html create mode 100644 docs/v/0.3.1/reference/index.html create mode 100644 docs/v/0.3.2/guide/index.html create mode 100644 docs/v/0.3.2/index.html create mode 100644 docs/v/0.3.2/reference/index.html create mode 100644 docs/v/0.3.3/guide/index.html create mode 100644 docs/v/0.3.3/index.html create mode 100644 docs/v/0.3.3/reference/index.html create mode 100644 docs/version-switcher.js create mode 100644 docs/versions.json diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 8a32aee..40daefd 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -113,3 +113,59 @@ jobs: gh release upload "${{ needs.release.outputs.tag }}" \ parsec-${{ needs.release.outputs.version }}-${{ matrix.target }}.${{ matrix.archive }} \ --clobber + + snapshot-docs: + name: Snapshot Versioned Docs + needs: release + if: needs.release.outputs.created == 'true' + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + with: + ref: main + + - name: Create versioned docs snapshot + env: + VERSION: ${{ needs.release.outputs.version }} + run: | + mkdir -p "docs/v/${VERSION}/guide" "docs/v/${VERSION}/reference" + + for file in index.html guide/index.html reference/index.html; do + sed \ + -e 's/data-doc-version="latest"/data-doc-version="'"${VERSION}"'"/' \ + -e 's||\n |' \ + -e 's|href="/git-parsec/"|href="/git-parsec/v/'"${VERSION}"'/"|g' \ + -e 's|href="/git-parsec/#|href="/git-parsec/v/'"${VERSION}"'/#|g' \ + -e 's|href="/git-parsec/reference/|href="/git-parsec/v/'"${VERSION}"'/reference/|g' \ + -e 's|href="/git-parsec/guide/|href="/git-parsec/v/'"${VERSION}"'/guide/|g' \ + -e 's|src="demo.gif"|src="/git-parsec/demo.gif"|' \ + "docs/${file}" > "docs/v/${VERSION}/${file}" + done + + - name: Update versions.json + env: + VERSION: ${{ needs.release.outputs.version }} + run: | + DATE=$(date -u +%Y-%m-%d) + jq --arg ver "$VERSION" --arg date "$DATE" \ + '.latest = $ver | .versions = [{"version": $ver, "date": $date, "path": ("/git-parsec/v/" + $ver + "/")}] + .versions' \ + docs/versions.json > docs/versions.json.tmp + mv docs/versions.json.tmp docs/versions.json + + - name: Update sitemap.xml + env: + VERSION: ${{ needs.release.outputs.version }} + run: | + DATE=$(date -u +%Y-%m-%d) + sed -i '/<\/urlset>/i \ + \n https://erishforg.github.io/git-parsec/v/'"${VERSION}"'/\n '"${DATE}"'\n never\n 0.3\n \n \n https://erishforg.github.io/git-parsec/v/'"${VERSION}"'/guide/\n '"${DATE}"'\n never\n 0.3\n \n \n https://erishforg.github.io/git-parsec/v/'"${VERSION}"'/reference/\n '"${DATE}"'\n never\n 0.3\n ' docs/sitemap.xml + + - name: Commit and push versioned docs + run: | + git config user.name "github-actions[bot]" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + git add docs/v/ docs/versions.json docs/sitemap.xml + git commit -m "docs: snapshot versioned docs for v${VERSION}" + git push origin main diff --git a/.gitignore b/.gitignore index dc58b7b..b7202fd 100644 --- a/.gitignore +++ b/.gitignore @@ -6,4 +6,5 @@ Cargo.lock .env .parsec/ .omc/ +.claude/ demo.mp4 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..2d804b9 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,90 @@ +# CLAUDE.md — git-parsec Project Instructions + +## Project Overview + +- **Name**: git-parsec (binary: `parsec`) +- **Language**: Rust (edition 2021) +- **Repo**: https://github.com/erishforG/git-parsec +- **Docs site**: https://erishforg.github.io/git-parsec/ (GitHub Pages from `docs/` on `main`) + +## Branch Strategy + +- **Main branch**: `main` — production, auto-releases on push +- **Dev branch**: `develop` — development work +- PRs go from `develop` → `main` +- Default branch prefix: `feature/` + +## Release Process + +### How Releases Work + +Releases are **fully automated via CI** (`.github/workflows/release.yml`). The workflow triggers on every push to `main` and: + +1. Reads version from `Cargo.toml` +2. Checks if a git tag for that version already exists +3. If new: creates git tag, publishes to crates.io, creates GitHub Release, builds binaries, and snapshots versioned docs + +### NEVER Create Tags Manually + +**Do NOT run `git tag` or create tags manually.** The CI workflow handles tag creation automatically. Manually creating tags will cause the release workflow to skip (it checks `if tag exists → skip`). + +### How to Release a New Version + +1. Bump `version` in `Cargo.toml` +2. Ensure all changes are on `develop` +3. Merge `develop` → `main` via PR +4. CI does the rest automatically + +### Pre-Release Checklist (MANDATORY) + +**CRITICAL: Do NOT merge to `main` without completing ALL items below. Skipping README or docs updates has caused issues in the past.** + +Before merging to `main`, verify: + +- [ ] `Cargo.toml` version bumped +- [ ] **`README.md` updated** — new commands, changed flags, feature descriptions, command count +- [ ] **`docs/` pages updated** — this is the public-facing site, must reflect current version + - `docs/index.html` — feature list, command count, examples + - `docs/guide/index.html` — installation, workflows, new features + - `docs/reference/index.html` — all commands with correct options/examples + - `softwareVersion` in structured data (` + diff --git a/docs/index.html b/docs/index.html index 88fb60b..3773010 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1,5 +1,5 @@ - + @@ -1461,6 +1461,80 @@ width: 100%; display: block; } + + /* ================================================ + VERSION SWITCHER + ================================================ */ + .version-switcher { + position: relative; + margin-left: 12px; + } + .version-btn { + background: var(--bg-raised); + color: var(--accent-cyan); + border: 1px solid var(--border-accent); + border-radius: var(--radius-sm); + padding: 4px 10px; + font-family: var(--font-mono); + font-size: 0.8rem; + cursor: pointer; + transition: background 0.2s; + display: flex; + align-items: center; + gap: 2px; + } + .version-btn:hover { background: var(--bg-card); } + .version-arrow { font-size: 0.7rem; } + .version-dropdown { + display: none; + position: absolute; + top: calc(100% + 6px); + left: 0; + background: var(--bg-raised); + border: 1px solid var(--border-accent); + border-radius: var(--radius-sm); + min-width: 160px; + z-index: 1000; + box-shadow: 0 8px 24px rgba(0,0,0,0.4); + } + .version-dropdown.open { display: block; } + .version-dropdown a { + display: block; + padding: 8px 14px; + color: var(--text-secondary); + text-decoration: none; + font-family: var(--font-mono); + font-size: 0.8rem; + transition: background 0.15s, color 0.15s; + } + .version-dropdown a:hover { + background: var(--bg-card); + color: var(--text-primary); + } + .version-dropdown a.active { + color: var(--accent-cyan); + background: var(--accent-glow); + } + .version-banner { + background: rgba(255, 193, 7, 0.12); + border-bottom: 1px solid rgba(255, 193, 7, 0.3); + color: #ffd54f; + text-align: center; + padding: 8px 16px; + font-family: var(--font-body); + font-size: 0.9rem; + position: fixed; + top: 0; + left: 0; + right: 0; + z-index: 10000; + } + .version-banner a { + color: #fff; + text-decoration: underline; + margin-left: 4px; + } + .version-banner a:hover { color: var(--accent-cyan); } @@ -2179,5 +2253,6 @@

    Start building

    }); + diff --git a/docs/reference/index.html b/docs/reference/index.html index 3e41bf7..3e1e40d 100644 --- a/docs/reference/index.html +++ b/docs/reference/index.html @@ -1,5 +1,5 @@ - + @@ -851,6 +851,80 @@ opacity: 1; transform: translateY(0); } + + /* ================================================ + VERSION SWITCHER + ================================================ */ + .version-switcher { + position: relative; + margin-left: 12px; + } + .version-btn { + background: var(--bg-raised); + color: var(--accent-cyan); + border: 1px solid var(--border-accent); + border-radius: var(--radius-sm); + padding: 4px 10px; + font-family: var(--font-mono); + font-size: 0.8rem; + cursor: pointer; + transition: background 0.2s; + display: flex; + align-items: center; + gap: 2px; + } + .version-btn:hover { background: var(--bg-card); } + .version-arrow { font-size: 0.7rem; } + .version-dropdown { + display: none; + position: absolute; + top: calc(100% + 6px); + left: 0; + background: var(--bg-raised); + border: 1px solid var(--border-accent); + border-radius: var(--radius-sm); + min-width: 160px; + z-index: 1000; + box-shadow: 0 8px 24px rgba(0,0,0,0.4); + } + .version-dropdown.open { display: block; } + .version-dropdown a { + display: block; + padding: 8px 14px; + color: var(--text-secondary); + text-decoration: none; + font-family: var(--font-mono); + font-size: 0.8rem; + transition: background 0.15s, color 0.15s; + } + .version-dropdown a:hover { + background: var(--bg-card); + color: var(--text-primary); + } + .version-dropdown a.active { + color: var(--accent-cyan); + background: var(--accent-glow); + } + .version-banner { + background: rgba(255, 193, 7, 0.12); + border-bottom: 1px solid rgba(255, 193, 7, 0.3); + color: #ffd54f; + text-align: center; + padding: 8px 16px; + font-family: var(--font-body); + font-size: 0.9rem; + position: fixed; + top: 0; + left: 0; + right: 0; + z-index: 10000; + } + .version-banner a { + color: #fff; + text-decoration: underline; + margin-left: 4px; + } + .version-banner a:hover { color: var(--accent-cyan); } @@ -2449,5 +2523,6 @@

    Policy Config

    cmdBlocks.forEach(el => scrollObserver.observe(el)); }); + diff --git a/docs/sitemap.xml b/docs/sitemap.xml index 78151ab..380a220 100644 --- a/docs/sitemap.xml +++ b/docs/sitemap.xml @@ -18,4 +18,100 @@ weekly 0.8 + + https://erishforg.github.io/git-parsec/v/0.3.3/ + 2026-04-23 + never + 0.3 + + + https://erishforg.github.io/git-parsec/v/0.3.3/guide/ + 2026-04-23 + never + 0.3 + + + https://erishforg.github.io/git-parsec/v/0.3.3/reference/ + 2026-04-23 + never + 0.3 + + + https://erishforg.github.io/git-parsec/v/0.3.2/ + 2026-04-21 + never + 0.3 + + + https://erishforg.github.io/git-parsec/v/0.3.2/guide/ + 2026-04-21 + never + 0.3 + + + https://erishforg.github.io/git-parsec/v/0.3.2/reference/ + 2026-04-21 + never + 0.3 + + + https://erishforg.github.io/git-parsec/v/0.3.1/ + 2026-04-21 + never + 0.3 + + + https://erishforg.github.io/git-parsec/v/0.3.1/guide/ + 2026-04-21 + never + 0.3 + + + https://erishforg.github.io/git-parsec/v/0.3.1/reference/ + 2026-04-21 + never + 0.3 + + + https://erishforg.github.io/git-parsec/v/0.3.0/ + 2026-04-16 + never + 0.3 + + + https://erishforg.github.io/git-parsec/v/0.2.4/ + 2026-04-15 + never + 0.3 + + + https://erishforg.github.io/git-parsec/v/0.2.3/ + 2026-04-15 + never + 0.3 + + + https://erishforg.github.io/git-parsec/v/0.2.2/ + 2026-04-15 + never + 0.3 + + + https://erishforg.github.io/git-parsec/v/0.2.1/ + 2026-04-15 + never + 0.3 + + + https://erishforg.github.io/git-parsec/v/0.2.0/ + 2026-04-14 + never + 0.3 + + + https://erishforg.github.io/git-parsec/v/0.1.1/ + 2026-04-14 + never + 0.3 + diff --git a/docs/v/0.1.1/index.html b/docs/v/0.1.1/index.html new file mode 100644 index 0000000..a6aa0ee --- /dev/null +++ b/docs/v/0.1.1/index.html @@ -0,0 +1,1869 @@ + + + + + + + git-parsec — Full-lifecycle worktree management + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    +
    +
    +
    Built with Rust
    +

    + From ticket to PR
    + in one command. +

    +

    + git-parsec manages the full lifecycle of git worktrees tied to your issue tracker. Start a ticket, code in parallel, ship a PR, and clean up -- all without leaving your terminal. +

    +
    + + Get Started + + + + + View on GitHub + +
    +
    +
    +
    +
    +
    +
    +
    parsec -- zsh
    +
    +
    +# Start working on a Jira ticket +$ parsec start CL-2283 +✓ Created worktree for CL-2283 + Title: Collect HeuristicCompletionException handling + Branch: feature/CL-2283 + Path: ../myproject.CL-2283 +  +# Work in parallel on another ticket +$ 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
    parallel workflows.
    +

    + Multiple developers or AI agents on the same repo fight over index.lock. + Worktrees solve isolation, but lack lifecycle management. +

    +
    + +
    +
    +
    + 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.

      +
      +
      • +
    +
    +
    +
    +
    + + +
    +
    +
    +
    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 Tracker Integration

    +

    + Connect to Jira or GitHub Issues. When you parsec start PROJ-123, the ticket title is + fetched automatically, branches are named consistently, and PR descriptions reference the original issue. + Manual --title fallback for offline or unsupported trackers. +

    +
    $ parsec start PROJ-123   # auto-fetches title from Jira
    +
    + + +
    +
    + +
    +

    Sibling Worktree Layout

    +

    + Worktrees placed adjacent to your repo as ../repo.ticket/. Clean, predictable, and compatible with your IDE. +

    +
    + + +
    +
    + +
    +

    One-step Shipping

    +

    + parsec ship pushes your branch, creates a GitHub PR with the ticket context, and cleans up the worktree. One command, done. +

    +
    + + +
    +
    + +
    +

    Cross-worktree Conflict Detection

    +

    + Detect when multiple worktrees modify the same files before you merge. Catch conflicts early, not at review time. +

    +
    + + +
    +
    + +
    +

    Shell Integration

    +

    + Add eval "$(parsec config shell zsh)" to your shell config and parsec switch teleports you into any worktree. +

    +
    + + +
    +
    + +
    +

    Post-create Hooks

    +

    + Automatically run npm install, cargo build, or any setup command after creating a new worktree. Zero manual steps. +

    +
    + + +
    +
    + +
    +

    JSON Output for AI Agents

    +

    + Every command supports --json for machine-readable output. Build automation pipelines, + integrate with AI coding agents, or script complex workflows. parsec is built to be both + human-friendly and agent-friendly. +

    +
    $ parsec list --json | jq '.[] | select(.commits > 0)'
    +
    +
    +
    +
    + + +
    +
    +
    +
    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-town
    Ticket tracker integrationJira + GitHub------
    Cross-worktree conflict detectionYes------
    One-step ship (push + PR + clean)Yes----Partial
    JSON output for AI agentsYesYes----
    Auto-cleanup merged worktreesYesYesManual--
    Status dashboardYesYes----
    Post-create hooksYes------
    Shell integration (cd into worktree)YesYes----
    +
    +
    +
    + + +
    +
    +
    +
    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 to connect your Jira or GitHub Issues instance.

    +
    parsec config init
    +
    +
    +
    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 +
    +
    +
    +
    +
    + + +
    +
    +
    +
    + Stop managing worktrees.
    + Start shipping tickets. +
    +

    + Join developers who use parsec to work on multiple tickets in parallel without the overhead. +

    +
    + + + Star on GitHub + +
    + $ cargo install git-parsec +
    +
    +
    +
    +
    + + + + + + + + + + diff --git a/docs/v/0.2.0/index.html b/docs/v/0.2.0/index.html new file mode 100644 index 0000000..73afea0 --- /dev/null +++ b/docs/v/0.2.0/index.html @@ -0,0 +1,1869 @@ + + + + + + + git-parsec — Full-lifecycle worktree management + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    +
    +
    +
    Built with Rust
    +

    + From ticket to PR
    + in one command. +

    +

    + git-parsec manages the full lifecycle of git worktrees tied to your issue tracker. Start a ticket, code in parallel, ship a PR, and clean up -- all without leaving your terminal. +

    +
    + + Get Started + + + + + View on GitHub + +
    +
    +
    +
    +
    +
    +
    +
    parsec -- zsh
    +
    +
    +# Start working on a Jira ticket +$ parsec start CL-2283 +✓ Created worktree for CL-2283 + Title: Collect HeuristicCompletionException handling + Branch: feature/CL-2283 + Path: ../myproject.CL-2283 +  +# Work in parallel on another ticket +$ 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
    parallel workflows.
    +

    + Multiple developers or AI agents on the same repo fight over index.lock. + Worktrees solve isolation, but lack lifecycle management. +

    +
    + +
    +
    +
    + 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.

      +
      +
      • +
    +
    +
    +
    +
    + + +
    +
    +
    +
    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 Tracker Integration

    +

    + Connect to Jira or GitHub Issues. When you parsec start PROJ-123, the ticket title is + fetched automatically, branches are named consistently, and PR descriptions reference the original issue. + Manual --title fallback for offline or unsupported trackers. +

    +
    $ parsec start PROJ-123   # auto-fetches title from Jira
    +
    + + +
    +
    + +
    +

    Sibling Worktree Layout

    +

    + Worktrees placed adjacent to your repo as ../repo.ticket/. Clean, predictable, and compatible with your IDE. +

    +
    + + +
    +
    + +
    +

    One-step Shipping

    +

    + parsec ship pushes your branch, creates a GitHub PR with the ticket context, and cleans up the worktree. One command, done. +

    +
    + + +
    +
    + +
    +

    Cross-worktree Conflict Detection

    +

    + Detect when multiple worktrees modify the same files before you merge. Catch conflicts early, not at review time. +

    +
    + + +
    +
    + +
    +

    Shell Integration

    +

    + Add eval "$(parsec config shell zsh)" to your shell config and parsec switch teleports you into any worktree. +

    +
    + + +
    +
    + +
    +

    Post-create Hooks

    +

    + Automatically run npm install, cargo build, or any setup command after creating a new worktree. Zero manual steps. +

    +
    + + +
    +
    + +
    +

    JSON Output for AI Agents

    +

    + Every command supports --json for machine-readable output. Build automation pipelines, + integrate with AI coding agents, or script complex workflows. parsec is built to be both + human-friendly and agent-friendly. +

    +
    $ parsec list --json | jq '.[] | select(.commits > 0)'
    +
    +
    +
    +
    + + +
    +
    +
    +
    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-town
    Ticket tracker integrationJira + GitHub------
    Cross-worktree conflict detectionYes------
    One-step ship (push + PR + clean)Yes----Partial
    JSON output for AI agentsYesYes----
    Auto-cleanup merged worktreesYesYesManual--
    Status dashboardYesYes----
    Post-create hooksYes------
    Shell integration (cd into worktree)YesYes----
    +
    +
    +
    + + +
    +
    +
    +
    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 to connect your Jira or GitHub Issues instance.

    +
    parsec config init
    +
    +
    +
    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 +
    +
    +
    +
    +
    + + +
    +
    +
    +
    + Stop managing worktrees.
    + Start shipping tickets. +
    +

    + Join developers who use parsec to work on multiple tickets in parallel without the overhead. +

    +
    + + + Star on GitHub + +
    + $ cargo install git-parsec +
    +
    +
    +
    +
    + + + + + + + + + + diff --git a/docs/v/0.2.1/index.html b/docs/v/0.2.1/index.html new file mode 100644 index 0000000..d3f01da --- /dev/null +++ b/docs/v/0.2.1/index.html @@ -0,0 +1,1939 @@ + + + + + + + git-parsec — Full-lifecycle worktree management + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    +
    +
    +
    Built with Rust
    +

    + From ticket to PR
    + in one command. +

    +

    + git-parsec manages the full lifecycle of git worktrees tied to your issue tracker. Start a ticket, code in parallel, ship a PR, and clean up -- all without leaving your terminal. +

    +
    + + Get Started + + + + + View on GitHub + +
    +
    +
    +
    +
    +
    +
    +
    parsec -- zsh
    +
    +
    +# Start working on a Jira ticket +$ parsec start CL-2283 +✓ Created worktree for CL-2283 + Title: Collect HeuristicCompletionException handling + Branch: feature/CL-2283 + Path: ../myproject.CL-2283 +  +# Work in parallel on another ticket +$ 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
    parallel workflows.
    +

    + Multiple developers or AI agents on the same repo fight over index.lock. + Worktrees solve isolation, but lack lifecycle management. +

    +
    + +
    +
    +
    + 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.

      +
      +
      • +
    +
    +
    +
    +
    + + +
    +
    +
    +
    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 Tracker Integration

    +

    + Connect to Jira or GitHub Issues. When you parsec start PROJ-123, the ticket title is + fetched automatically, branches are named consistently, and PR/MR descriptions reference the original issue. + Manual --title fallback for offline or unsupported trackers. +

    +
    $ parsec start PROJ-123   # auto-fetches title from Jira
    +
    + + +
    +
    + +
    +

    Sibling Worktree Layout

    +

    + Worktrees placed adjacent to your repo as ../repo.ticket/. Clean, predictable, and compatible with your IDE. +

    +
    + + +
    +
    + +
    +

    One-step Shipping

    +

    + parsec ship pushes your branch, creates a GitHub PR or GitLab MR with the ticket context, and cleans up the worktree. One command, done. +

    +
    + + +
    +
    + +
    +

    Cross-worktree Conflict Detection

    +

    + Detect when multiple worktrees modify the same files before you merge. Catch conflicts early, not at review time. +

    +
    + + +
    +
    + +
    +

    Shell Integration

    +

    + Add eval "$(parsec config shell zsh)" to your shell config and parsec switch teleports you into any worktree. +

    +
    + + +
    +
    + +
    +

    Post-create Hooks

    +

    + Automatically run npm install, cargo build, or any setup command after creating a new worktree. Zero manual steps. +

    +
    + + +
    +
    + +
    +

    JSON Output for AI Agents

    +

    + Every command supports --json for machine-readable output. Build automation pipelines, + integrate with AI coding agents, or script complex workflows. parsec is built to be both + human-friendly and agent-friendly. +

    +
    $ parsec list --json | jq '.[] | select(.commits > 0)'
    +
    + + +
    +
    + +
    +

    Adopt Existing Branches

    +

    + Already have a branch in flight? parsec adopt imports it into parsec management so you get full lifecycle tracking without starting over. +

    +
    $ parsec adopt PROJ-99 --branch fix/payment-timeout
    +
    + + +
    +
    + +
    +

    Operation History

    +

    + Every parsec action is logged. Use parsec log to review your full operation history, filter by ticket, or inspect the last N operations at a glance. +

    +
    $ parsec log --last 5   # or: parsec log PROJ-1234
    +
    + + +
    +
    + +
    +

    Undo Last Operation

    +

    + Made a mistake? parsec undo reverts the most recent operation. Use --dry-run to preview exactly what will be rolled back before committing. +

    +
    $ parsec undo --dry-run
    +
    +
    +
    +
    + + +
    +
    +
    +
    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--------
    Cross-worktree conflict detectionYes--------
    One-step ship (push + PR/MR + clean)GitHub + GitLab----PartialPR only
    JSON output for AI agentsYesYes------
    Auto-cleanup merged worktreesYesYesManual--Yes
    Status dashboardYesYes----Yes
    Post-create hooksYes--------
    Shell integration (cd into worktree)YesYes------
    Operation history & undoYes--------
    Adopt existing branchesYes--------
    +
    +
    +
    + + +
    +
    +
    +
    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 to connect your Jira or GitHub Issues instance.

    +
    parsec config init
    +
    +
    +
    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 +
    +
    +
    +
    +
    + + +
    +
    +
    +
    + Stop managing worktrees.
    + Start shipping tickets. +
    +

    + Join developers who use parsec to work on multiple tickets in parallel without the overhead. +

    +
    + + + Star on GitHub + +
    + $ cargo install git-parsec +
    +
    +
    +
    +
    + + + + + + + + + + diff --git a/docs/v/0.2.2/index.html b/docs/v/0.2.2/index.html new file mode 100644 index 0000000..a205f01 --- /dev/null +++ b/docs/v/0.2.2/index.html @@ -0,0 +1,1976 @@ + + + + + + + git-parsec — Full-lifecycle worktree management + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    +
    +
    +
    Built with Rust
    +

    + From ticket to PR
    + in one command. +

    +

    + git-parsec manages the full lifecycle of git worktrees tied to your issue tracker. Start a ticket, code in parallel, ship a PR, and clean up -- all without leaving your terminal. +

    +
    + + Get Started + + + + + View on GitHub + +
    +
    +
    +
    +
    +
    +
    +
    parsec -- zsh
    +
    +
    +# Start working on a Jira ticket +$ parsec start CL-2283 +✓ Created worktree for CL-2283 + Title: Collect HeuristicCompletionException handling + Branch: feature/CL-2283 + Path: ../myproject.CL-2283 +  +# Work in parallel on another ticket +$ 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
    parallel workflows.
    +

    + Multiple developers or AI agents on the same repo fight over index.lock. + Worktrees solve isolation, but lack lifecycle management. +

    +
    + +
    +
    +
    + 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 Tracker Integration

    +

    + Connect to Jira or GitHub Issues. When you parsec start PROJ-123, the ticket title is + fetched automatically, branches are named consistently, and PR/MR descriptions reference the original issue. + Manual --title fallback for offline or unsupported trackers. +

    +
    $ parsec start PROJ-123   # auto-fetches title from Jira
    +
    + + +
    +
    + +
    +

    Sibling Worktree Layout

    +

    + Worktrees placed adjacent to your repo as ../repo.ticket/. Clean, predictable, and compatible with your IDE. +

    +
    + + +
    +
    + +
    +

    One-step Shipping

    +

    + parsec ship pushes your branch, creates a GitHub PR or GitLab MR with the ticket context, and cleans up the worktree. One command, done. +

    +
    + + +
    +
    + +
    +

    Cross-worktree Conflict Detection

    +

    + Detect when multiple worktrees modify the same files before you merge. Catch conflicts early, not at review time. +

    +
    + + +
    +
    + +
    +

    Shell Integration

    +

    + Add eval "$(parsec config shell zsh)" to your shell config and parsec switch teleports you into any worktree. +

    +
    + + +
    +
    + +
    +

    Post-create Hooks

    +

    + Automatically run npm install, cargo build, or any setup command after creating a new worktree. Zero manual steps. +

    +
    + + +
    +
    + +
    +

    JSON Output for AI Agents

    +

    + Every command supports --json for machine-readable output. Build automation pipelines, + integrate with AI coding agents, or script complex workflows. parsec is built to be both + human-friendly and agent-friendly. +

    +
    $ parsec list --json | jq '.[] | select(.commits > 0)'
    +
    + + +
    +
    + +
    +

    Adopt Existing Branches

    +

    + Already have a branch in flight? parsec adopt imports it into parsec management so you get full lifecycle tracking without starting over. +

    +
    $ parsec adopt PROJ-99 --branch fix/payment-timeout
    +
    + + +
    +
    + +
    +

    Operation History

    +

    + Every parsec action is logged. Use parsec log to review your full operation history, filter by ticket, or inspect the last N operations at a glance. +

    +
    $ parsec log --last 5   # or: parsec log PROJ-1234
    +
    + + +
    +
    + +
    +

    Undo Last Operation

    +

    + Made a mistake? parsec undo reverts the most recent operation. Use --dry-run to preview exactly what will be rolled back before committing. +

    +
    $ parsec undo --dry-run
    +
    +
    +
    +
    + + +
    +
    +
    +
    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--------
    Cross-worktree conflict detectionYes--------
    One-step ship (push + PR/MR + clean)GitHub + GitLab----PartialPR only
    JSON output for AI agentsYesYes------
    Auto-cleanup merged worktreesYesYesManual--Yes
    Status dashboardYesYes----Yes
    Post-create hooksYes--------
    Shell integration (cd into worktree)YesYes------
    Operation history & undoYes--------
    Adopt existing branchesYes--------
    +
    +
    +
    + + +
    +
    +
    +
    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 to connect your Jira or GitHub Issues instance.

    +
    parsec config init
    +
    +
    +
    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 +
    +
    +
    +
    +
    + + +
    +
    +
    +
    + Stop managing worktrees.
    + Start shipping tickets. +
    +

    + Join developers who use parsec to work on multiple tickets in parallel without the overhead. +

    +
    + + + Star on GitHub + +
    + $ cargo install git-parsec +
    +
    +
    +
    +
    + + + + + + + + + + diff --git a/docs/v/0.2.3/index.html b/docs/v/0.2.3/index.html new file mode 100644 index 0000000..186d756 --- /dev/null +++ b/docs/v/0.2.3/index.html @@ -0,0 +1,2000 @@ + + + + + + + git-parsec — Full-lifecycle worktree management + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    +
    +
    +
    Built with Rust
    +

    + From ticket to PR
    + in one command. +

    +

    + git-parsec manages the full lifecycle of git worktrees tied to your issue tracker. Start a ticket, code in parallel, ship a PR, and clean up -- all without leaving your terminal. +

    +
    + + Get Started + + + + + View on GitHub + +
    +
    +
    +
    +
    +
    +
    +
    parsec -- zsh
    +
    +
    +# Start working on a Jira ticket +$ parsec start CL-2283 +✓ Created worktree for CL-2283 + Title: Collect HeuristicCompletionException handling + Branch: feature/CL-2283 + Path: ../myproject.CL-2283 +  +# Work in parallel on another ticket +$ 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
    parallel workflows.
    +

    + Multiple developers or AI agents on the same repo fight over index.lock. + Worktrees solve isolation, but lack lifecycle management. +

    +
    + +
    +
    +
    + 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 Tracker Integration

    +

    + Connect to Jira or GitHub Issues. When you parsec start PROJ-123, the ticket title is + fetched automatically, branches are named consistently, and PR/MR descriptions reference the original issue. + Manual --title fallback for offline or unsupported trackers. +

    +
    $ parsec start PROJ-123   # auto-fetches title from Jira
    +
    + + +
    +
    + +
    +

    Sibling Worktree Layout

    +

    + Worktrees placed adjacent to your repo as ../repo.ticket/. Clean, predictable, and compatible with your IDE. +

    +
    + + +
    +
    + +
    +

    One-step Shipping

    +

    + parsec ship pushes your branch, creates a GitHub PR or GitLab MR with the ticket context, and cleans up the worktree. One command, done. +

    +
    + + +
    +
    + +
    +

    Cross-worktree Conflict Detection

    +

    + Detect when multiple worktrees modify the same files before you merge. Catch conflicts early, not at review time. +

    +
    + + +
    +
    + +
    +

    Shell Integration & Completions

    +

    + Auto-cd with parsec switch, tab-completions for zsh/bash/fish/powershell, and a man page — all built in. +

    +
    + + +
    +
    + +
    +

    Branch Sync

    +

    + Keep worktrees fresh with parsec sync — rebase or merge the latest base branch into one or all worktrees at once. +

    +
    + + +
    +
    + +
    +

    JSON Output for AI Agents

    +

    + Every command supports --json for machine-readable output. Build automation pipelines, + integrate with AI coding agents, or script complex workflows. parsec is built to be both + human-friendly and agent-friendly. +

    +
    $ parsec list --json | jq '.[] | select(.commits > 0)'
    +
    + + +
    +
    + +
    +

    Adopt Existing Branches

    +

    + Already have a branch in flight? parsec adopt imports it into parsec management so you get full lifecycle tracking without starting over. +

    +
    $ parsec adopt PROJ-99 --branch fix/payment-timeout
    +
    + + +
    +
    + +
    +

    Operation History

    +

    + Every parsec action is logged. Use parsec log to review your full operation history, filter by ticket, or inspect the last N operations at a glance. +

    +
    $ parsec log --last 5   # or: parsec log PROJ-1234
    +
    + + +
    +
    + +
    +

    Undo Last Operation

    +

    + Made a mistake? parsec undo reverts the most recent operation. Use --dry-run to preview exactly what will be rolled back before committing. +

    +
    $ parsec undo --dry-run
    +
    + + +
    +
    + +
    +

    Open in Browser

    +

    + parsec open launches the PR or ticket page in your browser. Works with GitHub, GitLab, and Jira. +

    +
    $ parsec open PROJ-1234
    +
    + + +
    +
    + +
    +

    PR Status Dashboard

    +

    + parsec pr-status shows CI checks, review approvals, and merge state for all shipped PRs in one color-coded table. +

    +
    $ parsec pr-status PROJ-1234
    +
    +
    +
    +
    + + +
    +
    +
    +
    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--------
    Cross-worktree conflict detectionYes--------
    One-step ship (push + PR/MR + clean)GitHub + GitLab----PartialPR only
    JSON output for AI agentsYesYes------
    Auto-cleanup merged worktreesYesYesManual--Yes
    Status dashboardYesYes----Yes
    Post-create hooksYes--------
    Shell integration (cd into worktree)YesYes------
    Operation history & undoYes--------
    Adopt existing branchesYes--------
    +
    +
    +
    + + +
    +
    +
    +
    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 and tab-completions.

    +
    parsec config init
    eval "$(parsec config completions 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 +
    +
    +
    +
    +
    + + +
    +
    +
    +
    + Stop managing worktrees.
    + Start shipping tickets. +
    +

    + Join developers who use parsec to work on multiple tickets in parallel without the overhead. +

    +
    + + + Star on GitHub + +
    + $ cargo install git-parsec +
    +
    +
    +
    +
    + + + + + + + + + + diff --git a/docs/v/0.2.4/index.html b/docs/v/0.2.4/index.html new file mode 100644 index 0000000..7fc0124 --- /dev/null +++ b/docs/v/0.2.4/index.html @@ -0,0 +1,2137 @@ + + + + + + + git-parsec — Full-lifecycle worktree management + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    +
    +
    +
    Built with Rust
    +

    + From ticket to PR
    + in one command. +

    +

    + git-parsec manages the full lifecycle of git worktrees tied to your issue tracker. Start a ticket, code in parallel, ship a PR, and clean up -- all without leaving your terminal. +

    +
    + + Get Started + + + + + View on GitHub + +
    +
    +
    +
    +
    +
    +
    +
    parsec -- zsh
    +
    +
    +# Start working on a Jira ticket +$ parsec start CL-2283 +✓ Created worktree for CL-2283 + Title: Collect HeuristicCompletionException handling + Branch: feature/CL-2283 + Path: ../myproject.CL-2283 +  +# Work in parallel on another ticket +$ 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
    parallel workflows.
    +

    + Multiple developers or AI agents on the same repo fight over index.lock. + Worktrees solve isolation, but lack lifecycle management. +

    +
    + +
    +
    +
    + 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 Tracker Integration

    +

    + Connect to Jira or GitHub Issues. When you parsec start PROJ-123, the ticket title is + fetched automatically, branches are named consistently, and PR/MR descriptions reference the original issue. + Manual --title fallback for offline or unsupported trackers. +

    +
    $ parsec start PROJ-123   # auto-fetches title from Jira
    +
    + + +
    +
    + +
    +

    Sibling Worktree Layout

    +

    + Worktrees placed adjacent to your repo as ../repo.ticket/. Clean, predictable, and compatible with your IDE. +

    +
    + + +
    +
    + +
    +

    One-step Shipping

    +

    + parsec ship pushes your branch, creates a GitHub PR or GitLab MR with the ticket context, and cleans up the worktree. One command, done. +

    +
    + + +
    +
    + +
    +

    Cross-worktree Conflict Detection

    +

    + Detect when multiple worktrees modify the same files before you merge. Catch conflicts early, not at review time. +

    +
    + + +
    +
    + +
    +

    Shell Integration & Completions

    +

    + Auto-cd with parsec switch, tab-completions for zsh/bash/fish/powershell, and a man page — all built in. +

    +
    + + +
    +
    + +
    +

    Branch Sync

    +

    + Keep worktrees fresh with parsec sync — rebase or merge the latest base branch into one or all worktrees at once. +

    +
    + + +
    +
    + +
    +

    JSON Output for AI Agents

    +

    + Every command supports --json for machine-readable output. Build automation pipelines, + integrate with AI coding agents, or script complex workflows. parsec is built to be both + human-friendly and agent-friendly. +

    +
    $ parsec list --json | jq '.[] | select(.commits > 0)'
    +
    + + +
    +
    + +
    +

    Adopt Existing Branches

    +

    + Already have a branch in flight? parsec adopt imports it into parsec management so you get full lifecycle tracking without starting over. +

    +
    $ parsec adopt PROJ-99 --branch fix/payment-timeout
    +
    + + +
    +
    + +
    +

    Attach to Existing Branch

    +

    + Need to work on a branch that already exists? parsec start --branch creates a managed worktree from any local or remote branch. Fetches remote-only branches automatically. +

    +
    $ parsec start CL-2208 --branch feature/CL-2208
    +
    + + +
    +
    + +
    +

    Operation History

    +

    + Every parsec action is logged. Use parsec log to review your full operation history, filter by ticket, or inspect the last N operations at a glance. +

    +
    $ parsec log --last 5   # or: parsec log PROJ-1234
    +
    + + +
    +
    + +
    +

    Undo Last Operation

    +

    + Made a mistake? parsec undo reverts the most recent operation. Use --dry-run to preview exactly what will be rolled back before committing. +

    +
    $ parsec undo --dry-run
    +
    + + +
    +
    + +
    +

    Open in Browser

    +

    + parsec open launches the PR or ticket page in your browser. Works with GitHub, GitLab, and Jira. +

    +
    $ parsec open PROJ-1234
    +
    + + +
    +
    + +
    +

    PR Status Dashboard

    +

    + parsec pr-status shows CI checks, review approvals, and merge state for all shipped PRs in one color-coded table. +

    +
    $ parsec pr-status PROJ-1234
    +
    + + +
    +
    + +
    +

    Stacked PRs

    +

    + Create dependent PR chains with --on. parsec stack shows the dependency graph and --sync rebases the entire chain. +

    +
    $ parsec start PROJ-2 --on PROJ-1
    +
    + + +
    +
    + +
    +

    CI Pipeline Dashboard

    +

    + parsec ci shows individual check runs, durations, and overall status. Use --watch to poll until completion. +

    +
    $ parsec ci --watch
    +
    + + +
    +
    + +
    +

    Merge from Terminal

    +

    + parsec merge merges PRs directly from your terminal. Waits for CI to pass, supports squash and rebase, and cleans up automatically. +

    +
    $ parsec merge PROJ-1234
    +
    + + +
    +
    + +
    +

    Worktree Diff

    +

    + parsec diff shows changes in any worktree compared to its base branch. Supports --stat and --name-only views. +

    +
    $ parsec diff --stat
    +
    +
    +
    +
    + + +
    +
    +
    +
    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--------
    Cross-worktree conflict detectionYes--------
    One-step ship (push + PR/MR + clean)GitHub + GitLab----PartialPR only
    JSON output for AI agentsYesYes------
    Auto-cleanup merged worktreesYesYesManual--Yes
    Status dashboardYesYes----Yes
    Post-create hooksYes--------
    Shell integration (cd into worktree)YesYes------
    Operation history & undoYes--------
    Adopt existing branchesYes--------
    Attach to existing branchYes--------
    +
    +
    +
    + + +
    +
    +
    +
    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 and tab-completions.

    +
    parsec config init
    eval "$(parsec config completions 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 +
    +
    +
    +
    +
    + + +
    +
    +
    +
    + Stop managing worktrees.
    + Start shipping tickets. +
    +

    + Join developers who use parsec to work on multiple tickets in parallel without the overhead. +

    +
    + + + Star on GitHub + +
    + $ cargo install git-parsec +
    +
    +
    +
    +
    + + + + + + + + + + diff --git a/docs/v/0.3.0/index.html b/docs/v/0.3.0/index.html new file mode 100644 index 0000000..041ddcf --- /dev/null +++ b/docs/v/0.3.0/index.html @@ -0,0 +1,2145 @@ + + + + + + + git-parsec — Full-lifecycle worktree management + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    +
    +
    +
    Built with Rust
    +

    + From ticket to PR
    + in one command. +

    +

    + git-parsec manages the full lifecycle of git worktrees tied to your issue tracker. Start a ticket, code in parallel, ship a PR, and clean up -- all without leaving your terminal. +

    +
    + + Get Started + + + + + View on GitHub + +
    +
    +
    +
    +
    +
    +
    +
    parsec -- zsh
    +
    +
    +# Start working on a Jira ticket +$ parsec start CL-2283 +✓ Created worktree for CL-2283 + Title: Collect HeuristicCompletionException handling + Branch: feature/CL-2283 + Path: ../myproject.CL-2283 +  +# Work in parallel on another ticket +$ 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
    parallel workflows.
    +

    + Multiple developers or AI agents on the same repo fight over index.lock. + Worktrees solve isolation, but lack lifecycle management. +

    +
    + +
    +
    +
    + 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 Tracker Integration

    +

    + Connect to Jira or GitHub Issues. When you parsec start PROJ-123, the ticket title is + fetched automatically, branches are named consistently, and PR/MR descriptions reference the original issue. + Manual --title fallback for offline or unsupported trackers. +

    +
    $ parsec start PROJ-123   # auto-fetches title from Jira
    +
    + + +
    +
    + +
    +

    Sibling Worktree Layout

    +

    + Worktrees placed adjacent to your repo as ../repo.ticket/. Clean, predictable, and compatible with your IDE. +

    +
    + + +
    +
    + +
    +

    One-step Shipping

    +

    + parsec ship pushes your branch, creates a GitHub PR or GitLab MR with the ticket context, and cleans up the worktree. One command, done. +

    +
    + + +
    +
    + +
    +

    Cross-worktree Conflict Detection

    +

    + Detect when multiple worktrees modify the same files before you merge. Catch conflicts early, not at review time. +

    +
    + + +
    +
    + +
    +

    Shell Integration & Completions

    +

    + Auto-cd with parsec switch, tab-completions for zsh/bash/fish/powershell, and a man page — all built in. +

    +
    + + +
    +
    + +
    +

    Branch Sync

    +

    + Keep worktrees fresh with parsec sync — rebase or merge the latest base branch into one or all worktrees at once. +

    +
    + + +
    +
    + +
    +

    JSON Output for AI Agents

    +

    + Every command supports --json for machine-readable output. Build automation pipelines, + integrate with AI coding agents, or script complex workflows. parsec is built to be both + human-friendly and agent-friendly. +

    +
    $ parsec list --json | jq '.[] | select(.commits > 0)'
    +
    + + +
    +
    + +
    +

    Adopt Existing Branches

    +

    + Already have a branch in flight? parsec adopt imports it into parsec management so you get full lifecycle tracking without starting over. +

    +
    $ parsec adopt PROJ-99 --branch fix/payment-timeout
    +
    + + +
    +
    + +
    +

    Attach to Existing Branch

    +

    + Need to work on a branch that already exists? parsec start --branch creates a managed worktree from any local or remote branch. Fetches remote-only branches automatically. +

    +
    $ parsec start CL-2208 --branch feature/CL-2208
    +
    + + +
    +
    + +
    +

    Operation History

    +

    + Every parsec action is logged. Use parsec log to review your full operation history, filter by ticket, or inspect the last N operations at a glance. +

    +
    $ parsec log --last 5   # or: parsec log PROJ-1234
    +
    + + +
    +
    + +
    +

    Undo Last Operation

    +

    + Made a mistake? parsec undo reverts the most recent operation. Use --dry-run to preview exactly what will be rolled back before committing. +

    +
    $ parsec undo --dry-run
    +
    + + +
    +
    + +
    +

    Open in Browser

    +

    + parsec open launches the PR or ticket page in your browser. Works with GitHub, GitLab, and Jira. +

    +
    $ parsec open PROJ-1234
    +
    + + +
    +
    + +
    +

    PR Status Dashboard

    +

    + parsec pr-status shows CI checks, review approvals, and merge state for all shipped PRs in one color-coded table. +

    +
    $ parsec pr-status PROJ-1234
    +
    + + +
    +
    + +
    +

    Stacked PRs

    +

    + Create dependent PR chains with --on. parsec stack shows the dependency graph and --sync rebases the entire chain. +

    +
    $ parsec start PROJ-2 --on PROJ-1
    +
    + + +
    +
    + +
    +

    CI Pipeline Dashboard

    +

    + parsec ci shows individual check runs, durations, and overall status. Use --watch to poll until completion. +

    +
    $ parsec ci --watch
    +
    + + +
    +
    + +
    +

    Merge from Terminal

    +

    + parsec merge merges PRs directly from your terminal. Waits for CI to pass, supports squash and rebase, and cleans up automatically. +

    +
    $ parsec merge PROJ-1234
    +
    + + +
    +
    + +
    +

    Worktree Diff

    +

    + parsec diff shows changes in any worktree compared to its base branch. Supports --stat and --name-only views. +

    +
    $ parsec diff --stat
    +
    +
    +
    +
    + + +
    +
    +
    +
    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 and tab-completions.

    +
    parsec config init
    eval "$(parsec config completions 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 +
    +
    +
    +
    +
    + + +
    +
    +
    +
    + Stop managing worktrees.
    + Start shipping tickets. +
    +

    + Join developers who use parsec to work on multiple tickets in parallel without the overhead. +

    +
    + + + Star on GitHub + +
    + $ cargo install git-parsec +
    +
    +
    +
    +
    + + + + + + + + + + diff --git a/docs/v/0.3.1/guide/index.html b/docs/v/0.3.1/guide/index.html new file mode 100644 index 0000000..d010aa3 --- /dev/null +++ b/docs/v/0.3.1/guide/index.html @@ -0,0 +1,1705 @@ + + + + + + + Guide — git-parsec + + + + + + + + + + + + + + + + + + + +
    + + + + + +
    +
    + + +
    +
    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.2.4 +
    +
    + +

    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"
    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.0 +✓ Merged develop → main +✓ Tagged v0.3.0 +✓ GitHub Release: github.com/org/repo/releases/tag/v0.3.0 +  +# 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.

    +
    +
    +
    + +
    + +
    +
    + + + + + + + + + diff --git a/docs/v/0.3.1/index.html b/docs/v/0.3.1/index.html new file mode 100644 index 0000000..bdfcb40 --- /dev/null +++ b/docs/v/0.3.1/index.html @@ -0,0 +1,2151 @@ + + + + + + + git-parsec — Full-lifecycle worktree management + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    +
    +
    +
    +
    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 Tracker Integration

    +

    + Connect to Jira or GitHub Issues. When you parsec start PROJ-123, the ticket title is + fetched automatically, branches are named consistently, and PR/MR descriptions reference the original issue. + Manual --title fallback for offline or unsupported trackers. +

    +
    $ parsec start PROJ-123   # auto-fetches title from Jira
    +
    + + +
    +
    + +
    +

    Sibling Worktree Layout

    +

    + Worktrees placed adjacent to your repo as ../repo.ticket/. Clean, predictable, and compatible with your IDE. +

    +
    + + +
    +
    + +
    +

    One-step Shipping

    +

    + parsec ship pushes your branch, creates a GitHub PR or GitLab MR with the ticket context, and cleans up the worktree. One command, done. +

    +
    + + +
    +
    + +
    +

    Cross-worktree Conflict Detection

    +

    + Detect when multiple worktrees modify the same files before you merge. Catch conflicts early, not at review time. +

    +
    + + +
    +
    + +
    +

    Shell Integration & Completions

    +

    + Auto-cd with parsec switch, tab-completions for zsh/bash/fish/powershell, and a man page — all built in. +

    +
    + + +
    +
    + +
    +

    Branch Sync

    +

    + Keep worktrees fresh with parsec sync — rebase or merge the latest base branch into one or all worktrees at once. +

    +
    + + +
    +
    + +
    +

    JSON Output for AI Agents

    +

    + Every command supports --json for machine-readable output. Build automation pipelines, + integrate with AI coding agents, or script complex workflows. parsec is built to be both + human-friendly and agent-friendly. +

    +
    $ parsec list --json | jq '.[] | select(.commits > 0)'
    +
    + + +
    +
    + +
    +

    Adopt Existing Branches

    +

    + Already have a branch in flight? parsec adopt imports it into parsec management so you get full lifecycle tracking without starting over. +

    +
    $ parsec adopt PROJ-99 --branch fix/payment-timeout
    +
    + + +
    +
    + +
    +

    Attach to Existing Branch

    +

    + Need to work on a branch that already exists? parsec start --branch creates a managed worktree from any local or remote branch. Fetches remote-only branches automatically. +

    +
    $ parsec start CL-2208 --branch feature/CL-2208
    +
    + + +
    +
    + +
    +

    Operation History

    +

    + Every parsec action is logged. Use parsec log to review your full operation history, filter by ticket, or inspect the last N operations at a glance. +

    +
    $ parsec log --last 5   # or: parsec log PROJ-1234
    +
    + + +
    +
    + +
    +

    Undo Last Operation

    +

    + Made a mistake? parsec undo reverts the most recent operation. Use --dry-run to preview exactly what will be rolled back before committing. +

    +
    $ parsec undo --dry-run
    +
    + + +
    +
    + +
    +

    Open in Browser

    +

    + parsec open launches the PR or ticket page in your browser. Works with GitHub, GitLab, and Jira. +

    +
    $ parsec open PROJ-1234
    +
    + + +
    +
    + +
    +

    PR Status Dashboard

    +

    + parsec pr-status shows CI checks, review approvals, and merge state for all shipped PRs in one color-coded table. +

    +
    $ parsec pr-status PROJ-1234
    +
    + + +
    +
    + +
    +

    Stacked PRs

    +

    + Create dependent PR chains with --on. parsec stack shows the dependency graph and --sync rebases the entire chain. +

    +
    $ parsec start PROJ-2 --on PROJ-1
    +
    + + +
    +
    + +
    +

    CI Pipeline Dashboard

    +

    + parsec ci shows individual check runs, durations, and overall status. Use --watch to poll until completion. +

    +
    $ parsec ci --watch
    +
    + + +
    +
    + +
    +

    Merge from Terminal

    +

    + parsec merge merges PRs directly from your terminal. Waits for CI to pass, supports squash and rebase, and cleans up automatically. +

    +
    $ parsec merge PROJ-1234
    +
    + + +
    +
    + +
    +

    Worktree Diff

    +

    + parsec diff shows changes in any worktree compared to its base branch. Supports --stat and --name-only views. +

    +
    $ parsec diff --stat
    +
    +
    +
    +
    + + +
    +
    +
    +
    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.3.1/reference/index.html b/docs/v/0.3.1/reference/index.html new file mode 100644 index 0000000..e6864e3 --- /dev/null +++ b/docs/v/0.3.1/reference/index.html @@ -0,0 +1,2289 @@ + + + + + + + Command Reference — git-parsec + + + + + + + + + + + + + + + + + + + +
    + + + + + +
    +
    + + +
    +
    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
    +
    +
    + + +
    +
    +

    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.
    +
    + +
    +
    +
    + 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 +
    +
    +
    + + +
    +
    + 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.
    +
    + +
    +
    +
    + parsec stack +
    +
    +$ parsec stack + main + └── feature/PROJ-123 (PROJ-123) PR #42 open + └── feature/PROJ-124 (PROJ-124) PR #43 open +
    +
    +
    + + +
    +
    + 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.
    +
    + +
    +
    +
    + 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 +
    +
    +
    + + +
    +
    + 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.
    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 +
    +
    +
    + + +
    +
    + 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}).
    +
    + +
    +
    +
    + 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 +
    +
    +
    + + +
    +
    + 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 +
    +
    +
    + +
    + + +
    + +
    +
    + + + + + + + + + diff --git a/docs/v/0.3.2/guide/index.html b/docs/v/0.3.2/guide/index.html new file mode 100644 index 0000000..d3a3f7d --- /dev/null +++ b/docs/v/0.3.2/guide/index.html @@ -0,0 +1,1705 @@ + + + + + + + Guide — git-parsec + + + + + + + + + + + + + + + + + + + +
    + + + + + +
    +
    + + +
    +
    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.2.4 +
    +
    + +

    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"
    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.0 +✓ Merged develop → main +✓ Tagged v0.3.0 +✓ GitHub Release: github.com/org/repo/releases/tag/v0.3.0 +  +# 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.

    +
    +
    +
    + +
    + +
    +
    + + + + + + + + + diff --git a/docs/v/0.3.2/index.html b/docs/v/0.3.2/index.html new file mode 100644 index 0000000..1c3e967 --- /dev/null +++ b/docs/v/0.3.2/index.html @@ -0,0 +1,2151 @@ + + + + + + + git-parsec — Full-lifecycle worktree management + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    +
    +
    +
    +
    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 Tracker Integration

    +

    + Connect to Jira or GitHub Issues. When you parsec start PROJ-123, the ticket title is + fetched automatically, branches are named consistently, and PR/MR descriptions reference the original issue. + Manual --title fallback for offline or unsupported trackers. +

    +
    $ parsec start PROJ-123   # auto-fetches title from Jira
    +
    + + +
    +
    + +
    +

    Sibling Worktree Layout

    +

    + Worktrees placed adjacent to your repo as ../repo.ticket/. Clean, predictable, and compatible with your IDE. +

    +
    + + +
    +
    + +
    +

    One-step Shipping

    +

    + parsec ship pushes your branch, creates a GitHub PR or GitLab MR with the ticket context, and cleans up the worktree. One command, done. +

    +
    + + +
    +
    + +
    +

    Cross-worktree Conflict Detection

    +

    + Detect when multiple worktrees modify the same files before you merge. Catch conflicts early, not at review time. +

    +
    + + +
    +
    + +
    +

    Shell Integration & Completions

    +

    + Auto-cd with parsec switch, tab-completions for zsh/bash/fish/powershell, and a man page — all built in. +

    +
    + + +
    +
    + +
    +

    Branch Sync

    +

    + Keep worktrees fresh with parsec sync — rebase or merge the latest base branch into one or all worktrees at once. +

    +
    + + +
    +
    + +
    +

    JSON Output for AI Agents

    +

    + Every command supports --json for machine-readable output. Build automation pipelines, + integrate with AI coding agents, or script complex workflows. parsec is built to be both + human-friendly and agent-friendly. +

    +
    $ parsec list --json | jq '.[] | select(.commits > 0)'
    +
    + + +
    +
    + +
    +

    Adopt Existing Branches

    +

    + Already have a branch in flight? parsec adopt imports it into parsec management so you get full lifecycle tracking without starting over. +

    +
    $ parsec adopt PROJ-99 --branch fix/payment-timeout
    +
    + + +
    +
    + +
    +

    Attach to Existing Branch

    +

    + Need to work on a branch that already exists? parsec start --branch creates a managed worktree from any local or remote branch. Fetches remote-only branches automatically. +

    +
    $ parsec start CL-2208 --branch feature/CL-2208
    +
    + + +
    +
    + +
    +

    Operation History

    +

    + Every parsec action is logged. Use parsec log to review your full operation history, filter by ticket, or inspect the last N operations at a glance. +

    +
    $ parsec log --last 5   # or: parsec log PROJ-1234
    +
    + + +
    +
    + +
    +

    Undo Last Operation

    +

    + Made a mistake? parsec undo reverts the most recent operation. Use --dry-run to preview exactly what will be rolled back before committing. +

    +
    $ parsec undo --dry-run
    +
    + + +
    +
    + +
    +

    Open in Browser

    +

    + parsec open launches the PR or ticket page in your browser. Works with GitHub, GitLab, and Jira. +

    +
    $ parsec open PROJ-1234
    +
    + + +
    +
    + +
    +

    PR Status Dashboard

    +

    + parsec pr-status shows CI checks, review approvals, and merge state for all shipped PRs in one color-coded table. +

    +
    $ parsec pr-status PROJ-1234
    +
    + + +
    +
    + +
    +

    Stacked PRs

    +

    + Create dependent PR chains with --on. parsec stack shows the dependency graph and --sync rebases the entire chain. +

    +
    $ parsec start PROJ-2 --on PROJ-1
    +
    + + +
    +
    + +
    +

    CI Pipeline Dashboard

    +

    + parsec ci shows individual check runs, durations, and overall status. Use --watch to poll until completion. +

    +
    $ parsec ci --watch
    +
    + + +
    +
    + +
    +

    Merge from Terminal

    +

    + parsec merge merges PRs directly from your terminal. Waits for CI to pass, supports squash and rebase, and cleans up automatically. +

    +
    $ parsec merge PROJ-1234
    +
    + + +
    +
    + +
    +

    Worktree Diff

    +

    + parsec diff shows changes in any worktree compared to its base branch. Supports --stat and --name-only views. +

    +
    $ parsec diff --stat
    +
    +
    +
    +
    + + +
    +
    +
    +
    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.3.2/reference/index.html b/docs/v/0.3.2/reference/index.html new file mode 100644 index 0000000..b89ef7e --- /dev/null +++ b/docs/v/0.3.2/reference/index.html @@ -0,0 +1,2289 @@ + + + + + + + Command Reference — git-parsec + + + + + + + + + + + + + + + + + + + +
    + + + + + +
    +
    + + +
    +
    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
    +
    +
    + + +
    +
    +

    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.
    +
    + +
    +
    +
    + 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 +
    +
    +
    + + +
    +
    + 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.
    +
    + +
    +
    +
    + parsec stack +
    +
    +$ parsec stack + main + └── feature/PROJ-123 (PROJ-123) PR #42 open + └── feature/PROJ-124 (PROJ-124) PR #43 open +
    +
    +
    + + +
    +
    + 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.
    +
    + +
    +
    +
    + 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 +
    +
    +
    + + +
    +
    + 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.
    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 +
    +
    +
    + + +
    +
    + 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}).
    +
    + +
    +
    +
    + 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 +
    +
    +
    + + +
    +
    + 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 +
    +
    +
    + +
    + + +
    + +
    +
    + + + + + + + + + diff --git a/docs/v/0.3.3/guide/index.html b/docs/v/0.3.3/guide/index.html new file mode 100644 index 0000000..a22fc8d --- /dev/null +++ b/docs/v/0.3.3/guide/index.html @@ -0,0 +1,1792 @@ + + + + + + + Guide — git-parsec + + + + + + + + + + + + + + + + + + + + + + + + +
    + + + + + +
    +
    + + +
    +
    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"
    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.

    +
    +
    +
    + +
    + +
    +
    + + + + + + + + + diff --git a/docs/v/0.3.3/index.html b/docs/v/0.3.3/index.html new file mode 100644 index 0000000..c256cc8 --- /dev/null +++ b/docs/v/0.3.3/index.html @@ -0,0 +1,2259 @@ + + + + + + + git-parsec — Full-lifecycle worktree management + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    +
    +
    +
    +
    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 Tracker Integration

    +

    + Connect to Jira or GitHub Issues. When you parsec start PROJ-123, the ticket title is + fetched automatically, branches are named consistently, and PR/MR descriptions reference the original issue. + Manual --title fallback for offline or unsupported trackers. +

    +
    $ parsec start PROJ-123   # auto-fetches title from Jira
    +
    + + +
    +
    + +
    +

    Sibling Worktree Layout

    +

    + Worktrees placed adjacent to your repo as ../repo.ticket/. Clean, predictable, and compatible with your IDE. +

    +
    + + +
    +
    + +
    +

    One-step Shipping

    +

    + parsec ship pushes your branch, creates a GitHub PR or GitLab MR with the ticket context, and cleans up the worktree. One command, done. +

    +
    + + +
    +
    + +
    +

    Cross-worktree Conflict Detection

    +

    + Detect when multiple worktrees modify the same files before you merge. Catch conflicts early, not at review time. +

    +
    + + +
    +
    + +
    +

    Shell Integration & Completions

    +

    + Auto-cd with parsec switch, tab-completions for zsh/bash/fish/powershell, and a man page — all built in. +

    +
    + + +
    +
    + +
    +

    Branch Sync

    +

    + Keep worktrees fresh with parsec sync — rebase or merge the latest base branch into one or all worktrees at once. +

    +
    + + +
    +
    + +
    +

    JSON Output for AI Agents

    +

    + Every command supports --json for machine-readable output. Build automation pipelines, + integrate with AI coding agents, or script complex workflows. parsec is built to be both + human-friendly and agent-friendly. +

    +
    $ parsec list --json | jq '.[] | select(.commits > 0)'
    +
    + + +
    +
    + +
    +

    Adopt Existing Branches

    +

    + Already have a branch in flight? parsec adopt imports it into parsec management so you get full lifecycle tracking without starting over. +

    +
    $ parsec adopt PROJ-99 --branch fix/payment-timeout
    +
    + + +
    +
    + +
    +

    Attach to Existing Branch

    +

    + Need to work on a branch that already exists? parsec start --branch creates a managed worktree from any local or remote branch. Fetches remote-only branches automatically. +

    +
    $ parsec start CL-2208 --branch feature/CL-2208
    +
    + + +
    +
    + +
    +

    Operation History

    +

    + Every parsec action is logged. Use parsec log to review your full operation history, filter by ticket, or inspect the last N operations at a glance. +

    +
    $ parsec log --last 5   # or: parsec log PROJ-1234
    +
    + + +
    +
    + +
    +

    Undo Last Operation

    +

    + Made a mistake? parsec undo reverts the most recent operation. Use --dry-run to preview exactly what will be rolled back before committing. +

    +
    $ parsec undo --dry-run
    +
    + + +
    +
    + +
    +

    Open in Browser

    +

    + parsec open launches the PR or ticket page in your browser. Works with GitHub, GitLab, and Jira. +

    +
    $ parsec open PROJ-1234
    +
    + + +
    +
    + +
    +

    PR Status Dashboard

    +

    + parsec pr-status shows CI checks, review approvals, and merge state for all shipped PRs in one color-coded table. +

    +
    $ parsec pr-status PROJ-1234
    +
    + + +
    +
    + +
    +

    Stacked PRs

    +

    + Create dependent PR chains with --on. parsec stack shows the dependency graph and --sync rebases the entire chain. +

    +
    $ parsec start PROJ-2 --on PROJ-1
    +
    + + +
    +
    + +
    +

    CI Pipeline Dashboard

    +

    + parsec ci shows individual check runs, durations, and overall status. Use --watch to poll until completion. +

    +
    $ parsec ci --watch
    +
    + + +
    +
    + +
    +

    Merge from Terminal

    +

    + parsec merge merges PRs directly from your terminal. Waits for CI to pass, supports squash and rebase, and cleans up automatically. +

    +
    $ parsec merge PROJ-1234
    +
    + + +
    +
    + +
    +

    Worktree Diff

    +

    + parsec diff shows changes in any worktree compared to its base branch. Supports --stat and --name-only views. +

    +
    $ parsec diff --stat
    +
    +
    +
    +
    + + +
    +
    +
    +
    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.3.3/reference/index.html b/docs/v/0.3.3/reference/index.html new file mode 100644 index 0000000..c67dbe6 --- /dev/null +++ b/docs/v/0.3.3/reference/index.html @@ -0,0 +1,2529 @@ + + + + + + + Command Reference — git-parsec + + + + + + + + + + + + + + + + + + + + + + + +
    + + + + + +
    +
    + + +
    +
    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
    +
    +
    + + +
    +
    +

    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.
    +
    + +
    +
    +
    + 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 +
    +
    +
    + + +
    +
    + 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.
    +
    + +
    +
    +
    + parsec stack +
    +
    +$ parsec stack + main + └── feature/PROJ-123 (PROJ-123) PR #42 open + └── feature/PROJ-124 (PROJ-124) PR #43 open +
    +
    +
    + + +
    +
    + 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.
    +
    + +
    +
    +
    + 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 +
    +
    +
    + + +
    +
    + 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.
    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 +
    +
    +
    + + +
    +
    + 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 +
    +
    +
    + + +
    +
    + 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/version-switcher.js b/docs/version-switcher.js new file mode 100644 index 0000000..bb9d1e3 --- /dev/null +++ b/docs/version-switcher.js @@ -0,0 +1,115 @@ +(function () { + 'use strict'; + + var BASE = '/git-parsec'; + var MANIFEST = BASE + '/versions.json'; + + function detectVersion() { + var match = location.pathname.match(/\/git-parsec\/v\/([^/]+)\//); + return match ? match[1] : 'latest'; + } + + function currentSubpath() { + var path = location.pathname; + // Strip base and optional version prefix + var rest = path.replace(/^\/git-parsec\/?/, '').replace(/^v\/[^/]+\/?/, ''); + // rest is now '' or 'guide/' or 'reference/' etc. + return rest; + } + + function versionUrl(version, subpath) { + if (version === 'latest') return BASE + '/' + subpath; + return BASE + '/v/' + version + '/' + subpath; + } + + function createDropdown(versions, current) { + var container = document.createElement('div'); + container.className = 'version-switcher'; + + var btn = document.createElement('button'); + btn.className = 'version-btn'; + btn.textContent = current === 'latest' ? 'latest' : 'v' + current; + btn.setAttribute('aria-label', 'Switch documentation version'); + + var arrow = document.createElement('span'); + arrow.className = 'version-arrow'; + arrow.textContent = ' \u25BE'; + btn.appendChild(arrow); + + var dropdown = document.createElement('div'); + dropdown.className = 'version-dropdown'; + + // "latest" option + var latestLink = document.createElement('a'); + latestLink.href = versionUrl('latest', currentSubpath()); + latestLink.textContent = 'latest (' + versions.latest + ')'; + if (current === 'latest') latestLink.className = 'active'; + dropdown.appendChild(latestLink); + + // Versioned options + versions.versions.forEach(function (v) { + var link = document.createElement('a'); + link.href = versionUrl(v.version, currentSubpath()); + link.textContent = 'v' + v.version; + if (current === v.version) link.className = 'active'; + dropdown.appendChild(link); + }); + + container.appendChild(btn); + container.appendChild(dropdown); + + btn.addEventListener('click', function (e) { + e.stopPropagation(); + dropdown.classList.toggle('open'); + }); + + document.addEventListener('click', function () { + dropdown.classList.remove('open'); + }); + + return container; + } + + function showBanner(current, latest) { + var banner = document.createElement('div'); + banner.className = 'version-banner'; + banner.innerHTML = + 'You are viewing docs for v' + current + '. ' + + 'View latest (' + latest + ') \u2192'; + document.body.insertBefore(banner, document.body.firstChild); + + // Push nav and body content below the banner + requestAnimationFrame(function () { + var h = banner.offsetHeight; + var nav = document.querySelector('nav'); + if (nav) nav.style.top = h + 'px'; + document.body.style.paddingTop = h + 'px'; + }); + } + + function init() { + fetch(MANIFEST) + .then(function (r) { return r.json(); }) + .then(function (data) { + var current = detectVersion(); + var navBrand = document.querySelector('.nav-inner .nav-brand'); + if (!navBrand) return; + + var switcher = createDropdown(data, current); + navBrand.parentNode.insertBefore(switcher, navBrand.nextSibling); + + if (current !== 'latest' && current !== data.latest) { + showBanner(current, data.latest); + } + }) + .catch(function () { + // Graceful degradation: no dropdown on fetch failure + }); + } + + if (document.readyState === 'loading') { + document.addEventListener('DOMContentLoaded', init); + } else { + init(); + } +})(); diff --git a/docs/versions.json b/docs/versions.json new file mode 100644 index 0000000..0c9cedf --- /dev/null +++ b/docs/versions.json @@ -0,0 +1,55 @@ +{ + "latest": "0.3.3", + "versions": [ + { + "version": "0.3.3", + "date": "2026-04-23", + "path": "/git-parsec/v/0.3.3/" + }, + { + "version": "0.3.2", + "date": "2026-04-21", + "path": "/git-parsec/v/0.3.2/" + }, + { + "version": "0.3.1", + "date": "2026-04-21", + "path": "/git-parsec/v/0.3.1/" + }, + { + "version": "0.3.0", + "date": "2026-04-16", + "path": "/git-parsec/v/0.3.0/" + }, + { + "version": "0.2.4", + "date": "2026-04-15", + "path": "/git-parsec/v/0.2.4/" + }, + { + "version": "0.2.3", + "date": "2026-04-15", + "path": "/git-parsec/v/0.2.3/" + }, + { + "version": "0.2.2", + "date": "2026-04-15", + "path": "/git-parsec/v/0.2.2/" + }, + { + "version": "0.2.1", + "date": "2026-04-15", + "path": "/git-parsec/v/0.2.1/" + }, + { + "version": "0.2.0", + "date": "2026-04-14", + "path": "/git-parsec/v/0.2.0/" + }, + { + "version": "0.1.1", + "date": "2026-04-14", + "path": "/git-parsec/v/0.1.1/" + } + ] +}