Facebook 开源的跨平台、高度可扩展、兼容 Git 的源码控制系统 – Sapling

Sapling SCM 是 Meta(Facebook) 开源的跨平台、高度可扩展、兼容 Git 的源码控制系统。Git 和 Mercurial 用户会发现许多基本概念都很熟悉，而且像了解你的存储库、处理提交以及从错误中恢复等工作流程都变得更加容易。

当与 Sapling 服务器和虚拟文件系统结合使用时，Sapling 可扩展到上千万个文件、commits 和分支的仓库。虽然在 Meta 内部它主要用于我们的大型 monorepo，但 Sapling CLI 也支持克隆 Git 存储库，并可由个人开发者用于与 GitHub 等合作。

Sapling 始于 10 年前，当时是为了在工程不断增长的情况下扩大 Meta 的 monorepo 规模，公开可用的源码控制系统都不能处理这种规模的存储库。我们没有放弃 monorepo 而牺牲工程速度，而是决定构建我们需要的源码控制系统。

在这个过程中，我们意识到，通过改善源码控制的体验，也有很大的机会提高开发人员的效率。通过投资新的用户体验，我们让新的工程师也能理解他们的仓库，并做一些以前只有高级用户才能做的操作。

此外，当我们开发 Sapling 的过程中，我们获得了内部抽象，这恰好使我们可以直接添加 Git 支持。版本控制的用户体验和规模可以与存储库中分离出来，这使得我们可以在内部使用我们的可扩展系统，并在需要时与 Git 仓库进行交互。我们希望这种模式也能为源码控制的发展提供一个范例，使之超越当前的行业现状。

安装

Linux

Ubuntu

可以直接前往 Release 页面 https://github.com/facebook/sapling/releases/latest 根据你的平台下载以 Ubuntu20.04.deb 或 Ubuntu22.04.deb 结尾的文件，然后可以使用 apt 命令进行安装，如下所示：

sudo apt install -y ~/Downloads/path-to-the-Ubuntu.deb

MacOS

首先，确保你的系统上安装了 Homebrew。

Apple silicon (arm64)

使用 curl 下载：

curl -L -O https://github.com/facebook/sapling/releases/download/0.1.20221118-210929-cfbb68aa/sapling_0.1.20221118-210929-cfbb68aa.arm64_monterey.bottle.tar.gz

然后使用 brew 命令一键安装：

brew install ./sapling_0.1.20221118-210929-cfbb68aa.arm64_monterey.bottle.tar.gz

Intel (x86_64)

使用 curl 下载：

curl -L -O https://github.com/facebook/sapling/releases/download/0.1.20221118-210929-cfbb68aa/sapling_0.1.20221118-210929-cfbb68aa.monterey.bottle.tar.gz

然后使用 brew 命令安装：

brew install ./sapling_0.1.20221118-210929-cfbb68aa.monterey.bottle.tar.gz

请注意，要克隆更大的存储库，需要更改打开的文件限制，我们建议现在就做，这样它以后就不会困扰你了：

echo "ulimit -n 1048576 1048576" >> ~/.bash_profile
echo "ulimit -n 1048576 1048576" >> ~/.zshrc

Windows

同样从 Release 页面 https://github.com/facebook/sapling/releases/latest 下载 sapling_windows ZIP 后，以管理员身份在 PowerShell 中运行以下命令（根据需要替换您下载的 .zip 文件的名称）：

PS> Expand-Archive ~/Downloads/sapling_windows_0.1.20221118-210929-cfbb68aa_amd64.zip 'C:Program Files'

这将创建 C:Program FilesSapling 路径，你也可以使用以下命令将其添加到 %PATH% 环境变量中：

PS> setx PATH "$env:PATH;C:Program FilesSapling" -m

需要注意的是必须安装以下工具才能利用 Sapling 的完整功能：

• 需要安装 Git for Windows 才能将 Sapling 与 Git 存储库一起使用
• 使用 sl web 需要安装 Node.js（v10 或更高版本）

