Sapling — A Scalable Source Control System by Meta

Introduction

Sapling is Meta's open-source source control client, extracted from their internal Mercurial-based system. It speaks the Git protocol, interoperates with GitHub, and offers ergonomic commands for stacking, splitting, and rebasing changes in large codebases.

What Sapling Does

• Provides a streamlined CLI (sl) that works with Git repositories and GitHub
• Displays a smartlog showing your stacked changes in a visual tree
• Supports interactive commit splitting and absorbing fixups into the correct ancestor
• Handles stacked pull requests with automatic chain management on GitHub
• Scales to monorepo-sized repositories through virtual filesystem and sparse profiles

Architecture Overview

Sapling implements its own working copy tracking and commit graph logic while delegating storage to a Git backend or Meta's custom Mononoke server. The client fetches only needed data (lazy tree and blob fetching), enabling operations on repos with millions of files. A segmented changelog structure allows efficient graph queries without loading full history.

Self-Hosting & Configuration

• Install via Homebrew on macOS or download .deb/.rpm packages for Linux
• Initialize in a Git repo with sl init --git or clone with sl clone
• Configure in ~/.sapling/sapling.conf for identity, editor, and merge tool
• Authenticate with GitHub via sl auth for pull request integration
• Use sl sparse to limit the working copy to relevant directories in large repos

Self-Hosting & Configuration

• Install via Homebrew on macOS or download .deb/.rpm packages for Linux
• Clone any Git repository with sl clone <url>
• Configure user identity and preferred editor in ~/.sapling/sapling.conf
• Authenticate to GitHub with sl pr commands for stacked PR workflows
• Supports sparse profiles to work in subdirectories of large monorepos

Key Features

• Smartlog shows only your changes in a compact visual tree rather than full linear history
• sl absorb automatically routes fixups into the correct ancestor commit in a stack
• sl split interactively breaks a large commit into smaller logical pieces
• Native GitHub PR support: create, update, and land stacked PR chains with sl pr submit
• Undo any operation with sl undo backed by a comprehensive operation log

Comparison with Similar Tools

• Git — generic and low-level; Sapling provides opinionated UX for stacked changes
• Jujutsu (jj) — similar modern VCS goals; Sapling focuses on stacked-diff workflows and GitHub PR chains
• Graphite — SaaS stacking tool on top of Git; Sapling is open-source and works offline
• ghstack — stacked PRs for Git; Sapling integrates stacking into the VCS itself
• Mercurial — Sapling's ancestor; Sapling adds Git compatibility and lazy fetching

FAQ

Q: Can I use Sapling with existing Git repositories? A: Yes. Sapling speaks the Git protocol and can clone, push, and fetch from any Git remote.

Q: Does it work with GitHub Actions and CI? A: Yes. Since it pushes standard Git refs, CI systems work without modification.

Q: What is a stacked diff workflow? A: You build a chain of dependent commits, each submitted as its own pull request, reviewed independently, and landed in order.

Q: Is Sapling production-ready? A: It powers Meta's internal development and is actively maintained for external Git/GitHub use.

Sources

• https://github.com/facebook/sapling
• https://sapling-scm.com/docs/introduction/