Mastering Stacked Diffs and Git Workflow

If you have ever felt paralyzed by a massive feature branch that has fallen weeks behind main, you know the pain of the traditional GitHub Flow. There is a better way: Stacked Diffs.

What is a Stacked Diff?

Instead of one giant branch for a feature, you break your work into a chain (or stack) of small, dependent branches.

main
└─ feature-part-1 (API changes)
└─ feature-part-2 (UI components)
└─ feature-part-3 (Integration)

You submit a Pull Request for feature-part-1. While it is being reviewed, you continue working on feature-part-2 based on feature-part-1. You do not stop. You do not context switch.

Why Stack?

• Faster Reviews: Reviewers only look at small, logical chunks of code.
• Unblocked Development: You never have to wait for a review to continue coding.
• Easy Reverts: If Part 2 has a bug, you can revert just that part without killing the whole feature.

Tooling Matters

Managing stacks manually with standard Git commands can be painful (git rebase --interactive hell). Tools like Graphite (and increasingly, native Git features) make this workflow seamless.

At MatterAI, we use stacked diffs for everything. It allows our small team to ship with the velocity of a team 10x our size.

Best Practices

1. Keep stacks usually under 4-5 deep. Any deeper and managing dependencies becomes tricky.
2. Merge from the bottom up. Once the bottom PR is approved and merged, rebase the rest of the stack on top of main.
3. Communicate with reviewers. Let them know it is a stack so they understand the context of the changes.