注意，Sapling CLI sl.exe 的名称与 PowerShell 内置的 sl shell 冲突（sl 是 Set-Location 的别名，相当于 cd），如果要使用 sl 在 PowerShell 中运行 sl.exe，则必须重新分配别名。同样，你必须以管理员身份运行以下命令：

PS> Set-Alias -Name sl -Value 'C:Program FilesSaplingsl.exe' -Force -Option Constant,ReadOnly,AllScope
PS> sl --version
Sapling 20221108.091155.887dee39

快速使用

接下来我们讲使用 Sapling 来完成克隆、提交等操作。

设置身份

在命令行上安装 sl 后，首先需要配置你希望在创作提交时使用的身份：

$ sl config --user ui.username 'Alyssa P. Hacker <alyssa@example.com>'

如果还没有全局 Sapling 配置文件，上面的命令将创建它，该文件的位置因平台而异，但可以运行 sl configfile --user 命令来找到它。

• Linux：~/.config/sapling/sapling.conf（或 $XDG_CONFIG_HOME 而不是 ~/.config，如果已设置）
• macOS：~/Library/Preferences/sapling/sapling.conf
• Windows：%APPDATA%saplingsapling.conf

使用 GitHub 进行身份验证

Sapling 与 GitHub pull request 有许多自定义集成，为了与 GitHub 通信，Sapling 需要一个个人访问令牌来与 GitHub API 通信。我们建议安装 GitHub CLI (gh) 并使用它通过 GitHub 进行身份验证，而不是让 Sapling 管理你的令牌，如下所示：

gh auth login --git-protocol https

GitHub CLI 也是 GitHub 推荐的用于在 Git 中缓存 GitHub 凭据的解决方案，这样就不必在每次执行 sl push 时都输入密码或令牌了。

Clone 代码仓库

假设你使用 --git-protocol https 通过 gh 进行身份验证，请确保保持一致并为你的 GitHub 存储库使用 HTTPS URL（而不是 SSH URI）作为 sl clone 的参数：

$ sl clone https://github.com/facebook/sapling
$ cd sapling
$ sl
@  fafe18a24  23 minutes ago  ricglz  remote/main
│  migrate packer to new CLI framework
~

从 repo 内部，运行不带参数的 sl 会显示你的提交图，最开始只包含默认分支的 header，即 main。

创建第一个提交

Sapling 提供了熟悉的 add 和 commit/ci 命令来创建 commit 提交：

$ touch hello.txt
$ sl add .
$ echo 'Hello, World!' > hello.txt
$ sl commit -m 'my first commit with Sapling'
$ sl
  @  5a7b44286  25 seconds ago  alyssa
╭─╯  my first commit with Sapling
│
o  fafe18a24  27 minutes ago  remote/main
│
~

请注意，与 Git 不同，在创建 commit 之前无需显式声明新分支，Sapling 会自动跟踪 header，当运行 sl 时，header 很容易看到。与 Git 的另一个重要区别是，没有必须在其中暂存更改以供提交的索引。如果你使用 git 而不是 sl 运行上述命令，则 Git 提交将包含一个空的 hello.txt 文件，其中有非空的版本等待被暂存。

创建第一个 stack

出于说明目的，我们将继续创建更多提交：

$ echo foo > foo.txt ; sl add foo.txt ; sl ci -m 'adding foo'
$ echo bar > bar.txt ; sl add bar.txt ; sl ci -m 'adding bar'
$ echo baz > baz.txt ; sl add baz.txt ; sl ci -m 'adding baz'
$ sl
  @  4d9180fd8  1 second ago  alyssa
  │  adding baz
  │
  o  3cc43c835  7 seconds ago  alyssa
  │  adding bar
  │
  o  4f1243a8b  11 seconds ago  alyssa
╭─╯  adding foo
│
o  f22585511  Oct 06 at 17:40  remote/main
│
~

