stack

name	stack
description	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.

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

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 <branch> --onto <parent>: 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 <branch-or-pr>: 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

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

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

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

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 <branch> 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

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

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 <branch-or-pr> 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

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:

<!-- stack:links:start -->

### Stack

- [x] #101
- [ ] #102
- [ ] **#103** 👈 current

<!-- stack:links:end -->

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.