Why use stacked changes?
Feel free to skip this section if you've worked with stacked changes before!
A stack is a sequence of dependent code changes, each building off of its parent. Stacks enable users 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.
For code authors:
Stacking changes can help you stay unblocked while you wait for code review, get higher-quality review comments, and land small changes faster.
For code reviewers:
Stacks let you give feedback on small, easy-to-comprehend changes, spend less time re-reviewing, and easily bisect and roll back if something goes wrong.
It's no surprise that many of the largest companies have built internal code review platforms which support and encourage engineers to work with stacked changes, such as Critique (Google) & Phabricator (Facebook, Dropbox, Uber, Pinterest, Quora, Twitter). In fact, we missed this workflow so much that we built the first version of Graphite for ourselves as an internal tool to allow us to work with stacked changes on top of GitHub.
In Graphite, a stack is represented by a directed, acyclic graph (DAG) of dependent git branches. We chose to compose stacks of branches rather than commits because, on GitHub, branches are the smallest discrete unit of CI and code review.
- Graphite extends Git's commits and branches with a third unit - stacks.
- A Graphite stack is a chain (DAG) of dependent branches.
- Graphite tracks stacks by recording parent relationships between branches through git refs.
- Whenever you move a parent branch forward by a commit or rebase it, Graphite uses its persisted metadata to remember the DAG of branches and automatically rebase them to keep your stack up-to-date.
Where is the metadata stored? In your repo in the form of refs, visible at
.git/refs/branch-metadata/. All information stays within git and can be synced to and from remote repositories.Plenty of folks smarter than us have written extensively bout the benefits of stacked changes - here are some of our favorite blog posts & papers on the topic:
Last modified 10mo ago