创建 stack 后，sl 使用 @ 指示你位于刚刚创建的提交 stack 的顶部，go 命令支持许多特殊别名，例如 sl go top 和 sl go bottom 分别导航到 stack 的顶部和底部。

你还可以使用 next 和 prev 命令在 stack 中上下移动，这两个命令都采用可选数量的 steps ，例如 sl next 2 会将两个提交向上移动。

内置 Web 界面

你可能还想试试 Sapling 内置的 GUI，它可以在浏览器中运行，可以运行 sl web 来从命令行启动它。

$ sl web
Listening on http://localhost:3011/?token=929fa2b3d75aa4330e0b7b0a10822ee0&cwd=%2FUsers%2Falyssa%2Fsrc%2Fsapling
Server logs will be written to /var/folders/5c/f3nk25tn7gd7nds59hy_nj7r0000gn/T/isl-server-logKktwaj/isl-server.log

Sapling 将在你的浏览器中自动打开 URL。

此外交互式 Smartlog 也可在我们的 VSCode 扩展中使用。

提交 PR

Sapling 支持多个工作流来与 GitHub pull requests 交互，最简单的解决方案是 sl pr 命令：

$ sl pr
...
$ sl
  @  4d9180fd8  6 minutes ago  alyssa  #178
  │  adding baz
  │
  o  3cc43c835  6 minutes ago  alyssa  #177
  │  adding bar
  │
  o  4f1243a8b  6 minutes ago  alyssa  #176
╭─╯  adding foo
│
o  f22585511  Oct 06 at 17:40  remote/main
│
~
$ sl pr
#178 is up-to-date
#177 is up-to-date
#176 is up-to-date
no pull requests to update

运行 sl pr 会为本地 stack 中的每个提交创建一个 PR，请注意，这会创建重叠的拉取请求，这意味着每个 PR 都使用关联的提交作为 PR 的头部，并将 remote/main 作为基础。在 GitHub 上审查重叠的拉取请求可能会造成混淆，因此我们还提供 ReviewStack 作为替代的代码审查工具，可以更好地处理这些类型的拉取请求。使用 pr 创建了一系列初始拉取请求后，你可能会对需要提交审查的提交进行本地更改。要将这些本地更改发布到 GitHub，只需再次运行 pr 以更新你现有的 PR。请注意，如果在 stack 中引入了未链接到 PR 的新提交，pr 也会为这些创建拉取请求。

浏览 PR

如果你已经使用 Sapling 为你的提交创建 PR，那么可以使用 sl ssl 将拉取请求状态包含在你的 Smartlog 中，请注意，sl ssl 不是子命令，而是 sl smartlog -T {ssl} 的内置别名：

$ sl ssl
  @  4d9180fd8  6 minutes ago  alyssa  #178 Unreviewed
  │  adding baz
  │
  o  3cc43c835  6 minutes ago  alyssa  #177 Approved
  │  adding bar
  │
  o  4f1243a8b  6 minutes ago  alyssa  #176 Closed
╭─╯  adding foo
│
o  f22585511  Oct 06 at 17:40  remote/main
│
~

除了在 github.com 上审查 PR 之外，你可能还想尝试 ReviewStack，这是我们针对 GitHub PR 的新颖用户界面，具有对堆叠更改的自定义支持。

要查看 ReviewStack 上的 GitHub 拉取请求，请使用原始 URL：https://github.com/facebook/react/pull/25506，并将 github.com 域替换为 reviewstack.dev：https://reviewstack.dev/facebook/react/pull/25506。在 ReviewStack 上，PR 的差异和时间线并排显示，而不是跨选项卡分开显示。

默认情况下，sl 显示的 Smartlog 中的 PR 链接到 github.com 上的相应页面，但你可以运行以下命令将 Smartlog 配置为链接到 reviewstack.dev：

$ sl config --user github.pull_request_domain reviewstack.dev

关于 Sapling 的更多信息可以查看官方文档 https://sapling-scm.com/ 以了解更多。

Git 仓库：https://github.com/facebook/sapling