stack

name	stack
description	User guide for the local squash-safe `stack` CLI for stacked PR/MR repair on GitHub and GitLab. Use when someone asks how to inspect, track, sync, merge, document, or undo stacked pull requests / merge 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 change repair. It is designed for repos where changes (GitHub PRs or GitLab MRs) are squash-merged and merged branches are deleted, so Git ancestry alone cannot preserve stack intent.

Setup

Works against GitHub (via gh) and GitLab (via glab). Install and authenticate the matching CLI before running stack.

• github.com and gitlab.com are detected automatically from origin.
• Enterprise host: git config stack.codeHost github|gitlab (or STACK_CODE_HOST env override).
• Custom trunks: git config stack.trunks dev,develop,main,master.
• Drop the attribution link from stack blocks: git config stack.blockLink false.

Keep ordinary editing and commits on plain git. Use stack only for stack intent, inspection, sync, merge, and undo.

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, merge-base anchor, change number). Mutating workflows write .git/stack/undo.json so stack undo --apply can restore the previous state. Do not edit these files by hand — run stack sync to preview, stack sync --apply to fix.

Happy Path

Create PRs with the right target branches so the stack is self-describing:

gh pr create --base dev --head stack-a
gh pr create --base stack-a --head stack-b
stack sync              # preview inferred links and repairs
stack sync --apply      # record links, repair, retarget, refresh stack blocks

That's the common loop. stack sync previews; stack sync --apply does the work. Repeat after any parent branch changes or a squash merge lands.

Sync also publishes locally ahead parent branches before repairing descendants. For parents that need no local repair, it checks the actual push destinations and only publishes fast-forward changes with explicit leases. Fetch and reconcile diverged or unknown remote tips before retrying. Undo restores remote-only publication without rolling back commits that already existed on the local parent, and refuses to overwrite unexpected remote changes.

Commands

• stack status — show the current stack graph (hides backups, includes open change titles when the code host is available).
• stack skill — print this skill for AI agent discovery.
• stack doctor — check Git, code-host access, stack metadata, trunks, and undo journal health without mutating anything.
• stack track <branch> --onto <parent> — manually record stack intent only when target branches don't already encode it.
• stack sync [branch] — preview inferred links and repairs (non-mutating). Scopes to the current stack if no branch is given.
• stack sync --apply [branch] — infer links, remove stale links, repair descendants, retarget changes, refresh stack blocks, show a tree summary.
• stack sync --apply --keep-going — process independent stacks separately, report successes and failures, exit nonzero if any failed.
• stack merge [branch] — dry-run root merge plus descendant repair. Infers the root from the current branch.
• stack merge --apply — retarget child changes, squash-merge the root, repair descendants.
• stack merge --auto — retarget children, enable code-host auto-merge, wait, then repair descendants.
• stack merge --auto --through <branch-or-change> — repeat auto-merge one root at a time until the target lands.
• stack history — show the most recent applied repair journal.
• stack undo — dry-run restore of the last applied mutation.
• stack undo --apply — restore branch tips, change targets, and stack metadata.

Stack Blocks

stack sync --apply and stack merge --apply/--auto refresh a deterministic block in each open change description:

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

### [Stack](https://github.com/kitlangton/stack)

1. #101
2. #102
3. **#103** 👈 current
<!-- stack:links:end -->

Earlier entries are landed history. The current change is bold with 👈 current. GitHub uses #123; GitLab uses !123 - Title.

Safety Rules

• Bare stack sync never mutates branches, changes, or stack metadata.
• stack merge is dry-run by default.
• Mutating commands need --apply (except merge --auto, which waits for the code host and repairs after the root lands).
• Never mutate trunk branches (dev, main, master, or any configured trunk).
• Before rebasing, the tool creates a local backup branch.
• Clean sibling worktrees can own branches being repaired or cleaned up; dirty sibling owners fail before mutation.
• If a replay fails, the tool aborts the cherry-pick, restores the original branch, keeps backups and the undo journal, and tells you which branch to repair before running stack sync --apply again.
• If output is unclear, inspect with stack status, stack history, or command help before applying.