GitHub Stacked PRs

It’s not just nice for monorepos. It makes both reviewing and working on long-running feature projects so much nicer. It encourages smaller PRs or diffs so that reviews are quick and easy to do in between builds (whereas long pull requests take a big chunk of time).

- merge some commits independently when partial work is ready.

- mark some commit as reviewed.

- UI to do interactive rebase and and squash and edit individual commits. (I can do that well from the command line, but not when using the GitHub interface, and somehow not everyone from my team is familiar with that)

- ability to attach a comment to a specific commit, or to the commit message.

- better way to visualize what change over time in each forced push/revision (diff of diff)

Git itself already has the concept of commit. Why put this "stacked PR" abstraction on top of it?

Or is there a difference I don't see?

Right now I manually do "stacked PRs" like this:

main <- PR A <- PR B (PR B's merge target branch is PR A) <- PR C, etc.

If PR B merges first, PR A can merge to main no problems. If PR A merges to main first, fixing PR B is a nightmare. The GitHub UI automatically changes the "target" branch of the PR to main, but instantly conflicts spawn from nowhere. Try to rebase it and you're going to be manually looking at every non-conflicting change that ever happened on that branch, for no apparent reason (yes, the reason is that PR A merging to main created a new merge commit at the head of main, and git just can't handle that or whatever).

So I don't really need a new UI for this, I need the tool to Just Work in a way that makes sense to anyone who wasn't Linus in 1998 when the gospel of rebase was delivered from On High to us unwashed Gentry through his fingertips..

I never understood the PR=branch model GitHub defaulted to. Stacked commits (ala Phabricator/Gerrit) always jived more with how my brain reasons about changes.

Glad to see this option. I guess I'll have to install their CLI thing now.

And it doesn't even rebase and merge correctly with fast-forward if there it's a clean set of commits! https://github.com/orgs/community/discussions/5524

Curious whether this changes anything for the AI-assisted workflow. Right now I let Claude Code work on a feature branch and it naturally produces one big diff. Stacked PRs could be interesting if agents learned to split their own work into logical chunks.

Just using git, you'd send a set of patches, which can be reviewed, tested and applied individually.

The PR workflow makes a patch series an undivisible set of changes, which must be reviewed, tested and applied in unison.

And stacked PRs tries to work around this issue, but the issue is how PRs are implemented in the first place.

What you really want is the ability to review individual commits/patches again, rather than work on entire bundles at once. Stacked PRs seems like a second layer of abstraction to work around issues with the first layer of abstractions.

One part that seems like it's going to feel a little weird is how merging is set up[1].

