I might be missing something, but what I need is not "stacked PR" but a proper UI and interface to manage single commit:

- 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?

It's basically trying to bring the stacked diff workflow pioneered by Phabricator to GitHub.

The idea is that it allows you to better handle working on top of stuff that's not merged yet, and makes it easier for reviewers to review pieces of a larger stack of work independently.

It's really useful in larger corporate environments.

I've used stacked PRs when doing things like upgrading react-native in a monorepo. It required a massive amount of changes, and would be really hard to review as a single pull request. It has to be landed all at once, it's all or nothing. But being able to review it as smaller independent PRs is helpful.

Stacking PRs is also useful even when you don't need to merge the entire stack at once.

> stacked diff workflow pioneered by Phabricator

Ahem, pioneered by gerrit. But actually, I'm almost certain even that wasn't original art. I think gerrit just brought it to git.

https://www.gerritcodereview.com/about.html

To my knowledge, stacked diffs were first done in the Linux kernel as stacks of patches sent over email. From there they spread to Google and Facebook. (Source: I worked on Facebook's source control team from 2012-2018 and did a lot of work to enable stacked diffs there.)

Right, I was thinking from a web-based UI. The "pull request" term is from git (AFAIK), but git itself was built to accommodate the earlier concept of mailing patches around. (Source: I've been using version control since RCS/SCCS days and contributed here and there to git in its infancy. Also an early user/contributor to Gerrit.)

I'm not in a large corporate environment, but that also means we're not always a well oiled machine, and sometimes i am writing faster than the reviewer can review for a period of time -- and i really need the stacking then too.

What if main/master moves in between reviews?

Before this feature when you were doing it manually, it was a huge problem. One of the points of this feature, is it automates rebasing the whole stack.

Rebase the stack onto main.

Constantly rewriting git history with squashes, rebases, manual changes, and force pushes has always seemed like leaving a loaded gun pointed at your foot to me.

Especially since you get all of the same advantages with plain old stream on consciousness commits and merges using:

git merge --no-ff

git log --first-parent

git bisect --first-parent

I find rebases are only a footgun because the standard git cli is so bad at representing them - things like --force being easier to write than --force-with-lease, there being no way to easily absorb quick fixes into existing commits, interdiffs not really being possible without guesswork, rebases halting the entire workflow if they don't succeed, etc.

I've switched over pretty much entirely to Jujutsu (or JJ), which is an alternative VCS that can use Git as its backend so it's still compatible with Github and other git repos. My colleagues can all use git, and I can use JJ without them noticing or needing to care. JJ has merges, and I still use them when I merge a set of changes into the main branch once I've finished working on it, but it also makes rebases really simple and eliminates most of the footguns. So while I'm working on my branch, I can iteratively make a change, and then squash it into the commit I'm working on. If I refactor something, I can split the refactor out so it's in a separate commit and therefore easiest to review and test. When I get review feedback, I can squash it directly into the relevant commit rather than create a new commit for it, which means git blame tends to be much more accurate and helpful - the commit I see in the git blame readout is always the commit that did the change I'm interested in, rather than maybe the commit that was fixing some minor review details, or the commit that had some typo in it that was fixed in a later commit after review but that relationship isn't clear any more.

And while I'm working on a branch, I still have access to the full history of each commit and how it's changed over time, so I can easily make a change and then undo it, or see how a particular commit has evolved and maybe restore a previous state. It's just that the end result that gets merged doesn't contain all those details once they're no longer relevant.

Until someone merges master into their feature branch rather than rebasing it. (And then that branch later gets merged.)

This shouldn't be a problem if you stick to commits and merges. --first-parent will skip past commits, including merge commits, in merged branches.

I agree. PR merges for me are bisect points. That's when changes are introduced. Individual commits don't even always build.

And I don't rebase or squash because I need provenance in my job.

Workflows can vary, but what I like:

PR/MR is an "atomic" change (ideally the smallest change that can be landed separately - smallest makes it easier to review, bisect and revert)

Individual commits (or what "versions" are in Phabricator) are used for the evolution of the PR/MR to achieve that change.

But really I have 2 use cases for the commits:

1. the PR/MR is still too big, so I split it into individual commits (I know they will land together)

2. I keep the history of the evolution of the PR/MR in the commits ("changed foo to bar cause its a better approach")

You are describing gerrit.

https://www.gerritcodereview.com/

As someone who used phabricator and mercurial, using GitHub and git again feels like going back to the stone ages. Hopefully this and jujutsu can recreate stacked-diff flow of phabricator.

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).

I'm so glad git won the dvcs war. There was a solid decade where mercurial kept promoting itself as "faster than git*†‡" and every time I tried it wound up being dog slow (always) or broken (some of the time). Git is fugly but it's fast, reliable, and fugly, and I can work with that.

What is kind of funny here is that you're right locally. At the same time, the larger tech companies (Meta and Google, specifically) ended up building off of hg and not git because (at the time, especially) git cannot scale up to their use cases. So while the git CLI was super fast, and the hg CLI was slow, "performance" means more than just CLI speed.

I was never a fan of hg either, but now I can use jj, and get some of those benefits without actually using it directly.

Right, and I'm glad there are projects serving The Cathedral, but I live in The Bazaar so I'm glad The Bazaar won.

The efforts to sell priest robes to fruit vendors were a little silly, but I'm glad they didn't catch on because if they had caught on they no longer would have been silly.

Mercurial has a strictly superior API. The issue is solely that OG Mercurial was written in Python.

Git is super mid. It’s a shame that Git and GitHub are so dominant that VCS tooling has stagnated. It could be so so so much better!

Do not make claims about things you don't know shit about. Empiric evidence does not align with what you say. Idiomatic python is anywhere from 10 to 10000 times slower than idiomatic C. And a lot more resiurce hungry. If you were to optimize algorithms to the detail of git in Python, it would be unmaintainable.

> git was originally implemented as a handful of low level binaries stitched together with shell scripts.

Notice the "low level binaries" part?

> git was originally implemented as a handful of low level binaries stitched together with shell scripts.

A bunch of low level binaries stitched together with shell scripts is a lot faster than python, so not really sure what the point of this comparison is.

Python is an extremely versatile language, but if what you're doing is computing hashes and diffs, and generally doing entirely CPU-bound work, then it's objectively the wrong tool, unless you can delegate that to a fast, native kernel, in which case you're not actually using Python anymore.

I've rewritten a python tool in go, 1:1. And that turned something that was so slow that it was basically a toy, into something so fast that it became not just usable, but an essential asset.

Later on I also changed some of the algorithms to faster ones, but their impact was much lower than the language change.

They died because everyone knows that Python is infact very very slow. And that’s just totally fine for a vast number of glue operations.

It’s amusing you call Git fast. It’s notoriously problematic for large repos such that virtually every BigTech company has made a custom rewrite at some point or another!

Now that is interesting too, because git is very fast for all I have ever done. It may not scale to Google monorepo size, it would ve the wrong tool for that. But if you are talking Linux kernel source scale, it asolutely, is fast enough even for that.

For everything I've ever done, git was practically instant (except network IO of course). It's one of the fastest and most reliable tools I know. If it isn't fast for you, chances are you are on a slow Windows filesysrem additionally impeded by a Virus scanner.

The fact that Git has an extremely strong preference for storing full and complete history on every machine is a major annoyance! “Except for network IO” is not a valid excuse imho. Cloning the Linux kernel should take only a few seconds. It does not. This is slow and bad.

The mere fact that Git is unable to handle large binary files makes it an unusable tool for literally every project I have ever worked on in my entire career.

You barely have to try to have Python be noticeably slow. It's the only language I have ever used where I was even aware that a programming language could be slow.

Maybe forgejo has a shot?

Whatever your opinion on one tool or another might be - it does seem weird that the "market" has been captured by what you are saying is a lesser product.

IOW, what do you know that nobody else does?

Network effects and marketing can easily prevent better tools from winning.

I mean, in the fickle world that is TECH, I am struggling to believe that that's what's happened.

I personally went from .latest.latest.latest.use.this (naming versions as latest) to tortoise SVN (which I struggled with) to Git (which I also was one of those "walk around with a few memorised commands" people that don't actually know how to use it) to reading the fine manual (well 2.5 chapters of it) to being an evangalist.

I've tried Mercurial, and, frankly, it was just as black magic as Git was to me.

That's network effects.

But my counter is - I've not found Mercurial to be any better, not at all.

I have made multiple attempts to use it, but it's just not doing what I want.

And that's why I'm asking, is it any better, or not.

Mercurial has a more consistent CLI, a really good default GUI (TortoiseHg), and the ability to remember what branch a commit was made on. It's a much easier tool to teach to new developers.

Hmm, that feels a bit subjective - I'm not going to say X is easier than Y when I've just finished saying that I found both tools to have a lot of black magic happening.

But what I will point out, for better or worse, people are now looking at LLMs as Git masters, which is effectively making the LLM the UI which is going to have the effect of removing any assumed advantage of whichever is the "superior" UX

I do wish to make absolutely clear that I personally am not yet ready to completely delegate VCS work to LLMs - as I have pointed out I have what I like to think of as an advanced understanding of the tools, which affords me the luxury of not having an LLM shoot me in the foot, that is soley reserved as my own doing :)

Worse products win all the time. Inertia is almost impossible to overcome. VHS vs Betamax is a classic. iPod wasn’t the best mp3 player but being a better mp3 player wasn’t enough to claw market share.

Google and Meta don’t use Git and GitHub. Sapling and Phabricator much much better (when supported by a massive internal team)

What was the better mp3 player than the iPod?

That worse is better, and some people don't know better or care.

"better" in that sentence is very specific. Worse is also worse, and if you're one of the people for whom the "better" side of a solution doesn't apply, you're left with a mess that people celebrate.

Welcome to VHS and Betamax. the superior product does not always win the market.

I remember using darcs, but the repos I was using it with were so small as to performance really not mattering…

Git is not remotely fast for large projects.

This matches my experience 100%. I was about to write a similar comment before I see yours.

I just used it because I preferred the UX.

I continue to use gerrit explicitly because I cannot stand github reviews. Yes, in theory, make changes small. But if I'm doing larger work (like updating a vendored dep, that I still review), reviewing files is... not great... in github.

Most editors have some kind of way to review github PRs in your editor. VSCode has a great one. I use octo.nvim since I use neovim.

Can these tools e.g. do per-commit review? I mean, it's not the UI what's the problem (though it's not ideal), it's the whole idea of commenting the entire PR at once, partly ignoring the fact that the code in it changes with more commits pushed.

Phabricator and even Gerrit are significantly nicer.

I miss the Phabricator review UI so much.

Me too. And I'm speaking from using it at Rdio 15 years ago.

Nothing since (Gerrit, Reviewboard, Github, Critique) has measured up...

Finally!

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.

Huh interesting, my mental model is unable to see any difference between them.

I mean a branch is just jamming a flag into a commit with a polite note to move the flag along if you're working on it. You make a long trail, leave several flags and merge the whole thing back.

Of course leaving multiple waypoints only makes sense if merging the earlier parts makes any sense, and if the way you continue actually depends on the previous work.

If you can split it into several small changes made to a central branch it's a lot easier to merge things. Otherwise you risk making a new feature codependent on another even if there was no need to.

My only complaint off the bat is the reliance on the GH CLI, which I don't use either. But maybe by the time it's GA they'll have added UI support.

Stacked PRs can be created via the UI, API, or CLI.

You can also run a combination of these. For ex, use another tool like jj to develop locally, push up the branches, and use the gh CLI to batch create a stack of n PRs, without touching local state.

You can in fact do this from the web UI: https://github.github.com/gh-stack/guides/ui/#creating-a-sta...

damn, I missed it as well

presenting only cli commands in announcement wasn't a good choice

I must have missed that. Amazing! From a reviewer's POV, this will be so nice to at the very least remove diff noise for PRs built on top of another PR. I usually refrain from reviewing child PRs until the parent is merged and the child can be rebased, for the sole reason that the diffs are hard to review i.r.t. what came from where.

We're shipping a skill file with the CLI: https://skills.sh/github/gh-stack/gh-stack

Everyone will have their own way of structuring stacks, but I've found it great for the agent to plan a stack structure that mirrors the work to be done.

Why don't you use the CLI?

It seems partially exposed in the UI with that dropdown. There's an 'add' and 'unstack' button.

Probably relies on some internal metadata.

Does it fix the current UX issue with Squash & Merge?

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..

Conflicts spawn most likely because PR A was squashed, and once you squash Git doesn't know that PR B's ancestors commits are the same thing as the squashed commit on main.

No idea if this feature fixes this.

Edit: Hopefully `gh stack sync` does the rebasing correctly (rebase --onto with the PR A's last commit as base)

> Conflicts spawn most likely because PR A was squashed, and once you squash Git doesn't know that PR B's ancestors commits are the same thing as the squashed commit on main.

Yeah, and I kind of see how git gets confused because the squashed commits essentially disappear. But I don't know why the rebase can't be smart when it sees that file content between the eventual destination commit (the squash) is the same as the tip of the branch (instead of rebasing one commit at a time).

I agree that this is annoying and unintuitive. But I don’t see the simplest solution here, so:

All you need to do is pull main, then do an interactive rebase with the next branch in your stack with ‘git rebase -i main’, then drop all the commits that are from the branch you just merged.

If I'm following correctly, the conflicts arise from other commits made to main already - you've implicitly caught branch A up to main, and now you need catch branch B up to main, for a clean merge.

I don't see how there is any other way to achieve this cleanly, it's not a git thing, it's a logic thing right?

I've no issue with the logic of needing to update feature branches before merging, that's pretty bread and butter. The specific issue with this workflow is that the "update branch" button for PR B is grayed out because there are these hallucinated conflicts due to the new squash commit.

The update branch button works normally when I don't stack the PRs, so I don't know. It just feels like a half baked feature that GitHub automatically changes the PR target branch in this scenario but doesn't automatically do whatever it takes for a 'git merge origin/main' to work.

No, it's a Git thing arising from squash commits. There are workflows to make it work (I've linked the cleanest one I know that works without force pushing), but ultimately they're basically all hacks. https://www.patrickstevens.co.uk/posts/2023-10-18-squash-sta...

This is actually a reasonable workflow. Although requires some preparation. I’ll try it out!

Very cool that GitHub actually put stacks in the UI vs. GitLab's `glab stack`[0] (which looks just like the `gh stack` part of GitHub's thing).

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...>

> 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

As we have it designed currently, you would have to wait for CI to pass on the bottom two and then you can merge the bottom two in one step. The top of the stack would then get rebased, which will likely trigger another CI run.

Thanks for the callout - we'll update those docs to make it clear multiple PRs can be merged at once.

As a solo dev I rarely need stacked PRs, but the underlying problem, keeping PRs small and reviewable, is real even when you're your own reviewer. I've found that forcing myself to break work into small branches before I start (rather than retroactively splitting a giant branch) is the actual discipline. The tooling just makes it less painful when you don't.

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.

The tooling for that already exists, since a PR can consist of multiple Git commits and you can look at them separately in the UI. I don't know whether agents are any good at navigating that, but if not, they won't do any better with stacked PRs. Stacked PRs do create some new affordances for the review process, but that seems different from what you're looking for.

Looking at multiple commits is not a good workflow:

* It amounts to doing N code reviews at once rather than a few small reviews which can be done individually

* Github doesn't have any good UI to move between commits or to look at multiple at once. I have to find them, open them in separate tabs, etc.

* Github's overall UX for reviewing changes, quickly seeing a list of all comments, etc. is just awful. Gerrit is miles ahead. Microsoft's internal tooling was better 16 years ago.

* The more commits you have to read through at once the harder it is to keep track of the state of things.

Historically, hn etiquette is that it's fine to downvote for disagreement. This came from pg himself.

That said, while he hasn't posted here for a long time, this is still in the guidelines:

> Please don't post comments saying that HN is turning into Reddit. It's a semi-noob illusion, as old as the hills.

https://news.ycombinator.com/newsguidelines.html

Well, I stand corrected.

Small reviews allow moving faster for both the author and reviewer.

A chain of commits:

* Does not go out for review until the author has written all of them

* Cannot be submitted even in partial form until the reviewer has read all of them

Reviewing a chain of commits, as the reviewer I have to review them all. For 10 commits, this means setting aside an hour or whatever - something I will put off until there's a gap in my schedule.

For stacked commits, they can go out for review when each commit is ready. I can review a small CL very quick and will generally do so almost as soon as I get the notification. The author is immediately unblocked. Any feedback I have can be addressed immediately before the author keeps building on top of it.

Let's compare 2 approaches to delivering commits A, B, C.

Single PR with commits A, B, C: You must merge all commits or no commits. If you don't approve of all the commits, then none of the commits are approved.

3 stacked PRs: I approve PR A and B, and request changes on PR C. The developer of this stack is on vacation. We can incrementally deliver value by merging PRs A and B since those particular changes are blocking some other engineer's work, and we can wait until dev is back to fix PR C.

I have had a lot of success with Claude and jj, telling it to take the stack of work it's done and build me a new stack on top of trunk that's centered around ease of reviewing.

I once threatened Claude have to learn JJ after doing some crazy git rebase gymnastics. The problem is clearly that I don't know jj

It sometimes will hallucinate older CLI options, because jj has changed at various times, but it's pretty decent with it at this point. The harder part is that a lot of plugins hardcode git into them.

Maybe there’s a git trick I don’t know, but I’ve found making small branches off each other painful. I run into trouble when I update an earlier branch and all the dependent branches get out of sync with it. When those earlier branches get rebased into master it becomes a pain to update my in-progress branches as well

If I understood you correctly, you want to propagate changes in a branch to other branches that depend on it? Then --update-refs is for you[1]. That way, you only need to update the "latest" branch.

[1] https://andrewlock.net/working-with-stacked-branches-in-git-...

Stacking branches for any extended period of time is definitely a poor mixing of the concepts of branches and commits. If you have a set of changes you need to keep in order, but you also need to maintain multiple silos where you can cleanly allow the code to diverge, that divergence constitutes the failure of your efforts to keep the changes in order.

Until you can make it effortless, maintaining a substantial commit structure and constantly rebasing to add changes to the proper commit quickly turns into more effort than just waiting to the end and manually editing a monster diff into multiple sensible commits. But we take the challenge and tell ourselves we can do better if we're proactive.

This is what I understood as well, but it sounded like GP had success doing it; so I was curious if there was a trick I didn’t know about

I take from GP that they try to make their branches small, and keep the cycle of development->review->merging small, so that the problem stacked PRs seeks to solve doesn't materialize in the first place.

Stacked PRs in my experience has primarily been a request to merge in a particular order. If you're the only merger, as in GP's case, there's no need to request this of yourself.

If you visit the webpage it gives you integration instructions for agents

I really don't get the point of stacked PRs.

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.

The teams that I have worked with still apply the philosophy you’re describing, but they consider PRs to be the “commit”, i.e. the smallest thing that is sane to apoly individually.

Then the commits in the PR are not held to the standard of being acceptable to apply, and they are squashed together when the PR is merged.

This allows for a work flow in which up until the PR is merged the “history of developing the PR” is preserved but once it is merged, the entire PR is applied as one change to the main branch.

This workflow combined with stacked PRs allows developers to think in terms of the “smallest reviewable and applicable change” without needing to ensure that during development their intermediate states are safe to apply to main.

There’s a startup callled Graphite dedicated to stacked PRs. I have been using them for a while now I always wonder why github doesn’t implement something similar to this. I probaly will try and switch to GitHub to see if it works flawlessly

Yep, very happy with graphite at work.

GitLab's UI around MRs (PRs) is IMO miles better than what GH's been offering. Try creating a PR from branch A to main, and then rebasing A. GitLab handles this fine and can show you changes between the two revisions; GitHub is completely lost.

Maybe this is just a skill issue, but even with several attempts I just can't figure out why I would use stacked diffs/PRs. Though maybe that's because of the way I work?

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?

We use this feature extensively at $dayjob.

Imagine you have some task you are working on, and you wish to share your progress with people in bite sized chunks that they can review one at a time, but you also don’t want to wait for their reviews before you continue working on your task.

Using a stacked set of PRs you can continue producing new work, which depends on the work you’ve already completed, without waiting for the work you’ve already completed to be merged, and without putting all your work into one large PR.

I also branch out, and rebase. Also, keep updating and rebasing until merged. It’s tedious when PR take ages for approval, as I keep creating new branches on top of each other.

So, when I saw this announcement seemed interesting but don’t see the point of it yet.

I thrive on stacked PRs but this sure seems like a weird way to implement support for it. Just have each branch point to their parent in the chain, the end. Just native Git. I've been longing for better GitHub support for this but the CLI is not where I need that support: just the UI.

Rebasing after merging a base branch becomes a pain though, when you do this. IMO the CLI will be nice to automate the process of rebasing each branch on its parent.

Agreed. I do have tooling for a rebase + push flow, but it simply calls native git commands.

The CLI is completely optional, you can create stacked PRs purely via the UI.

Also the rationale for having a chain of branches pointing to each other was so the diff in a PR shows just the relevant changes from the specific branch, not the entire set of changes going back to the parent/trunk.

Curious how you're thinking about it?

Yes! Maybe that feature will come next.

I find this puzzling. It does not seem to allow to stack PRs on top of other people's PRs?

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.

Still feels like an alpha version right now. I'm sure they will add it later.

Graphite (which they seem to be inspired by) has frozen branches exactly for that use case:

https://graphite.com/blog/introducing-frozen-branches

This API leaves a comment, on the commit; not quite the same thing since in GH, several operations are tied to PRs and not to commits.

> a chain of small, focused pull requests that build on each other — each one independently reviewable.

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 canonical example here is a feature for a website that requires both backend and frontend work. The frontend depends on the backend, but the backend does not depend on the frontend. This means that the first commit is "independent" in the sense that it can land without the second, but the second is not, hence, a stack. The root of the stack can always be landed independently of what is on top of it, while the rest of the stack is dependent.

> If they’re not, why do you want to review them independently?

For this example, you may want review from both a backend engineer and a frontend engineer. That said, see this too though:

> 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.

If you do this in a PR, both get assigned to review the whole thing. Each person sees the code that they don't care about, because they're grouped together. Notifications go to all parties instead of the parties who care about each section. Both reviews can proceed independently in a stack, whereas they happen concurrently in a PR.

> If you approve change A and reject change B, then the feature is only half done.

It depends on what you mean by "the feature." Seen as one huge feature, then yes, it's true that it's not finished until both land. But seen as two separate but related features, it's fine to land the independent change before the dependent one: one feature is finished, but the other is not.

> If you do this in a PR, both get assigned to review the whole thing. Each person sees the code that they don't care about, because they're grouped together.

There are two separate issues you’re bringing up:

- Both groups being “assigned” the PR: fixable with code owners files. It’s more elegant than assigning diffs to people: groups of people have ownership over segments of the codebase and are responsible for approving changes to it. Solves the problem way better IMO.

- Both groups “seeing” all the changes: I already said GitHub lets you view single commits during PR review. That is already a solved problem.

And I didn’t even bring up the fact that you can just open a second PR for the frontend change that has the backend commit as the parent. Yes, the second PR is a superset of the first, but we’ve already established that (1) the second change isn’t orthogonal to the first one and can’t be merged independently anyway, and (2) reviewers can select only the commits that are in the frontend range. Generally you just mark the second PR as draft until the first one merges (or do what Gitlab does and mark it as “depends on” the first, which prevents it from merging until the first one is done.) The first PR being merged will instantly make the second PR’s diff collapse to just the unique changes once you rebase/merge in the latest main, too.

All of this is to explain how we can already do pretty much all of this. But in reality, it’s silly to have people review change B if change A hasn’t landed yet. A reviewer from A may completely throw the whole thing out and tell you to start over, or everything could otherwise go back to the drawing board. Making reviewers look at change B before this is done, is a potential for a huge waste of time. But then you may think reviewers from change B may opt to make the whole plan go back to the drawing board too, so what makes A so special? And the answer is it’s both a bad approach: just make the whole thing in one PR, and discuss it holistically. Code owners files are for assigning ownership, and breaking things into separate commits is to help people look at a subset of the changes. (Or just, like, have them click on the folder in the source tree they care about. This is not a problem that needs a whole new code review paradigm.)

> fixable with code owners files.

Code owners automatically assigns reviewers. You still end up in the state where many groups are assigned to the same PR, rather than having independent reviews.

> I already said GitHub lets you view single commits during PR review.

Yes, you can look at them, but your review is still in the context of the full PR.

> And I didn’t even bring up the fact that you can just open a second PR for the frontend change that has the backend commit as the parent.

The feature being discussed here is making this a first-class feature of the platform, much nicer to use. The second PR is "stacked" on top of the first.

> You still end up in the state where many groups are assigned to the same PR

> Yes, you can look at them, but your review is still in the context of the full PR.

Why is this a bad thing? I don’t get it. This has literally never been a problem once in my career. Is the issue that people can’t possibly scroll past another discussion? Or… I seriously am racking my brain trying to imagine why it’s a bad thing to have more than one stakeholder in a discussion.

I can think of a lot of reasons why doing the opposite, and siloing off discussions, leads to disaster. That is something I’ve encountered constantly in my career. We start out running an idea past group A, they iterate, then once we reach a consensus we bring the conclusion to group B and they have concerns. But oh, group A already agreed to this so you need to get on board. So group B feels railroaded. Then more meetings are called and we finally bring all the stakeholders together to discuss, and suddenly hey, group A and B both only had a partial view of the big picture, and why didn’t we all discuss this together in the first place? That’s happened more times in my career than I can count. The number of times group B is mad that they have to move their finger to scroll past what group A is talking about? Exactly zero.

If the layers of a stack have a disjoint set of reviewers things are viewed in separation which might lead to issues if there is no one reviewing the full picture.

That is why your forge will show that these two things are related to each other, and you may have the same person assigned to review both. It can show you this particular change in the context of the rest of them. But not every reviewer will always want to see all of the full context at all times.

Feature B depends on feature A, but you don't need B to understand A. Why wouldn't you create separate PRs?? It is faster to review and deploy.

Of course you would create separate PRs.

Why would you waste time faffing about building B on top of a fantasy version of A? Your time is probably better spent reviewing your colleague’s feature X so they can look at your A.

>If you reject change A and approve change B, nothing can merge

The feature is also half done in this case. The author can fix up the concerns the reviewer had in A and then both can be merged at the same time.

Meta has something similar to this using mercurial. It was awesome.

Let's say I have the canonical example of a stack from main via a backend-pr and a frontend-pr. When my stack is done I send it for review to one frontend reviewer and one backend reviewer.

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?

> If you have 10 commits for frontend and 10 for backend

In this model, you tend to want to amend, rather than add more commits. And so:

> they might start with 5 for backend, then 5 commits to each branch to iron out the interface and communication,

You don't add more commits here, you modify the commits in your stack instead.

> Now I need to rebase my frontend branch to sit on B6?

Yes, when you change something lower in the stack, the things on top need to be rebased. Because your forge understands that they're stacked, it can do this for you. And if there's conflicts, let you know that you need to resolve them, of course.

But in general, because you are amending the commits in the stack rather than adding to it, you don't need to move anything around.

> And wouldn't this separation normally be obvious e.g. by paths?

In the simplest case, sure. But for more complex work, that might not be the case. Furthermore, you said you have five commits for each; within those sets of five, this separation won't exist.

Super excited to give this a whirl - i've been messing with graphite's `gt` command for stacking and it's been relatively decent but I didn't love needing to bring in another tool/service/account when I only care about the stacking behaviour. Was a fun experiment but nice I can simplify back onto `gh` and `git`

Well, I have been waiting for this for YEARS.

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

Very interested ot check it out.

Seems to mainly be useful for monorepos as currently designed. Or, to replace a long-lived feature/refactor branch.

Whatbmakes you say that? Devs use stacked PRs in small and large repos today.

Their examples show combined backend and frontend changes on the same monorepo in different PRs.

As far as splitting work into different PRs that need coordinated merging, I've only ever encountered that when it's a long lived refactor / feature.

I think the only thing I miss from GitLab was being able to make merge requests depend on other merge requests, even across repositories. So I could make a backend repository MR depend on a library repository MR, and even enable auto-merge that’d fire when the backend MR was reviewed and the dependency was also merged.

Looks interesting, but it seems you need to know the final shape of the stack before you start creating Pull Requests. So it's useful if you create Pull Request A, then immediately start working on something that builds on top of A, create a Pull Request for that (while A is still a PR), then you can do A->B->C

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).

