Skip to content

PATTERN Cited by 1 source

VCS undo tooling

Treat VCS undo as a first-class subsystem, not a recovery procedure. Provide named, idempotent, discoverable commands for undoing every destructive operation, and an interactive scroller to find "the state of the repo N operations ago."

Canonical instance: Sapling's undo subsystem.

Design rules (from Sapling)

  • Named commands for common reversals. Sapling ships: sl undo, sl redo, sl uncommit, sl unamend. Each command has a specific inverse semantics — not a generic "try to figure it out."
  • Hide, don't delete. sl hide / sl unhide — "you can trivially and safely hide commits and bring them back to life." Commits are retained in the object store; the hidden-ness is tracked in mutation metadata.
  • Interactive time-travel. On Mac/Linux, sl undo -i opens an interactive scroller through old smartlog views — the user visually browses historical states until they find the one they want. Canonical UX primitive: let the user see past states, not just act on them.
  • No "reclone to fix". Per the post verbatim: "Never again should you have to delete your repository and clone again to get things working." The undo subsystem is explicitly sized to obviate reclone as a recovery step.

Substrate

The undo subsystem is made safe by mutation history tracking — Sapling records every mutation (amend, rebase, fold, split, hide) as a link between old and new commits, so undo has a graph to walk.

Git's equivalent is the reflog, which tracks ref movements but not commit-level mutation lineage — git reflog is a useful tool for advanced users but not a subsystem the way Sapling's undo is.

Why the investment pays off

Per Sapling's announcement post, the motivation is scaling the support function:

"The Sapling development team is small, and in order to support our tens of thousands of internal developers, we needed to make it as easy as possible to solve your own issues and get unblocked."

— Sapling announcement post

VCS support is expensive at scale — each ticket that ends in "let me reclone your repo" is engineering time lost. First-class undo tooling compresses the support surface so users self-serve recoverable mistakes.

patterns/usability-first-vcs-cli is the broader design stance; this pattern is its recovery-UX specialization. patterns/first-class-commit-stack-workflow is the workflow specialization that makes aggressive editing (and therefore frequent undoing) the default.

Seen in

Last updated · 319 distilled / 1,201 read