Stacking enables you to break up a large engineering task into a series of small, incremental code changes, each of which can be tested, reviewed, and merged independently while staying unblocked. A stack is a sequence of dependent code changes, each building off of their parent.
What other people are saying?
At work you’re often tasked with tackling multiple large projects and breaking them down into smaller chunks so that they’re reviewable. Often, newer engineers struggle mightily with this problem. "Stacked Diffs" are an important tool to manage this complexity.
1:42 PM - 30 NOV 2022
Sometimes when I code I end up feeling blocked or overwhelmed. Whenever that happens the solution is always the same: Break up the work into smaller PRs And when I do so I like using @withgraphite to keep my work in order.
7:27 AM - 28 OCT 2022
Stacked diffs are so good. I had a steep learning curve with huge PRs. Doing manual stack management is error prone and waste of time.
11:31 AM - 15 NOV 2022
For team product work, @withgraphite is the shiz. Let’s you stack up multiple small changes into dependent PRs. Does all your rebasing for you and keeps everything clean and encourages smaller diffs. It’s the future.
12:15 PM - 30 SEPT 2022
stacked diffs are so much better than pull requests, my friends. embrace the nature of git
10:02 PM - 19 OCT 2022
Stacked changes are just multiple dependent PRs. Stacking keeps authors unblocked while waiting for review, evokes higher-quality review comments, and lands small changes faster. Reviewers get bite-sized changes, spend less time re-reviewing, and have more granularity to bisect and rollback if something goes wrong.
People tend to avoid stacking because of the pain that comes with maintaining and merging a stack. Each time a base PR changes, there's a need to “restack” (propagate down-stack changes upward via recursive rebasing) - this is where tooling can help.
Many of the largest companies see the benefits of stacking code changes and have built internal code review platforms to help merge and restack, such as Critique (Google) & Phabricator (Facebook, Dropbox, Uber, Pinterest, Quora, Twitter).
Stacking and features branches both enable trunk-based development. The critical difference between stacking and feature branches is that stacked PRs don’t need to directly branch off of main; they can instead branch off of each other. While a feature branch can become bloated and hard to review, a stack can always stay light and modular. Feature branches need to be reviewed, pass CI, and merged as one large chunk. Stacks can be reviewed in small pieces, pass CI one branch at a time, and be merged in whenever ready.
If you have ever branched off of a branch and opened two, dependent PRs, you have already stacked. This workflow is natively supported by git, and just requires that you checkout and start working on the parent PR, rather than always developing against main.
Some developers prefer to write a large change first and then split it into a stack of smaller changes later. This can be helpful when you’re unsure of the final code structure upfront, but still want to submit a sequence of small, independently-reviewable changes.
Updating stacked branches is no different than updating traditional branches. The only difference is once you update a stacked branch, you’ll need to update the merge base of any dependent PRs too. If rebasing after every change is a daunting concept, have no fear; this is a place where tooling can automate.
When you’re ready for review, you can create a PR per branch in your stack. You can open your first PR the moment you stack on your second branch. Frequently submitting changes will ensure that the pull requests remain small and easily reviewable for your teammates.
Small PRs allow you to be more selective with requested reviewers, which reduces the bystander effect and notification spam. And since the pull requests are smaller, reviewers have to do less context switching. They know exactly what they’re looking at and can more easily give feedback.
If reviewers request changes, you can update your pull requests independently without needing to update the rest of your stack.
Once your changed are approved and passing CI, you’re ready to merge. Stacked changes always merge into trunk, meaning you always merge your stack bottoms up. Once a PR is merged, the base branch of the dependent PRs need to be updated to point to trunk - another opportunity for automated tooling to help.
How Graphite helps you stack
Much of the process above can be automated by tooling. For example, Graphite can help:
Graphite creates a visualization of your stack in the terminal, on our web dashboard, and as a GitHub comment, so that you always know where you are.
Graphite can merge many PRs in a stack at once using our merge-all functionality. That merges your PRs in order, for you.
When you update a PR in a stack, Graphite automatically rebases all up-stack (dependent) PRs for you; intelligently applying any rebase conflicts you resolve so that you only have to resolve them once.