It looks like in the UI if you base a PR on another branch you can just check a box to make it a stack. So I don't think you have to know the full shape of the stack in advance unless you're using the cli.

I use jj to stack branches so i'll just be using the UI to do github pr stacks.

> Large pull requests are hard to review, slow to merge, and prone to conflicts. Reviewers lose context, feedback quality drops, and the whole team slows down.

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.

how is this different than viewing a PR one commit at a time?

I think it is conceptually the same but multiple PRs gives you the tools to manage the commits properly which GitHub is missing. You can't do the equivalent of `git rebase -i` in the GitHub UI to squash a fixup into a previous commit. Having each change in it's own PR enables that workflow using the existing GitHub UI.

Split into individual PRs, which works better for how a lot of companies do code review.

Stacked PRs track changes through updates and can be integrated progressively as they get validated.

They also allow reviewing commits individually, which is very frustrating to do without dedicated support (unless you devolve back to mailing list patch stacks).

Each commit can be merged independently as they're reviewed.

I don't think this is it. The main driver is that several operations in GH are scoped around a PR, not a commit. So the reason you need stacked PRs is that the layer of tooling above `git` is designed to work on logical groups of commits called a PR.

Right, the argument against: "how is this any different than splitting into single commits?" is simply: In general you want just one level above a commit which is the PR

