Skip to content
Skills Library
Programming · Learning & explanation

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.

Repository
stack ↗
Licence
MIT
Last repository change
27.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
2
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 27.08.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 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

  1. Setup
  2. Mental Model
  3. Happy Path
  4. Commands
  5. Stack Blocks
  6. Safety Rules
Original SKILL.md headings · 117 lines, 734 words
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

RepositoryScoreLicence
This page · kitlangton/stack100MIT
Insilico-org/plsi100MIT
ShepardVasNormandy/claude-skills100MIT
chaordic-io/discipline96MIT

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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.