stack
/stack
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.
- Author
- kitlangton ↗
- Repository
- stack ↗
- Licence
- MIT
- Last repository change
- 27.08.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 2
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 27.08.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.
What it does and when to use it
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.
Original author 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.
How it works
- Setup
- Mental Model
- Happy Path
- Commands
- Stack Blocks
- Safety Rules
SKILL.md preview
---
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
```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, 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:
```bash
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:
```md
<!-- 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.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · kitlangton/stack | 100 | MIT |
| Insilico-org/plsi | 100 | MIT |
| ShepardVasNormandy/claude-skills | 100 | MIT |
| chaordic-io/discipline | 96 | MIT |
Database snapshot: 13.11.2026 · package version 5b17a85d4847 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 85github:stack
Publish and merge GitHub native stacked pull requests with the `gh stack` extension. Use when a branch is stacked on another branch rather than the default branch, when linking a chain of branches into a stack on GitHub, or when merging a PR that belongs to a stack. Load before… - 86stacked-branches
Build, submit, sync and merge a stack of dependent pull requests on GitHub (`gh stack`) or Gitea (`git-spice`/`gs`). Use when a follow-up needs its own pull request on top of the effort's, when the user asks for a stack, when a `warp` builds past a blocked step, or when a… - 100merging-pr-stack
Use when merging a stack of stacked PRs with jj. Triggered by phrases like "merge the PR stack", "merge the stacked PRs", "land these PRs", or "merge the stack into main". - 90stacked-prs
Design and operate GitHub stacked pull requests with the official github/gh-stack CLI. Use when deciding whether dependent work should be a stack, splitting work into valid layers, or creating, reviewing, updating, handing off, merging, cleaning up, or recovering a stack. Do not… - 90stacked-pull-requests
Use when working with a stack of GitHub pull requests — creating branches, keeping the stack in sync, or merging in order. Covers Git Town setup, PR targeting, rebasing, and landing the stack. - 100stacked-prs
Manages dependent branch stacks and stacked pull requests using safe Git topology rules. Triggers on: "create stacked PRs", "publish this stack", "sync my PR stack", "rebase this stack", "merge the stack", "retarget child PRs", "split this branch into stacked PRs", "validate…