One of the advertised features of this is being able to merge all the PRs at once. Which would also be the case for multiple commits in a single PR.

That's possible but not mandatory. In the current UX you can only approve/submit all or none.

It would be the same if commits were meaningful things. But typically they're not. The PR is the meaningful thing. A commit is something like "fix the lint error".

CI runs on each PR, you get a whole PR message and discussion/review interface for each PR. Each PR can itself consist of multiple commits. You can have stacked PRs from different authors (though from another comment it sounds like they may not have implemented that).

It's a big improvement (assuming they've done it right).

This is probably driven to be more usable with AI agents, but smaller prs can create more code as they need to enforce more backwards compability, this can also lead to more code or more maintenance work.

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

Like I’m not saying you should

My main question about this is does it keep review history properly after a rebase to restack PRs? Eg if I have reviewed PR for branch A and now its been rebased onto B by this tool and then more changes are made to A, does "review changes since" work in A's PR? This has been the main thing stopping me from wanting to use rebase to stack PRs and if they've fixed this somehow then I'm interested.

> How It Works

> 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.)

People have been building stacked PR workflows on top of GitHub for a while now. It's great to see that the message seems to have finally landed at GitHub, but what is actually new here in GitHub itself (i.e., not counting the gh CLI tool)?

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.

Freaking finally.

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.

