# 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: `somtougeh/stack` (Agent Skill) - Install (CLI): `npx skillmds@latest add somtougeh/stack` - Raw SKILL.md: https://api.skillmd.com/api/skills/somtougeh/stack/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: SomtoUgeh (https://skillmd.com/u/somtougeh) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/somtougeh/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. First verify `command -v stack` and read its `--help`/`guide`; this is a custom tool and a different executable named `stack` may be unrelated. If unavailable, say so and inspect Git/PR metadata read-only with `git` and `gh`; do not execute guessed repair commands or install an unverified namesake. The behavior below must match the discovered implementation before it is relied upon. Inspection requests do not authorize sync, merge, remote pushes, PR edits, or undo. A correct dry-run alone is not permission to apply it. Use the session's existing authorization for each concrete action; never run a workflow that pushes unless pushing was requested. Undo restores only the effects documented by the actual journal; it cannot unmerge a PR or reverse unrelated external effects. 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. 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. 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.