Back to Guides
Git Workflow

Mastering Stacked Diffs and Git Workflow

Stop wrestling with giant merge conflicts. Learn how top tech companies use stacked diffs to ship code faster and safer.

10 min read

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.