# Sapling — A Scalable Source Control System by Meta

> A Git-compatible source control client designed for large monorepos, featuring a smartlog for visualizing stacked changes, interactive split, and first-class support for stacked diffs workflows.

## Install

Save in your project root:

# Sapling — A Scalable Source Control System by Meta

## Quick Use
```bash
# Install on macOS
brew install sapling
# Clone a Git repo
sl clone https://github.com/user/repo.git
sl smartlog
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-1fe36c8f
Author: AI Open Source