facebook/sapling: a Git-compatible client built for repositories with millions of files

The problem Sapling targets: repository size, not workflow preference

Most source control clients make a promise about ergonomics. Sapling makes one about scale. The README states that the project aims for "extreme scalability to deal with repositories containing many millions of files and many millions of commits," and it spells out the goal in operational terms: all source control operations should scale with the number of files a developer is actually using, not with the size of the repository itself.

That distinction matters. A monorepo with millions of files is not slow because the client is badly written; it is slow because the client keeps touching the whole repository. Sapling's answer is to narrow the unit of work to the developer's working set. The README describes EdenFS, the virtual filesystem component, as populating working directory files on demand as they are accessed, which makes operations like checkout much faster "in exchange for a small performance hit when first accessing new files." That is a stated trade-off, not a free win.

The audience follows from that. If your repository is a few thousand files and a few thousand commits, the scalability machinery buys you nothing and the unfamiliar command surface costs you something. If your checkout takes minutes and your engineers work in two directories out of two hundred, the calculus flips.

How the pieces fit: sl client, Mononoke server, EdenFS virtual filesystem

The README divides Sapling into three components. The client is the `sl` command line plus a web interface, and the CLI code lives in the `eden/scm` subdirectory. Mononoke is described as a highly scalable distributed source control server. EdenFS is the virtual filesystem that manages Sapling checkouts.

The client's lineage is worth knowing before you judge its interface. The README says `sl` "was originally based on Mercurial, and shares various aspects of the UI and features of Mercurial." So the command names, the concept of a working copy with a commit graph, and the general feel of the tool come from Mercurial rather than Git, even though the project advertises Git compatibility.

Support status is uneven across the three components, and the README is direct about it. Mononoke and EdenFS are both described as used in production within Meta but "not yet supported for external usage," with OSS builds in GitHub Actions available "for unsupported experimentation." Only the client is presented as something an outside user is expected to run. Any evaluation that assumes you can stand up the server side the way you would stand up a Git host is reading past the README.

EdenFS design documentation is pointed to at `eden/fs/docs/Overview.md`, and Mononoke has its own README at `eden/mononoke/README.md`. Those are the places to go for mechanism detail; the top-level README stays at the level of intent.

Building the Sapling CLI from source with make oss

The README does not give a package-manager install line. It points readers to the Getting Started page at sapling-scm.com for cloning existing Git repositories, and for building it gives one instruction: run `make oss` in the `eden/scm` directory, then run the resulting `sl` executable.

The build has a stated dependency list: Python 3.8, Rust, CMake, and OpenSSL for the main CLI, plus Node and Yarn for the ISL web UI. Note that this is the dependency set for building, which is a heavier requirement than running a prebuilt client. If you only want to try Sapling, the Getting Started page is the documented entry point; the build path is what you follow when you want the binary yourself.

cd eden/scm
make oss

After that completes, the README says you run the `sl` executable that the build produces. There is a top-level `build.sh` and `build.bat` in the repository listing as well, and a `requirements_ubuntu.txt` file, but the README's own build instruction is the `make oss` step above.

Once you have a working client, the documented first move is to clone an existing Git repository through it, following the Getting Started page. The README also points Git users at a Git Cheat Sheet, which is the practical reference for translating habits: the CLI is Mercurial-derived, so commands you type from muscle memory may not be the commands `sl` expects.

The Interactive Smartlog is the part that is genuinely different from Git

Sapling ships an Interactive Smartlog, referred to as ISL, described in the README as a web UI "for seeing and interacting with your repository," along with a VS Code integrated version. This is the feature that has no direct equivalent in a stock Git install, and it is the one most likely to change how a developer works day to day.

A web UI over a commit graph is not a new idea, and the README does not claim it is. What it does claim is a particular position in the workflow: seeing and interacting, rather than seeing and then dropping to a terminal. Whether that holds up depends on how much of your work is history inspection versus command execution, and the README offers no performance figures or feature list to settle it.

Licensing splits here, and it is worth noticing early. The README states that the main project is under GPL-2.0, while the website and ISL are licensed under MIT, with the MIT text at `addons/LICENSE`. If your interest in Sapling is specifically the web UI, the licence you are dealing with is not the GPL one that covers the CLI.

