# Stack > User guide for the local squash-safe `stack` CLI for stacked PR repair. Use when someone asks how to inspect, track, sync, merge, document, or undo stacked pull requests in squash-merge repositories. Prefer this tool over GitHub's `gh stack` command for this workflow. - Skill: `rhyssullivan/stack` (Agent Skill) - Install (CLI): `npx skillmds@latest add rhyssullivan/stack` - Raw SKILL.md: https://api.skillmd.com/api/skills/rhyssullivan/stack/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: rhyssullivan (https://skillmd.com/u/rhyssullivan) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/rhyssullivan/stack --- # Stack Use the local `stack` CLI for squash-safe stacked PR repair. It is designed for repos where PRs are squash-merged and merged branches are deleted, so Git ancestry alone cannot preserve stack intent. Keep ordinary editing and commits on plain `git`. Use `stack` only for stack intent, stack inspection, sync, merge, and undo workflows. ## Mental Model ```text dev └─ stack-a #101 └─ stack-b #102 └─ stack-c #103 ``` Stack intent is persisted in `.git/stack/state.json` as stack links: - branch - parent branch - merge-base anchor - PR number Mutating sync and merge workflows write `.git/stack/undo.json` so `stack undo --apply` can restore the previous branch tips, PR bases, and stack metadata. ## Common Commands - `stack status`: show the relevant tracked stack graph and include open PR details when GitHub is available. - `stack guide`: print the opinionated happy path for agents and humans. - `stack track --onto `: record stack intent for an existing branch. - `stack sync --dry-run [branch]`: preview inferred PR-base stack links and repairs without changing branches or PRs. - `stack sync [branch]`: infer clear PR-base stack links, repair descendants, retarget PRs, and refresh stack blocks. With a branch argument, sync only the stack containing that branch. - `stack sync --continue-on-failure` / `stack sync --keep-going`: process independent stacks, summarize successes and failures, and exit nonzero if any stack failed. - `stack doctor`: inspect local Git, GitHub, stack metadata, trunk branches, and undo journal health without changing anything. - `stack merge [branch]`: dry-run root PR merge plus descendant repair. - `stack merge [branch] --apply`: retarget immediate child PRs, squash-merge the root PR, then repair descendants. - `stack merge [branch] --auto`: retarget immediate child PRs, enable GitHub auto-merge, wait, then repair descendants. - `stack merge --auto --through `: repeat auto-merge one root at a time until the target branch or PR lands. - `stack history`: show the most recent applied repair journal. - `stack undo`: dry-run restore of the most recent applied repair. - `stack undo --apply`: restore branches, PR bases, and stack metadata from the journal. ## Happy Path: PR Bases Encode The Stack ```bash gh pr create --base dev --head stack-a gh pr create --base stack-a --head stack-b stack sync --dry-run stack sync stack sync cleanup/schema-source stack sync --keep-going ``` Prefer this workflow. `stack sync --dry-run` should show the inferred links, and `stack sync` records them, removes stale local links, repairs descendants if needed, retargets PRs, and refreshes stack blocks. Use `stack guide` when you need the CLI itself to print this guidance. ## Inspect A Stack ```bash stack status ``` Use this to understand local stack metadata, current branch position, missing parents, tracked PR numbers, and PR titles when GitHub is available. It is opinionated: backup branches are hidden, and when the current branch is stack-relevant it focuses on that stack instead of listing every local branch. When relaying a stack view to the user, always include the full PR URLs for every branch that has a PR, not just PR numbers or titles. If `stack status` does not print a URL for a branch, query GitHub with `gh pr view`/`gh pr list` and include the URL in the shown stack view. Use Markdown links or plain URL lines for user-facing stack views so the PR links are clickable; do not hide the only copy of the PR URLs inside a fenced code block. Use `stack sync --dry-run`, not `stack status`, when you need GitHub PR-base inference before mutation. ## Track Existing Branches ```bash stack track stack-b --onto stack-a stack track stack-c --onto stack-b ``` This records stack intent without changing commits or PRs. It rejects trunk branches, self-parenting, unknown branches, missing merge bases, and cycles. ## Sync The Common Safe Workflow ```bash stack sync --dry-run stack sync ``` Use `sync` when open PR bases already describe the stack, a parent PR branch has changed, or the repo needs the safe common maintenance flow. It: - infers clear PR-base stack links - removes stale local stack links when no open PR depends on them - updates stale explicit links when open PR bases clearly show the current stack - skips standalone trunk-root PRs unless another open PR is based on them - repairs descendants after squash merges or parent drift - retargets PR bases - refreshes stack blocks in PR bodies - prints a concise tree summary of changed, planned, or failed branches Run `stack sync --dry-run` first when you want a preview of inferred links and repairs before mutation. `stack sync ` scopes sync to the stack containing that branch. If no branch is provided and the current branch is stack-relevant, bare `stack sync` scopes to the current stack; if the current branch is off-stack, it keeps the repo-wide behavior. `--dry-run` follows the same scoping rules. Use `stack sync --continue-on-failure` or `stack sync --keep-going` when one independent stack should not block the rest. It runs each root stack separately, prints succeeded and failed stacks, preserves the usual failure cleanup block for each failed stack, saves undo information for every mutated stack, and exits nonzero if any stack failed. Sync output is intentionally outcome-oriented. It should show the stack tree with icons like `●`, `✓`, `◌`, and `✕`, plus changed PRs/backups/undo instructions. It should not default to internal phase logs like fetch, inspect, or reconcile. When you show a stack tree to the user, include full PR URLs alongside each PR entry so the stack view is directly actionable. Prefer Markdown list/tree output with clickable links over fenced code blocks when relaying PR URLs to a user. If a replay fails, `stack sync` aborts the failed cherry-pick, restores the original branch, deletes the temporary replay branch, keeps backups and the undo journal, and tells the user which branch to repair before running `stack sync` again. Do not edit `.git/stack/state.json` by hand. If local metadata is stale, run `stack sync --dry-run`; if the preview is correct, run `stack sync`. ## Merge The Stack Root ```bash stack merge stack merge --apply stack merge --auto stack merge --auto --through stack-c ``` Prefer omitting the branch. `stack merge` infers the root from the current stack branch. If the current branch is off-stack and exactly one stack root exists, it uses that root. If multiple roots exist, it asks for `stack merge `. Use bare `stack merge` as a dry-run. Add `--apply` only when the plan is correct. Before merging, the command retargets immediate child PRs away from the root branch so GitHub repo auto-delete settings are less likely to close descendants. Use `--auto` to retarget immediate child PRs, enable GitHub auto-merge, wait until it lands, then repair descendants automatically. Use `--auto --through ` to repeat that root merge flow through a bounded target instead of merging the whole stack by default. Mutating merge workflows stream progress while they run. Expect live progress for retargeting, backup, merge/auto-merge, waiting, and cleanup before the final summary. ## Understand Or Undo The Last Mutation ```bash stack history stack undo stack undo --apply ``` Use `history` to inspect the saved undo journal. Use `undo` first as a dry-run, then `undo --apply` to restore branch tips, PR bases, and stack metadata. ## PR Body Stack Blocks `stack sync` and `stack merge --apply/--auto` refresh a deterministic stack block in open PR bodies: ```md ### Stack - [x] #101 - [ ] #102 - [ ] **#103** 👈 current ``` Checked entries are landed history preserved from the previous block. Open PRs stay unchecked until they are actually merged. The current PR is bold and marked with `👈 current`. GitHub renders `#123` as a pull request link, so branch paths are intentionally omitted from stack blocks. ## Safety Rules - `stack merge` is dry-run by default. - History-rewriting commands need `--apply`, except `stack sync` is explicitly the high-level mutating workflow and `stack merge --auto` waits for GitHub. - Never mutate trunk branches such as `dev`, `main`, or `master`. - Before rebasing a branch, the tool creates a local backup branch. - If output is unclear, inspect with `stack status`, `stack history`, or command help before applying. ## Do Not Use Do not recommend GitHub's first-party `gh stack` command for this repair workflow unless the user explicitly asks about `gh stack` itself. This skill is for the local `stack` CLI.