That is, if I merge the bottom of the stack, it'll rebase the others in the stack, which will probably trigger a CI test run. So, if I have three patches in the stack, and I want to merge the bottom two, I'd merge one, wait for tests to run on the other, merge the second vs. merge just those two in one step (though, without having used it, can't be sure about how this'd work in practice—maybe there's some way to work around this with restacking?)

[0]: <https://docs.gitlab.com/cli/stack/>

[1]: <https://github.github.com/gh-stack/guides/stacked-prs/#mergi...>

My biggest gripe with GitHub when working with stacks – and something that's not clarified in these docs – is whether fast-forward merges are possible. Its "Merge with rebase" button always rewrites the commit. They do mention that the stack needs to be rebased in order to merge it. My workaround has been `git merge --ff-only top-branch-of-stack` to merge the entire stack locally into main (or anything in between actually) and then push. GitHub neatly recognizes that each PR in the stack is now in main and marks them all as merged. If there are subsequent PRs that weren't merged it updates the base branch.

Having said that, it's great to see GitHub getting a proper UI for this. It's also great that it understands the intent that branch B that goes on top of branch A is a stack and thus CI runs against. I just hope that it's not mandatory to use their CLI in order to create stacks. They do cover this briefly in the FAQ[3], but it might be necessary to use `gh stack init --adopt branch-a branch-b branch-c`. On the other hand, if that removes the need to manually create the N PRs for my stack, that's nice.

[1]: https://git-scm.com/docs/git-rebase#Documentation/git-rebase...

[2]: https://github.com/tummychow/git-absorb

[3]: https://github.github.com/gh-stack/faq/#will-this-work-with-...

This will help some since you can more easily split PRs into units that make sense to squash at the end, but it still seems like not doing this on a per-commit basis is a disadvantage compared to Gerrit. With Gerrit I can use all the built-in Git rebase/squash/fixup tools to manage the commit stack and push everything in one go. I don't think there's a nearly as convenient a way to work with stacked branches in Git.

I notice a lot of examples just vaguely mention "oh, you can have others review your previous changes while you continue working", but this one doesnt make sense to me. Often times, the first set of commits doesn't even make it to the end result. I'm working on a feature using lexical, and at this point I had to rewrite the damn thing 3 times. The time of other devs is quite valuable and I can't imagine wasting it by having them review something that doesn't even make it in.

Now, I have been in situations where I have some ready changes and I need to build something on top. But it's not something just making another branch on top + rebase once the original is merged wouldn't solve.

Is this really worth so much hype?

I hope the Gitub CLI will include syncing[3] 'stacks' locally with upstream in a similar way.

[1]: https://www.git-town.com/stacked-changes.html

[2]: https://github.com/marketplace/actions/git-town-github-actio...

[3]: https://www.git-town.com/commands/sync.html

There is already an option to enable review comments on individual commits (see the API endpoint here: https://docs.github.com/en/rest/guides/working-with-comments...). Self-stacking PRs seem redundant.

> The gh stack CLI handles the local workflow […]

That's not "how it works", that's "how you['re supposed to] use it"… for "how it works" I would've expected something like "the git branches are named foo1 foo2 and foo3 and we recognize that lorem ipsum dolor sit amet…"

…which, if you click the overview link, it says "The CLI is not required to use Stacked PRs — the underlying git operations are standard. But it makes the workflow simpler, and you can create Stacked PRs from the CLI instead of the UI." … erm … how about actually explaining what the git ops are? A link, maybe? Is it just the PRs having common history?

…ffs…

(In case it's not obvious: I couldn't care less for using a GH specific CLI tool.)

One thing I keep thinking about in this same direction: even within a single layer of a stack, line-level diffs are still noisy. You rename a function and update x call sites, the diff shows y changed lines. A reviewer has to mentally reconstruct "oh this is just a rename" from raw red/green text.

Semantic diffing (showing which functions, classes, methods were added/modified/deleted/moved) would pair really well with stacks. Each layer of the stack becomes even easier to review when the diff tells you "modified function X, added function Y" instead of just showing changed lines.

I've been researching something in this direction, https://ataraxy-labs.github.io/sem/. It does entity-level diffs, blame, and impact analysis. Would love to see forges like GitHub move in this direction natively. Stacked PRs solve the too much at once problem. Semantic diffs solve the "what actually changed" problem. Together they'd make code review dramatically better.

OK, yeah, I’m with you.

> Stacked PRs solve this by breaking big changes into a chain of small, focused pull requests that build on each other — each one independently reviewable.

I don’t get this part. It seems like you are just wasting your own time building on top of unreviewed code in branches that have not been integrated in trunk. If your reviews are slow, fix that instead of running ahead faster than your team can actually work.

Here's something that would be useful: To break down an already big PR into multiples that make up a stack. So people can create a stack and add layers, but somehow re-order them (including adding something new at the first position).

Every time I try to do it manually, I wind up screwing everthing up.

Very interested ot check it out.

----

OK, I found this from official docs, so this feature is now quite useless to me:

> Can stacks be created across forks?

> No, Stacked PRs currently require all branches to be in the same repository. Cross-fork stacks are not supported.

I'm old enough to have worked with SVN and young enough to have taught engineers to avoid stacking PR in Git. All wisdom has been lost and will probably be rediscovered in another time by another generation.

Usually when you develop a "full stack" thing you continuously massage the backend into place while developing frontend stuff. If you have 10 commits for frontend and 10 for backend, they might start with 5 for backend, then 5 commits to each branch to iron out the interface and communication, and finally 5 commits on the frontend. Let's call these commits B1 through B10 and F1 through F10. Initially I have a backend branch based on main wuth commits B1 through B5.

Then I have a frontend branch based on B5 with commits F1 through F5. But now I need to adjust the backend again and I make change B6. Now I need to rebase my frontend branch to sit on B6? And then I make F6 there (And so on)?

And wouldn't this separation normally be obvious e.g. by paths? If I have a regular non-stack PR with 20 commits and 50 changed files, then 25 files will be in /backend and 25 in /frontend.

Sure, the reviewers who only review /frontend/* might now see half the commits being empty of relevant changes. But is that so bad?

Not for me, but I'm glad it fits other people's workflows. I just hope it doesn't encourage people to try make poorly reasoned changes!

I have never understood what this even means.

Either changes are orthogonal (and can be merged independently), or they’re not. If they are, they can each be their own PR. If they’re not, why do you want to review them independently?

If you reject change A and approve change B, nothing can merge, because B needs A to proceed. If you approve change A and reject change B, then the feature is only half done.

Is it just about people wanting to separate logical chunks of a change so they can avoid get distracted by other changes? Because that seems like something you can already do by just breaking a PR into commits and letting people look at one of those at a time.

I’ve tried my best to give stacked-diff proponents the benefit of the doubt but none of it actually makes sense to me.

The only annoying part is that I have to keep on merging the base branch to the feature branch constantly to keep it up-to date. If Github can provide a feature to do that automatically, then that would be perfect. Other than that, I don't see any advantage on this stacked PR approach they are proposing.

A PR is basically a cyberspatial concept saying "I, as a dog on the internet, am asking you to accept my patches" like a mailing list - this encourages trying to see the truth in the whole. A complete feature. More code in one go because you haven't pre-agreed the work.

Stacks are for the opposite social model. You have already agreed what you'll all be working on but you want to add a reviewer in a harmonious way. This gives you the option to make many small changes, and merge from the bottom

There seems to be a native stack navigation widget on the PR page, which is certainly a welcome addition.

The most important question though is whether they finally fixed or are going to fix the issues that prevent submitting stacked PRs from forks. I don't see any indication about that on the linked page.

Why are stacked commits useful? Multiple patches can be developed concurrently and efficiently, with each patch focused on a single concern, for a clean Git commit history and improved productivity. The tutorial [2] says:

> One common use of StGit is to “polish” a Git branch before publishing it to another public repository. The kinds of polish that StGit can help with include:

    Complete and correct commit messages.
    Each patch limited to one coherent topic.
    Each patch standing on its own: passing tests, etc.
    Considerate patch (commit) order

> As a concrete example, consider a situation where several Git commits have been made in a repository with commit messages such as:

    “Improve the snarfle cache”
    “Remove debug printout”
    “New snarfle cache test”
    “Oops, spell function name correctly”
    “Fix documentation error”
    “More snarfle cache”

Originally written in Python (2005, pre-GitHub) by Catalin Marinas, the current version is in Rust. StGit is free and open source [3]. It was inspired by Quilt [4], an earlier system credited to Andrew Morton and Andreas Grünbacher.

[1] https://stacked-git.github.io/ [2] https://stacked-git.github.io/guides/tutorial/#development-b... [3] https://github.com/stacked-git/stgit/ [4] https://en.wikipedia.org/wiki/Quilt_(software)

Is it?

Sure, your application has a dependency on that database, but it doesn't necessarily mean you can't deploy the application before having a database. If possible, make it acceptable for your application to stay in a crashloop until your database is online.

If this works as smoothly as it sounds, that'll significantly reduce the overhead!

All in all, pilegit works with Github, Gitlab, Phabricator, Gitea, and custom.

How about https://github.com/hokwangchoi/pilegit?

> This is a docs site that was made to share the spec and CLI for private preview customers that ended up getting picked up. This will move to GitHub docs once it’s in public preview.

(https://x.com/matthewisabel)

Honestly I don’t see the benefit of smaller prs, except driving vanity scores?

Like I’m not saying you should

Only downside is that Phabricator is not open source so viewing it in most things sucks. Hoping now I can get a much better experience

I’ve been trying to convince my boss to buy Graphite for this, seems like Github is getting their a* in gear after Cursor bought them.

If Jetbrains ever implements support for them in IntelliJ I will be in Heaven.

2. I'm not a huge fan of having to use a secondary tool that isn't formally a layer around git / like jj as opposed to github

Since I can still login, is there a web API (using CURL and some identifying session token I could retrieve from my login) I could use to actually do "something". For instance, be involved in the issues of some project?

(for me, that would be mostly valve stuff on linux based OSes)

Any pointers?

Huh? Some stacks need to land all at once and need to be reviewed (and merged) from the top down. It’s not uncommon, in my org at least, to review an entire stack and merge 3 into 2 and then 2 into 1 and then 1 into main. If 2 merges before 3, you just rebase 3 onto 1.

∙ `git checkout -b feature-branch-xyz`

∙ make a few commits, perhaps some fixups, rebase, whatever

∙ start tig, look at the history, decide at which points I want to break the branch into stacked PRs, and mark those points using shift-s (which calls my own `git gh-stack branch create $commit` and creates a specially named branch there)

∙ `git gh-stack sync` — collects all the specially named branches, builds a graph of how they're stacked on one another, pushes them, opens stacked PRs

GitHub has had some "support" for stacked PRs for a while, so merging the first one to main will automatically change the target branch of the second to main.

If I need to change anything, I can just `git rebase --interactive --update-refs`, amend commits, split commits, rearrange commits, and then running `git gh-stack sync` will update the PRs for me. If I split a commit in the middle and shift-s to mark it, it will open an extra PR and restack everything to update the order.

Furthermore, the "PR stack" doesn't actually need to be a stack (linear chain), it can be a tree. If I know that some commits are independent of the rest, I don't need to create a separate stack, I just create another local branch, mark PR-ready commits with shift-s, and `git gh-stack sync` will do the right thing. If I need to rebase the whole tree on top of current main, then `git rebase -i --rebase-merges --update-refs` does the job.

I guess what I'm saying is that as someone who's been using git since its inception, it feels much more natural to just do everything in git, and then have a single command that pushes my work to GitHub. And I think this might work even better with jujutsu — just point `git gh-stack sync` at the branches jj makes and it'll make a stack/tree of PRs out of them. :-)

https://github.com/liskin/dotfiles/blob/home/bin/git-gh-stac... if anyone's curious. It's just a few hundred lines of code. Building the graph is done by `git log --simplify-by-decoration`. Opening PRs is shelled out to `gh pr create`.

¹) I mean, I'd much rather they added a UI for reviewing PRs commit-by-commit, with the option to approve/request-changes on each, and the possibility to merge the first few approved ones while continuing work on the rest… But in a world of almost every $dayjob insisting on squash-merging, a UI for stacked PRs is a total game changer, positively.

I think they have a culture of circumventing 'official' channels and whoever is in charge of a thing is whoever publishes the thing.

I think it's a great way to train users to get phished by github impostors, if tomorrow we see an official download from official.github.com or even official-downloads.github.io, sure it's phishy, but it's also something that github does.

It's also 100% the kind of issues that, if it happens, the user will be blamed.

I would recommend github to stop doing this stuff and have a centralized domain to publish official communications and downloads from. Github.github.com? Come on, get serious.

TL;DR: DO NOT DOWNLOAD ANYTHING from this site, (especially not npm/npx/pnpm/bun/npjndsa) stuff. It's a Github Pages site, just on a subdomain that looks official, theoretically it might be no different from an attacker to obtain access to dksabdkshab.github.com than github.github.com. Even if it is official, would you trust the intern or whoever managed to get a subdomain to not get supply chained? github.github.com just think about it.