This needs to be supported on `git` level first imho, not by a forge vendor.

What would this being supported by git mean to you?

One mistake I see across many organizations is that sometimes they overthink how much order should matter.

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.

I agree with you and further will add that modularity+atomicity are the ideal state for the vast majority of software applications… but in reality, most organizations can not afford to rewrite their software to the extent required to achieve this, if it wasn’t planned from the start.

Thank goodness. It was a pain to do this manually

Interesting to see how their CLI compares with GitLab's CLI interface for stacked diffs (the only support they offer at the moment): https://docs.gitlab.com/user/project/merge_requests/stacked_.... Most things are the same (up/down/top/bottom vs. next/prev/first/last, init vs. create), but both feel quite limiting. I've heard of other systems such as Gerrit that offer better native support, but have not tried out any for myself.

Wow i really need this, we had a refactor our monorepo (dotnet 8 -> 10 and angular 19 -> 21) which resulted in many small changes (like refactoring to signals, moving components to standalone) and we try to group changes into commits by what was fixed, but this had the downside of some commits beeing huge while others small, this would have helped us alot grouping commits together and having cleaner commit messages.

Interesting to see how this integrates with any release flows that use a lot of tags or feature flagging.

Very much looking forward to getting this on Renovate - we require squash-merge via Merge Queue (with no per-PR override available in GitHub, despite asking) and so when I've got multiple changes, it's a lot of wrangling and rebasing

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

