PATTERN Cited by 1 source

Usability-first VCS CLI

Design a VCS command-line interface so that usability is the first-class design concern, not an afterthought left over once scalability and feature completeness are handled.

Canonical instance: Sapling, which invests in usability as a parallel design axis to scalability (see concepts/vcs-usability).

Design rules (from Sapling)

• Every command does one thing. No command-is-multiple-modes overloading (git checkout, git reset, git stash as counterexamples).
• The default view is useful. Running the tool with no arguments produces something actionable — Sapling's sl invokes smartlog.
• Optional ceremony. Local branch names are optional. No staging area. Pre-commit-index is a choice the user can skip.
• Sensible defaults at every flag. The common case should need no flags.
• Recovery is first-class. undo / redo / uncommit / unamend / hide / unhide as named, documented commands — not "read the reflog and hope". See patterns/vcs-undo-tooling.
• Workflow-shaped commands. If stack-of-small-commits is a common workflow, provide sl fold, sl split, sl absorb, sl amend --to COMMIT instead of requiring interactive rebase incantations. See patterns/first-class-commit-stack-workflow.

Why it matters at engineering scale

Sapling's announcement post frames usability as a support-headcount multiplier:

"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

When users can self-serve recovery (find their old commit, undo an accidental rebase, unstash a stash they forgot about), the VCS support team doesn't have to field the ticket. For a tool used by "tens of thousands" of engineers, the support-volume-reduction payoff on usability work is substantial.

The contrast

Git is the canonical comparand: a tool that optimized for flexibility and a small, performant implementation — which bought the ecosystem it has — but whose surface-level UX has remained famously hostile to new users. The Git 2.23 split of git checkout into git switch + git restore is explicit recognition of this trade-off at the design-axis level.

Seen in

• sources/2024-09-10-meta-sapling-source-control-thats-user-friendly-and-scalable — canonical-first wiki instance. Meta invests in CLI usability as a parallel, first-class design axis to scalability.

Related

• systems/sapling-scm — the canonical instance.
• systems/sapling-smartlog — the specific UI primitive that anchors the usability-first stance.
• concepts/vcs-usability — the concept.
• patterns/vcs-undo-tooling — the recovery-UX sibling pattern.
• patterns/first-class-commit-stack-workflow — the workflow-UX sibling pattern.