How to Stop Drowning in Huge Pull Requests with gh-stack

We've all been there: you're working on a complex feature that touches the API, backend logic, and frontend. The result is one giant PR with three thousand lines of code. The reviewer opens it, sees the sheer volume, sighs quietly, and closes the tab until better times. Or worse, skims through it in five minutes and writes "LGTM," missing critical bugs.

To spare our colleagues, we try to break changes into small pieces. But then dependency hell begins: branch feature-ui depends on feature-api, which depends on feature-db. Fix something at the bottom of this chain, and you have to manually rebase all the upper branches, keep track of base branches on GitHub, and hope nothing breaks.

It seems GitHub engineers got tired of this too and released an extension for their CLI — gh-stack. It automates working with so-called "stacked" pull requests.

What are stacked PRs and why do you need them

The idea is simple: instead of one massive change, you create a chain of small, logically connected PRs. Each subsequent one builds on the previous one.

Think of it this way:

1. PR #1: Add database schema (base: main).
2. PR #2: Implement API endpoints (base: branch from PR #1).
3. PR #3: Build the frontend interface (base: branch from PR #2).

Reviewers can check them individually. It's faster, easier, and more thorough. The problem is that Git and GitHub don't natively play well with this structure. If you update PR #1, you have to manually "pull up" changes to all the others. gh-stack handles this routine for you.

How it works in practice

The tool installs as an extension for the official GitHub CLI. If you already have gh, installation takes a couple of seconds:

gh extension install github/gh-stack

Creating your first stack

Let's say you're starting work on a new task. Instead of the usual git checkout -b, you initialize a stack:

gh stack init

Then you make commits as usual. When the first logical part is ready, instead of creating a branch manually, you just say:

gh stack add feature-api

This command creates a new branch on top of the current one and immediately switches you to it. You keep writing code. When the stack is ready, a single gh stack submit command sends everything to GitHub. The tool will create multiple pull requests and set their base branch correctly so each PR shows only the relevant diff, not a mess of all previous branches.

Navigation and edits

One of the handiest features in gh-stack is navigation. Forgot branch names? No problem.

• gh stack up — move up one level in the stack.
• gh stack down — go down to the base.
• gh stack tree — view the entire structure.

If a reviewer asks you to fix something in the very first PR, you just go down (gh stack bottom), make the changes, and run gh stack rebase. The magic is that the tool automatically propagates these changes through the entire stack upward, updating all intermediate branches. No more manually rebasing five branches in a row.

Managing via TUI

For those who prefer visual control, there's the gh stack modify command. It opens an interactive interface right in the terminal. There you can:

• Reorder branches.
• Fold multiple branches into one.
• Remove unnecessary parts of the stack.
• Rename layers.

This is much more intuitive than trying to do the same through git rebase -i and endless branch switching.

Synchronization and finishing work

When your PRs start merging into the main branch, it's time for gh stack sync. The command does several useful things at once: pulls changes from main, updates your local stack, and suggests deleting branches from already merged pull requests.

By the way, the utility can also work with AI agents. If you use automation for code generation, you can install the gh skill install github/gh-stack skill so the agent understands your branch structure and doesn't break the stack.

Any caveats?

The project is currently in Public Preview. This means that for some features to work (like the nice PR relationship display directly in the GitHub interface), the feature must be enabled for your repository. If it's not active yet, you can join the waitlist.

However, even without the server-side component, as a local helper for managing branch chains, gh-stack is already quite usable.

Who is this for

If you work on a large team with a strict code review process, this tool will save you hours. It eliminates the fear of branch "delamination" and lets you focus on code rather than Git administration.

If you're the only developer on a project and merge everything directly to main, you probably don't need this. But for everyone else — this is a great way to make your PRs human-friendly and easy to review.

It's worth trying just for the gh stack alias command. It creates a short alias gs, after which working with the stack becomes completely seamless. For example, gs push instead of long-winded constructs. A simple and effective tool from the makers of GitHub itself.