Graphite powers up your development workflow with stacked changes
August 7, 2022
Graphite is a "modern code review tool for fast-moving teams". It lets you stack incremental changes so you stay unblocked while your collegues reviews each diff independently. I've been using it for a couple of months at work. It's been a fantastic addition to my setup. Let me tell you more about it!
But first, let's get on the same page. A small pull request (PR) is easier to review than a large one. I think we can all agree. Typically it also generates more meaningful feedback. The same is true for PRs that try to solve one problem rather than many. That makes them hard to grasp and leads to code review procrastination. Usually it ends with someone approving the change just to get it off the table 🤞.
The standard GitHub workflow
# 1. Create a feature branch
git checkout -b feature-name
# 2. Change some code and make a commit
git commit --all --message "Add helper functions"
# 3. Make additional changes and another commit
git commit --all --message "Add new feature on page"
# 4. Open a PR and wait for feedback
git push --set-upstream origin feature-name
open https://github.com/repo/repo-name/compare/main...feature-name
# 5. Once approved, merge the PR
# 6. Repeat 1-5
This workflow is widely used across the software industry. It's simple but with a clear bottleneck: getting your code reviewed and approved. While waiting for your colleagues you don't have many options. If you don't wanna be that nagging guy, it's probably best to just sit back and wait.
In the meantime, you could keep making changes to the same branch. However, then you end up with a large PR. Which is bad. At least it makes me feel like I failed. That leaves the option to move on to a different task. But that's not ideal either, as context switching destroys developer productivity.
The best thing would be if you could stay in the same mindset keep going; branching off your current work. This pain has been felt especially in mega-companies like Meta and Google. In response, they've developed internal tools that unblock developers by allowing them review changes that stack on-top of one another.
The good news is that Graphite is bringing this workflow to the rest of us!
The Graphite workflow
# 1. Make some code changes
# 2. Create a branch with a commit
gt branch create feature/step-1 --all --message "Add step 1 of new feature X"
# 3. Open a PR
gt stack submit
# 4. Make some more changes
# 5. Create a new branch, stacked on the previous one
gt branch create feature/step-2 --all --message "Add step 2 of new feature X"
# 6. Open another PR
gt stack submit
# 7. Repeat 4-7
# 8. When approved, merge the whole stack in the web UI
To support this workflow, Graphite offers a command line tool and web dashboard. It's interoperable with GitHub and can be adopted by one engineer at a time. It scales from a "really fancy GitHub client" to a full git-workflow optimised for teams rather than open source and community-led projects; all based around the idea of stacked changes.
The CLI wraps git but takes the pain out of managing a stack of changes. You can update things and "restack" child-branches with a few simple commands. In fact, it does it so well that I don't find myself returning to my go-to graphical git-clients anymore.
The web UI works well as a replacement for the code review experience that GitHub normally offers, even if some features like suggesting changes are still missing. The dashboard gives an especially useful overview of all your teams work, something that Github notoriously has been lacking for years. The meme library is also a gem.
All-in-all, I highly recommend you check it out: graphite.dev
If this got you excited, you should listen to this episode of PodRocket where the co-founders discuss why they decided to build their business on GitHub among other things.
Did you know; Thomas Dohmke (current CEO of GitHub) and Tom Preston-Werner (GitHub founder) are Angel investors in Graphite.