Even though moments where I would reach for it are rare, this is a very welcome feature. In times when I could have used it, it was not difficult to emulate via more branches, consistent naming, referencing the PRs, etc. Not difficult, but definitely tedious, and always left me feeling less organized than I like to feel.

Just when I’ve gotten used to having 3 or more PRs in parallel with a local octopus working tree with jj. Maybe my colleagues will see the light at least.

great, I'll directly compare it to graphite.com - the main point really is the user interface in my opinion. Still a bit sceptical whether github can out-deliver here, but happy to be proven wrong!

Has anyone already tried that was a graphite user before?

“You cannot merge a PR in the middle of the stack before the PRs below it are merged.”

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.

What's difference between stacked PRs and merge trains in gitlab?

Merge trains are an integration method. In GitHub that’s called merge queues.

Stacked PRs are a development method, for managing changes which are separate but dependent on one another (stacked).

The two are orthogonal they can be used together or independently (or not at all).

Ahh so stacked diffs? https://docs.gitlab.com/user/project/merge_requests/stacked_...

Yes, except with a proper UI. Also while you could do this on GitHub before in the same way that that Gitlab feature works, it didn't work cross-repo so in practice it wasn't an option for most open source code.

I can't remember if Gitlab has the same limitations but I do remember trying to use Gitlab's stacked diffs and finding them to not work very well. Can't remember why tbh.

