github/gh-stack

If your team reviews big changes as a chain of small PRs, gh stack is worth a look before you build your own scripts around Git branches. It is a GitHub CLI extension that formalizes the stack: branches are recorded locally, rebased in order, pushed, and turned into linked PRs whose base is always the branch beneath them.

The problem

A developer with a large change wants reviewers to see it in layers instead of one thousand-line diff. Today that means manually creating each branch from the previous one, remembering the order, setting every PR's base branch by hand, and rebasing the whole chain whenever the bottom layer changes. The bookkeeping, not the code, is the friction. gh stack takes over that bookkeeping: you add branches in order, submit once, and each layer becomes a PR targeted at the branch below, so reviewers see only their layer's diff.

What's different

Stack metadata is the interesting mechanism. It lives in a JSON catalog under Git's common directory (<common-dir>/gh-stack in a normal clone), not in the repository, so stacks are a local concept until submitted. Because the catalog is shared across linked worktrees, separate stacks or branches of one stack can live in different worktrees, and rebase and sync update the clean worktree that owns each affected branch. Dirty, busy, missing or changed owners stop the operation, and unrelated worktrees are left alone.

The trade-off is that the tool now owns a category of state Git does not. Recovery journals for rebase and modify operations sit alongside the catalog, while Git's own HEAD, index and rebase markers stay per worktree. Submitting also creates a "Stack" grouping on GitHub, so the workflow assumes reviewers and repository settings cooperate with that structure. The official extension installs unpinned and checks for a newer latest release in the background, caching results for 24 hours and appending an upgrade notice to stderr at most once a day; stdout and JSON output are unchanged. That background check is convenient if you want current releases, but it is one more moving part in non-interactive scripts.

Who should try it

Good fit: a developer or small team already splitting feature work into dependent branches, especially one using worktrees, who wants submitted PRs to encode the dependency correctly and wants rebases handled as a unit. The worktree-aware update behavior is the strongest reason to choose it over ad-hoc scripts. Poor fit: a solo developer whose changes fit one PR, or a team whose review process is not organized around chained branches, because the extra branch bookkeeping would buy nothing. Teams on other forges also get nothing here, since submission targets GitHub PRs.

There is a documented AI agent path: installing the gh-stack skill teaches a coding agent how stacked PRs and the CLI work (README). That is optional, not required to use the extension.

Requirements and limitations

You need the GitHub CLI gh v2.0+ and Git 2.36+, plus an authenticated GitHub repository (install instructions). The Git version floor matters because the worktree handling is central to how stacks are distributed and updated; older Git is not documented as supported. Local metadata lives in the common directory rather than the repo, so a fresh clone or a different machine does not carry the stack definition with it — expect to rebuild or re-adopt branches when you move.

Ongoing care: operations that change history (rebase, sync) depend on owning worktrees being clean and available, so a long-running stack needs discipline about which worktree holds which branch. Because stacks are not committed, teammates cannot see stack structure until PRs are submitted, and the PR grouping is created on GitHub's side.

HotRepo's take

HotRepo's records show 730 stars on 2026-08-01, 890 on 2026-08-02 and 1,724 on 2026-10-28, with three recorded daily-board days (project). Coverage is too sparse to judge whether that interest persists. Before adopting, check one concrete thing: whether your reviewers and repository merge settings actually work with the stacked-PR grouping the tool creates, since that model, not the CLI, determines whether the workflow pays off.