🦄 I'm writing this post much earlier than I usually would for all of my work friends. I've been using gh stack since the preview was made available in the GitHub UI a few weeks ago. It's a game changer when it comes to working across multiple branches — or it will be just as soon as they get the rest of the kinks worked out. Hopefully this helps explain exactly what the extension does and when you should definitely be using it. Don't miss the agent setup near the end! 🥞🦾
My boss told me to make my diffs smaller — consistently, and for long enough that I could recite the follow-up before it showed up in the comments: is this really required?
My answer was nearly always yes, and it got overridden often enough that substantial changes stopped making it out the door at all. The obvious problem, the one we all already know, is that large diffs are difficult to read. GitHub agrees in their docs:
Large pull requests are difficult to review and create bottlenecks, especially when AI helps you generate a high volume of code in a short time.
gh stack fixes the thing I'd abandoned trying forever ago: stacking branches so the diffs stay contained and still get released in a single merge.
The concept isn't new, and I've tried to maintain these by hand several times, which is not at all recommended. What's changed is that it's easy to work with — which matters as much on a repo my lead reads as it does on one nobody but an AI ever opens.
Think of each PR as a pancake, with the plate being main or whatever trunk branch you started from. Every pancake in the stack targets the layer below it, and GitHub is in charge of the syrup between every layer from the top one down to the plate.
Change a layer at the bottom and those changes have to propagate up through the syrupy goodness into the next one, which used to mean a rebase and a force-push, one at a time, in order, and made the whole thing useless for heavy dev work. Now gh stack manages all the syrup for you.
You need gh installed and authenticated, push access to origin, and a clean tree on your trunk branch. Stacked PRs are still in public preview, so expect the edges to move accordingly.
Branch names pass through exactly as given, slashes and all, so gh stack add refactor/foo gets you refactor/foo. Leave the name off and it stops to ask.
submit is the half that opens pull requests. sync pushes branches and refreshes PRs that already exist, but it has no create path, so a stack you've synced ten times still has nothing on GitHub until you submit.
Past two layers I stop remembering which branch I'm standing on, so this is most of what I actually type:
Arrows move through the layers, ↵ checks out whichever one you're sitting on, o opens its PR in the browser, and c and f expand that layer's commits and files without moving you anywhere — so I look at the whole stack, stop on the right pancake, and hit enter.
Editing something at the bottom after the stack exists is the thing gh stack actually buys you. Go to the pancake that owns the change, edit it, commit, and run one command:
If two layers touch the same lines, sync stops on the conflict and restores every branch to where it was, so nothing is left half-rebased.
Dropping a layer takes the stack apart and rebuilds it from the branches you're keeping, in order:
Those branches already exist, so init adopts them rather than creating anything — the commits, the branches, and their open PRs all survive it. The only thing thrown away is the chain between them.
One rule covers all of merging: whatever layer you're on merges everything from that layer down to the trunk, using whichever merge option you picked.