I'm surprised no-one has commented on the "sign up for the waitlist" button being a Microsoft Office form that wants your email address and GitHub handle. This feels like an elaborate phishing attack more than a serious feature announcement.

cherry picking is so fragile, this is at least a step in the right direction

This feels like a workaround for git's contradictory ergonomics.

At first I thought this was a user submitted project due to the subdomain of github.com but then realize the subdomain is also github. Is this an official channel for this sort of thing? Surprised this isn't on the official blog.

It's in private preview. Probably they'll put it in the main docs and such once it's open to everyone.

it's a GitHub Pages site in the @GitHub org from a repo called gh-stack (i.e. the repo is at https://github.com/github/gh-stack/).

There’s a special case where certain official orgs can continue to use github.com instead of github.io for their Pages domain, and that’s how you end up with:

https://github.github.com/gh-stack/

from the code:

Should Pages owned by this user be regarded as “Official GitHub properties”?

def github_owned_pages? GitHub.github_owned_pages.include?(login) end

# Orgs/users that are owned by GitHub and should be allowed to use # `github.com` URLs. # # Returns an Array of String User/Organization logins. ...

It's their 'GitHub' org GitHub Pages domain - it's just .com instead of .io (not to be confused with their gh.io link shortener)

Aside:

> 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)

Wondering how all of those startups that implement this for GitHub feel right now.

