gh-stack: A Deep Dive into GitHub's Stacked PR Workflow Management Tool

What Are Stacked PRs?

In the day-to-day development of large software projects, a feature often needs to be broken down into multiple logically independent yet interdependent changes. In the traditional GitHub Pull Request workflow, developers typically cram all changes into one massive PR, or manually create multiple branches while carefully maintaining the dependencies between them. The former makes code reviewers miserable, while the latter easily descends into chaos during rebases.

Stacked PRs are a development paradigm designed to solve this exact pain point. The core idea is: break a large change into a series of small, logically coherent PRs, each building on top of the previous one, forming a "stacked" dependency chain. Reviewers can examine each layer individually, and authors can maintain the atomicity and readability of each change.

This concept actually originates from the tradition of "patch series" in version control systems. In Linux kernel development, developers submit an ordered series of patches through mailing lists, each patch logically independent but sequentially dependent—this is precisely the prototype of Stacked PRs. Git's design philosophy emphasizes atomic commits, but GitHub's PR model uses branches rather than individual commits as the unit of review, leading developers to pile up large numbers of commits on a single branch. Stacked PRs restore the possibility of fine-grained review by chaining multiple branches together.

The github/gh-stack project, which has recently gained traction on GitHub Trending, is an official command-line tool focused on stacked PR management. Written in Go, it has already earned 683 stars with 67 new stars in a single day, demonstrating strong community interest in this workflow.

Core Capabilities of gh-stack

Automated Stack Management

The greatest value of gh-stack lies in automating the complex dependency relationships between stacked PRs. When you maintain a stack chain containing five or six PRs in a project, any upstream change needs to propagate to all downstream branches. Doing this manually is both tedious and highly error-prone, while gh-stack can identify this dependency chain and batch-update all affected branches and PRs.

To understand the value of this capability, you need to understand the complexity of Git rebase operations in stacking scenarios. Git rebase is an operation that "replays" a series of commits onto a new base. In stacked branch management, when a lower-level branch changes (such as incorporating review feedback), all upper-level branches need to be sequentially rebased onto the new base. This process can produce cascading conflicts—where resolving one conflict at the bottom layer may cause new conflicts in each upper branch due to context changes. When manually managing five or six layers of stacking, a single rebase might require resolving ten or more conflicts repeatedly. This is precisely the critical value point where automation tools come in.

As a tool incubated by GitHub officially, gh-stack naturally integrates deeply with GitHub's PR system. It can read and manage relationships between branches, and automatically generates stack navigation information in each PR's description—letting reviewers see at a glance "where the current PR sits in the overall stack" and what it depends on before and after.

A Lightweight CLI Built with Go

Choosing Go as the implementation language allows gh-stack to compile into a single static binary, making cross-platform distribution simple with virtually no additional runtime dependencies for installation and execution. This is a huge advantage for command-line tools: developers can seamlessly embed it into their local development environment or CI pipelines without worrying about Python version conflicts or Node dependency bloat.

Since its inception, Go has been one of the preferred languages for command-line tool development. Its compiler supports cross-compilation, generating native binaries for Linux, macOS, Windows, and other platforms from a single codebase. Because Go uses static linking, the resulting executable doesn't depend on external shared libraries—users can run it immediately after downloading. GitHub's official CLI tool gh is itself written in Go, and gh-stack, as its extension plugin, can be installed with a single gh extension install command, seamlessly integrating into the developer's existing gh toolchain ecosystem.

Why the Stacked Workflow Deserves Attention

Smaller PRs, Faster Reviews

Research and engineering practice consistently show a clear inverse correlation between PR size and review quality. With a massive PR exceeding several hundred lines, reviewers often skim through or simply approve it, allowing hidden defects to slip into the main branch. The stacked workflow forces changes to be broken down, with each PR focused on a clear intent. Reviewers can provide more targeted feedback, and defect detection rates improve accordingly.

This conclusion is backed by solid data. A classic study from SmartBear (based on analysis of over 2,500 code reviews at Cisco) showed that review effectiveness peaks in the 200-400 line change range. Beyond 400 lines, defect detection rates drop sharply—reviewers experience "attention fatigue" and tend to approve quickly rather than review carefully. Google's engineering practice reports also indicate that the median change size in their internal code reviews is approximately 24 lines, far smaller than typical PR sizes in the open-source community. The stacked workflow is the engineering practice that translates these research findings into actionable processes.

No Blocking Your Development Rhythm

In the traditional single-branch model, if a PR hasn't been merged yet, subsequent work that depends on it can only wait. The stacked workflow allows developers to continue building downstream changes based on an upstream PR that's still under review, maintaining development continuity. This is especially valuable in fast-paced team collaboration.

Battle-Tested at Big Tech Companies

In fact, stacked PRs are not a new concept. Companies like Meta and Google have long employed similar "diff stack" workflows internally, and tools like Graphite and Sapling have built substantial followings in the open-source community. The emergence of gh-stack means that this efficient paradigm, repeatedly validated in the industry, is gradually being introduced into GitHub's native development experience.

Specifically, Meta (formerly Facebook) has long used Phabricator's Differential system internally, where developers break features into multiple "diffs" submitted for sequential review, each diff independently reviewable and mergeable. Google's internal Critique system similarly supports chains of CLs (changelists). In the open-source space, Graphite is currently the most mature commercialized Stacked PRs solution, offering a web dashboard and CLI tools; Meta's open-source Sapling version control system has built-in diff stack management capabilities; and community tools like git-branchless and spr each have their own focus areas. gh-stack's unique positioning is that it's a project under the official GitHub organization, hinting at platform-level integration potential.

Positioning and Outlook

Looking at the star growth curve, gh-stack's high short-term attention reflects developers' genuine need for more refined PR workflows. Compared to third-party SaaS solutions like Graphite, an officially endorsed, open-source tool delivered as a CLI naturally has an easier time winning over teams that value data sovereignty and local-first approaches.

Of course, as a project still in its early stages (only 32 forks), gh-stack's feature completeness, documentation richness, and ecosystem maturity all remain to be proven over time. For teams looking to try out the stacked workflow, it's recommended to pilot it on non-critical projects first, evaluate its compatibility with existing CI/CD processes, and then gradually expand adoption.

It's worth noting that stacked PRs pose new challenges for CI/CD pipelines. Traditional CI typically runs tests against the merge result of a single PR with the target branch, but in stacking scenarios, a PR's target branch might be another unmerged PR branch rather than main. This means CI systems need to correctly handle builds and tests with non-main base branches. Additionally, when a PR in the stack is merged, subsequent PRs' base branches need to automatically change to main, and CI needs to re-trigger to verify correctness after the merge. These scenarios all require corresponding CI configuration adaptations, and teams should fully evaluate this before adoption.

Overall, gh-stack represents another positive exploration by GitHub in improving developer workflow efficiency. If your team is suffering from massive PRs and branch dependency headaches, this tool deserves a place on your technology selection shortlist.

Key Takeaways