From 01d254c784622c1ea35f6afaf72ddd65e5897c3c Mon Sep 17 00:00:00 2001 From: dotta Date: Mon, 30 Mar 2026 01:08:53 -0500 Subject: [PATCH] docs: add missing worktree CLI commands to DEVELOPING.md Document worktree:list, worktree:merge-history, and worktree:cleanup commands that exist in the CLI but were missing from the worktree CLI reference section. Co-Authored-By: Paperclip --- doc/DEVELOPING.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.md index 7864b90edbc..7b4537eab45 100644 --- a/doc/DEVELOPING.md +++ b/doc/DEVELOPING.md @@ -256,6 +256,34 @@ pnpm paperclipai worktree env --json eval "$(pnpm paperclipai worktree env)" ``` +**`pnpm paperclipai worktree:list [options]`** — List git worktrees visible from this repo and whether they look like Paperclip worktrees. + +| Option | Description | +|---|---| +| `--json` | Print JSON instead of text output | + +**`pnpm paperclipai worktree:merge-history [source] [options]`** — Preview or import issue/comment history from another worktree into the current instance. + +| Option | Description | +|---|---| +| `[source]` | Optional source worktree path, directory name, or branch name (back-compat alias for `--from`) | +| `--from ` | Source worktree path, directory name, branch name, or `current` | +| `--to ` | Target worktree path, directory name, branch name, or `current` (defaults to current) | +| `--company ` | Shared company id or issue prefix inside the chosen source/target instances | +| `--scope ` | Comma-separated scopes to import: `issues`, `comments` (default: `issues,comments`) | +| `--apply` | Apply the import after previewing the plan | +| `--dry` | Preview only and do not import anything | +| `--yes` | Skip the interactive confirmation prompt when applying | + +**`pnpm paperclipai worktree:cleanup [options]`** — Safely remove a worktree, its branch, and its isolated instance data. + +| Option | Description | +|---|---| +| `` | Worktree name — auto-prefixed with `paperclip-` if needed | +| `--instance ` | Explicit instance id (if different from the worktree name) | +| `--home ` | Home root for worktree instances (default: `~/.paperclip-worktrees`) | +| `--force` | Bypass safety checks (uncommitted changes, unique commits) | + For project execution worktrees, Paperclip can also run a project-defined provision command after it creates or reuses an isolated git worktree. Configure this on the project's execution workspace policy (`workspaceStrategy.provisionCommand`). The command runs inside the derived worktree and receives `PAPERCLIP_WORKSPACE_*`, `PAPERCLIP_PROJECT_ID`, `PAPERCLIP_AGENT_ID`, and `PAPERCLIP_ISSUE_*` environment variables so each repo can bootstrap itself however it wants. ## Quick Health Checks