sherlocked

The biggest challenge for us are PRs that need to be coordinated across multiple repos. API + client for example. It doesn't sound like stacked PRs solve that problem, right? Description specifically states single repo.

They do not no. Afaik GitHub has little to nothing that is cross repository.

Can we merge from GitHub UI without rewriting the commit already?

Cool. Now let me do it across multiple repos. I often end up with 10 or 20 PRs across a half dozen repos that need to be merged in specific order.

For sure. If you are in a monorepo this solution works but if you have distinct microservice repositories it would help to coordinate pr #827 on repo-A and pr #1092 on repo-B are related and need to ship in a certain order.

Exact problem we've run into at work. We've ended up having to write external merge coordination in order to not break our dev deployments.

Their manager who suggested that everything be a microservice, but everything depends on each other.

Microservices, by the sound of the original comment

Microservices without a monorepo is hell

They've opted for critical damage.

How would that work? Commits in different repos aren't ordered relative to one another. I suppose you could have a "don't let me merge this PR until after this other PR is merged" feature, but you could do that with a GitHub Action; it doesn't really need dedicated backend or UI support.

> How would that work?

In practical terms: I manually write a list of PRs, and maintain that list in the description of each of the PRs. Massive duplication. But it clearly shows the merge train.

what happened to the old gerrit reviews, I loved its handling on incremental patchsets. github is primitive by comparison.