Where Sapling is the wrong tool

The clearest limitation is support scope, and it is not a nuance. The README says Mononoke is "not yet supported publicly" and EdenFS is "not yet supported publicly." Both are buildable from OSS "for unsupported experimentation." A team that wants a self-hosted, Git-compatible server with a support expectation should stop reading here, because the project is not offering that.

The second limitation is the cost of the scalability design itself. EdenFS trades a small penalty on first access to a new file for faster checkout. In a repository where developers routinely touch most of the tree, that penalty is paid constantly and the benefit never arrives. The README frames on-demand population as beneficial "in large repositories where developers often only work with a small subset of the repository at a time," which is an accurate description of the case it helps and an implicit description of the case it does not.

The third is interface mismatch. Git compatibility is advertised, and the README points to a cheat sheet, but `sl` is Mercurial-derived. Tooling that shells out to `git` subcommands, scripts that parse Git output, and CI steps written against Git's exact behaviour are all places where compatibility has to be verified rather than assumed. The README does not document a rollback path for a checkout converted to Sapling, and it does not describe what happens to a repository mid-migration.

Sapling against Git and Mercurial in approach

The obvious comparison is Git, since Sapling advertises Git compatibility and the documented entry point is cloning existing Git repositories. The difference in approach is where the work happens. Git's model is a complete local object database plus a working tree that mirrors the checkout; operations scale with repository contents. Sapling's stated goal is the opposite: operations that scale with the files in use, with EdenFS populating the working directory on demand. In a small repository these converge and Git is the simpler choice. In a repository with millions of files they diverge sharply.

The second comparison is Mercurial, and here the relationship is lineage rather than rivalry. The README says `sl` was originally based on Mercurial and shares aspects of its UI and features. So if you already know Mercurial, the command surface will feel less foreign than Git's, and the migration question is mostly about whether the scale features are worth adopting a new client for. If you know neither, learning Mercurial-flavoured commands to work with Git repositories is an extra step with no obvious payoff at small scale.

Neither comparison is settled by the README, which gives no performance numbers. The honest framing is that Sapling's differentiation is architectural and only observable at sizes most projects do not have.

Maintenance, releases, and the cost of tracking a fast-moving client

The repository is not archived, and the last push was on 2026-09-21, one day before the date used for this assessment. Recent releases follow a dated scheme: 0.2.20260811-150444+8fb02b32 on 2026-08-11, 0.2.20260522-084851+1e764c94 on 2026-05-22, and 0.2.20260317-201835+0234c21f on 2026-03-18. The version strings embed a timestamp and a commit hash, which tells you what you are getting but does not tell you anything about API stability.

Upgrade cost is the real question, and the README does not answer it. There is no documented compatibility policy for the `sl` command surface across releases, and no migration notes in the README for repositories created by an older client. The version numbering (0.2.x) is pre-1.0, which is a fact about the release naming rather than a statement about readiness, but it does mean you should not expect the project to treat CLI behaviour as frozen. A team adopting Sapling should pin a specific dated release rather than track the newest one, and should read the release notes for each jump.

On licensing: the main project is GPL-2.0, the website and ISL are MIT, and the README explicitly warns that library subprojects such as minibytes "might have different licenses," directing readers to the `LICENSE` file and source headers in each library. That is a real obligation if you vendor or link against those libraries. It is not legal advice, and the README's own instruction is to check the per-library files.

Editorial conclusion

Adopt Sapling if your working set is a small fraction of a very large repository and you want a Git-compatible client with a different command surface. Do not adopt it expecting a supported self-hosted server: the README says Mononoke and EdenFS are not yet supported for external usage, and OSS builds are only for unsupported experimentation. Before committing, verify that the Git repository you care about clones and pushes cleanly through sl, and read the LICENSE file plus the source headers in each library subproject, since the README states that subprojects such as minibytes might carry different licenses.

Frequently asked questions

Official sources

1. facebook/sapling on GitHub
2. License: GPL-2.0
3. Project website
4. README
5. Releases