Skip to content

CONCEPT Cited by 1 source

Commit stack

A commit stack is a sequence of small, incremental, individually- reviewable commits built on top of each other as a single feature's worth of work — not merged as a single large pull request, but reviewed commit-by-commit in order.

The workflow

Per the 2022-11-15 Sapling announcement post:

"At Meta, working with stacks of commits is a common part of our workflow. First, an engineer building a feature will send out the small first step of that feature as a commit for code review. While it's being reviewed, they will start on the next step as a second commit that will later be sent for code review as well. A full feature will consist of many of these small, incremental, individually reviewed commits on top of one another."

— Sapling announcement post

Meta's internal vocabulary for this: stacked diffs (from the Phabricator era). External ecosystems that embrace it: Gerrit, Sapling, various GitHub-adjacent tools (git- spice, git-stack, ghstack, etc.). GitHub's native pull-request UI is the canonical non-stack opposite.

Why it beats a big PR

  • Reviewer cognitive load: small commits are individually small; a 10-commit stack is easier to review than one 1000-line PR.
  • Blast radius: smaller commits, finer-grained bisection if something breaks.
  • Parallel work: the author starts commit N+1 while commit N is still in review.
  • Cleaner history: each commit is a reviewed, meaningful unit; not a "WIP + fix typo + address feedback" mess.

What makes it hard without VCS support

Editing a commit earlier in a stack in classical Git requires git rebase -i — "complex stateful commands" per the Sapling post — and every rebase reshuffles the subsequent commits, losing in-flight review state.

Sapling's answer: track mutation history for every commit. After sl amend on an earlier commit, Sapling knows how to algorithmically rebuild the stack (sl restack) no matter how many edits have happened. Commands like sl fold, sl split, sl absorb, sl amend --to COMMIT all lean on this tracking.

Canonical wiki pattern: patterns/first-class-commit-stack-workflow.

Review tooling

Stack-oriented code review is a separate concern from stack- aware version control. Sapling addresses it with [[systems/ reviewstack|ReviewStack]] — a demo UI for per-commit GitHub-PR review — flagged by Meta as a demonstration of "just how intuitive and powerful stacked commit review flows could be."

Seen in

Last updated · 319 distilled / 1,201 read