How does this work with a tool like jujutsu that provides native support for stacking and preferably don't have a separate tool mucking about with state?

Using a platform-specific tool feels like vendor lock-in. Given the recent trends, behavior, and activity of GitHub, it sure seems like this is the opposite of what the world should be going for generally.

Also if someone could help me understand: Are these so-called stacked commits not possible with multiple commits on a single branch? I prefer to write my commits as atomic, independent, related changes, on a single branch, with both Git and Mercurial. I am apparently missing something: why can't a better UI simply show a multi-change PR?

The CLI is not required and you can push up your bookmarks as branches and open stacked PRs via the UI. You can also use the gh CLI to just create the stacked PRs on github.com (essentially an API wrapper), without using it to manage local state.

It's a matter of taste, but I much prefer the workflow in the tool I hacked together for this, https://github.com/jlebar/git-pr-chain.

In the tool I wrote, you have a single branch with linear history. PRs in the chain are demarcated via commit messages. You then don't need any special rebase / sync commands -- you can use regular `git rebase -i` to reorder commits or edit a commit in the middle of a stack. Literally the only special command I need is "push this branch to github as multiple PRs".

Anyway I hope that alongside the branch-based you've built tool in `gh` that there will be an API that I can target.

Yup, there will be an API for stacks, just like there is one for regular PRs.

Any idea if/when this would be coming to GHE? I know the release cycle is way different but curious about your thoughts.

Yeah features need to be released as GA (general availability) before they can be included in GHES. I don't have a definitive timeline, but it will likely be end of this year or early next.

github.github.com? Not the first time github does something highly weird with their domains (like publishing docs from a subdomain of their public github pages service)

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.

in github's defense. This is a bit more nuanced, less objectively wrong domain posture issue. It will only matter if one security mechanism (subdomain control) fails.

The quoted microsoft examples are way worse. I see this with outbound email systems a lot, which is especially dangerous because email is a major surface of attack.

If only there were some way to logically break up large pull requests into smaller pieces... Some way of creating a checkpoint with a diff including your changes, and some kind of message explaining the context behind the change... some way to "commit" a change to the record of the repository...

Part of the idea behind stacked PRs is to keep your commits focused and with isolated changes that are meaningful.

A stacked PR allows you to construct a sequence of PRs in a way that allows you to iterate on and merge the isolated commits, but blocks merging items higher in the stack until the foundational changes are merged.

What can stacked PRs do that a series of well-organized commits in a single branch can't?

Stacked PRs tend to encourage a series of well-organized commits, because you review each commit separately, rather than together.

What they do that the single branch cannot is things like "have a disjoint set of reviewers where some people only review some commits", and that property is exactly why it encourages more well-organized commits, because you are reviewing them individually, rather than as a massive whole.

They also encourage amending existing commits rather than throwing fixup commits onto the end of a branch, which makes the original commit better rather than splitting it into multiple that aren't semantically useful on their own.

There are tools that use LLMs to do this.

I've done this manually by building a big feature branch and asking an LLM to extract out functionality for a portion of it.

For the former, it would seem to split based on frontend/backend, etc. rather than what semantically makes the most sense and for the latter it would include changes I don't want and forget some I do want. But I haven't tried this a lot.

So much effort has been spent beating git until it's just CVS with bells on.

The stacked diffs flow is much closer to the kernel flow for git than the traditional GitHub PR flow is.

Yeah, I feel like just being able to review a PR commit-by-commit with a nice interface would just suffice.

Not really. Without seeing the entire changeset for a PR, you'd have to mentally keep track of what the current state of everything is unless you're a commit minimalist and presquash.

How does that differ from this where you need to keep track of state and the whole change in the stack?

If we're speaking strictly code review, because you can actually make sense of the changeset for the child PR by not including its unmerged parent's changeset.

For me that would mean avoiding tiny commits, and I wouldn't want to do that

What might that be?

I feel like we already have enough abstractions in this space. Having any constraints at all in your tools is actually a good thing. PRs on top of ordinary git was a good step. This seems like one too many.

I honestly don't even get the PR addiction. Github has shaped devs workflows way too much. My best experience with git was when I realized that I can just have an blatantly simple workflow and explain it even to the junior-est dev in a few minutes. The reliance on github is somehow telling me that people stopped thinking about things they can actually control.

What a time to be alive. Stacked PRs are now a native feature of Github, even with first-class support for your ai agents. Vibeslop your whole Jira Backlog. Don't fear the merge anymore. Just make any feature branch a long-lived branch by stacking one upon another like bricks.

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.

Yeah, not sure what this solves that doing multiple PRs from one feature branch into another doesn't solve. But building behavior that into AI agents wouldn't be cool enough, I guess.