feat: add Sapling (sl) VCS backend support (#291)

Author: zzl0

.github/workflows/ci.yml

@@ -48,6 +48,18 @@ jobs:
         with:
           tool: jj-cli
 
+      - name: Install Sapling
+        run: |
+          sudo apt-get install -y xz-utils
+          sudo mkdir -p /opt/sapling
+          SAPLING_URL="https://github.com/facebook/sapling/releases/download/0.2.20260317-201835%2B0234c21f/sapling-0.2.20260317-201835%2B0234c21f-linux-x64.tar.xz"
+          SAPLING_SHA256="2dca0b964a2f3e2e3ad3f4f01794dc7e829de4aedddb2798a7bae883ce6cd71f"
+          curl -fsSL "$SAPLING_URL" -o /tmp/sapling.tar.xz
+          echo "$SAPLING_SHA256  /tmp/sapling.tar.xz" | sha256sum --check
+          sudo tar -xJf /tmp/sapling.tar.xz -C /opt/sapling
+          sudo ln -s /opt/sapling/sl /usr/local/bin/sl
+          sl version
+
       - name: Install dependencies
         run: bun install --frozen-lockfile
 

.github/workflows/pr-ci.yml

@@ -93,6 +93,18 @@ jobs:
         with:
           tool: jj-cli
 
+      - name: Install Sapling
+        run: |
+          sudo apt-get install -y xz-utils
+          sudo mkdir -p /opt/sapling
+          SAPLING_URL="https://github.com/facebook/sapling/releases/download/0.2.20260317-201835%2B0234c21f/sapling-0.2.20260317-201835%2B0234c21f-linux-x64.tar.xz"
+          SAPLING_SHA256="2dca0b964a2f3e2e3ad3f4f01794dc7e829de4aedddb2798a7bae883ce6cd71f"
+          curl -fsSL "$SAPLING_URL" -o /tmp/sapling.tar.xz
+          echo "$SAPLING_SHA256  /tmp/sapling.tar.xz" | sha256sum --check
+          sudo tar -xJf /tmp/sapling.tar.xz -C /opt/sapling
+          sudo ln -s /opt/sapling/sl /usr/local/bin/sl
+          sl version
+
       - name: Install dependencies
         run: bun install --frozen-lockfile
 

CHANGELOG.md

@@ -10,6 +10,7 @@ All notable user-visible changes to Hunk are documented in this file.
 - Added Catppuccin Frappé and Macchiato as built-in themes, completing the four official Catppuccin flavors.
 - Added a Zenburn built-in theme (`theme = "zenburn"`), a warm low-contrast dark palette inspired by Jani Nurminen's original Zenburn. It also works as a custom-theme `base`.
 - Added a `--transparent-bg` flag and `transparent_background` config option for translucent terminal setups.
+- Added Sapling VCS backend support for `hunk diff` and `hunk show`.
 
 ### Changed
 

README.md

@@ -65,9 +65,9 @@ hunk show                      # review the latest commit
 hunk show HEAD~1               # review an earlier commit
 ```
 
-### Working with Jujutsu
+### Working with Jujutsu and Sapling
 
-Hunk auto-detects Jujutsu checkouts, so `hunk diff [revset]` and `hunk show [revset]` use jj revsets inside a jj workspace. To override VCS detection, set `vcs = "git"` or `vcs = "jj"` in [config](#config).
+Hunk auto-detects Jujutsu and Sapling checkouts, so `hunk diff [revset]` and `hunk show [revset]` use native revsets inside jj or Sapling workspaces. To override VCS detection, set `vcs = "git"` or `vcs = "jj"` or `vcs = "sl"` in [config](#config).
 
 ### Working with raw files and patches
 
@@ -121,7 +121,7 @@ Example:
 ```toml
 theme = "graphite"   # graphite, midnight, paper, ember, catppuccin-latte, catppuccin-frappe, catppuccin-macchiato, catppuccin-mocha, zenburn, custom
 mode = "auto"        # auto, split, stack
-vcs = "git"          # git, jj
+vcs = "git"          # git, jj, sl
 watch = false
 exclude_untracked = false
 line_numbers = true
@@ -130,7 +130,7 @@ agent_notes = false
 transparent_background = false
 ```
 
-`exclude_untracked` affects Git working-tree `hunk diff` sessions only.
+`exclude_untracked` affects Git/Sapling working-tree `hunk diff` sessions only.
 `transparent_background` can also be written as `transparentBackground`.
 
 Custom themes can inherit from any built-in base theme and override only the colors you care about:
@@ -188,6 +188,15 @@ pager = ["hunk", "pager"]
 diff-formatter = ":git"
 ```
 
+### Sapling pager integration
+
+To use Hunk as Sapling's pager, run `sl config -u` and update:
+
+```ini
+[pager]
+pager = hunk pager
+```
+
 ### OpenTUI component
 
 Hunk also publishes `HunkDiffView` and lower-level primitives from `hunkdiff/opentui` for embedding the same diff renderer in your own OpenTUI app.

src/core/git.ts

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import { join } from "node:path";
 import { HunkUserError } from "./errors";
+import { escapeUntrackedPatchPath } from "./patch/normalize";
 import type { VcsCommandInput, ShowCommandInput, StashShowCommandInput } from "./types";
 
 export type GitBackedInput = VcsCommandInput | ShowCommandInput | StashShowCommandInput;
@@ -456,15 +457,6 @@ export function listGitUntrackedFiles(
   );
 }
 
-/** Escape only the filename characters that break unified-diff header parsing. */
-function escapeUntrackedPatchPath(path: string) {
-  return path
-    .replaceAll("\\", "\\\\")
-    .replaceAll("\t", "\\t")
-    .replaceAll("\n", "\\n")
-    .replaceAll("\r", "\\r");
-}
-
 /** Rewrite Git's quoted untracked-file headers into parser-friendly paths. */
 export function normalizeUntrackedPatchHeaders(patchText: string, filePath: string) {
   const safePath = escapeUntrackedPatchPath(filePath);

src/core/loaders.test.ts

@@ -10,6 +10,8 @@ const tempDirs: string[] = [];
 
 // Jujutsu subprocess setup can exceed Bun's default 5s test timeout on Windows CI.
 const JjLoaderIntegrationTestTimeoutMs = 20_000;
+// Sapling subprocess setup can exceed Bun's default 5s test timeout on slower machines.
+const SlLoaderIntegrationTestTimeoutMs = 20_000;
 
 function cleanupTempDirs() {
   while (tempDirs.length > 0) {
@@ -76,6 +78,22 @@ function jj(cwd: string, ...cmd: string[]) {
   return Buffer.from(proc.stdout).toString("utf8");
 }
 
+function sl(cwd: string, ...cmd: string[]) {
+  const proc = Bun.spawnSync(["sl", "--noninteractive", "--color", "never", ...cmd], {
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+    stdin: "ignore",
+  });
+
+  if (proc.exitCode !== 0) {
+    const stderr = Buffer.from(proc.stderr).toString("utf8");
+    throw new Error(stderr.trim() || `sl ${cmd.join(" ")} failed`);
+  }
+
+  return Buffer.from(proc.stdout).toString("utf8");
+}
+
 function createTempRepo(prefix: string) {
   const dir = createTempDir(prefix);
 
@@ -95,8 +113,19 @@ function createTempJjRepo(prefix: string) {
   return dir;
 }
 
+function createTempSlRepo(prefix: string) {
+  const dir = createTempDir(prefix);
+
+  sl(dir, "init", "--git");
+  sl(dir, "config", "--local", "ui.username", "Test User <test@example.com>");
+
+  return dir;
+}
+
 // Keep jj-backed loader coverage opt-in on machines that have the external CLI installed.
 const jjTest = Bun.which("jj") ? test : test.skip;
+// Keep sl-backed loader coverage opt-in on machines that have the external CLI installed.
+const slTest = Bun.which("sl") ? test : test.skip;
 
 async function runWithHome<T>(home: string, task: () => Promise<T>) {
   const previousHome = process.env.HOME;
@@ -317,6 +346,30 @@ describe("loadAppBootstrap", () => {
     expect(bootstrap.changeset.files[1]?.patch).toContain("new file mode");
   });
 
+  slTest(
+    "includes Sapling unknown files in working copy reviews",
+    async () => {
+      const dir = createTempSlRepo("hunk-sl-untracked-");
+
+      writeFileSync(join(dir, "tracked.ts"), "export const value = 1;\n");
+      sl(dir, "add", "tracked.ts");
+      sl(dir, "commit", "-m", "initial");
+
+      writeFileSync(join(dir, "new-file.ts"), "export const added = true;\n");
+
+      const bootstrap = await loadFromRepo(dir, {
+        kind: "vcs",
+        staged: false,
+        options: { mode: "auto", vcs: "sl" },
+      });
+
+      const file = bootstrap.changeset.files[0];
+      expect(bootstrap.changeset.files.map((entry) => entry.path)).toEqual(["new-file.ts"]);
+      expect(file?.isUntracked).toBe(true);
+    },
+    SlLoaderIntegrationTestTimeoutMs,
+  );
+
   test("keeps generated large tracked diffs as skipped placeholders", async () => {
     const dir = createTempRepo("hunk-git-large-tracked-");
 

src/core/loaders.ts

@@ -18,7 +18,7 @@ import {
 import { createFileSourceFetcher, type FileSourceSpec } from "./fileSource";
 import { normalizeUntrackedPatchHeaders, runGitUntrackedFileDiffText } from "./git";
 import { splitPatchIntoFileChunks, findPatchChunk } from "./patch/chunks";
-import { normalizePatchText } from "./patch/normalize";
+import { escapeUntrackedPatchPath, normalizePatchText } from "./patch/normalize";
 import { createUnsupportedVcsOperationError, getVcsAdapter, operationFromInput } from "./vcs";
 import type {
   AppBootstrap,
@@ -182,6 +182,7 @@ function buildUntrackedDiffFile(
   agentContext: AgentContext | null,
   gitExecutable = "git",
 ) {
+  const absolutePath = join(repoRoot, filePath);
   const largeFileCheck = inspectLargeUntrackedFile(repoRoot, filePath);
   if (largeFileCheck.shouldSkip) {
     return buildDiffFile(
@@ -199,6 +200,40 @@ function buildUntrackedDiffFile(
     );
   }
 
+  if (input.options.vcs === "sl") {
+    if (isProbablyBinaryFile(absolutePath)) {
+      return buildDiffFile(
+        createSkippedBinaryMetadata(filePath, "new"),
+        `Binary file skipped: ${filePath}\n`,
+        index,
+        sourcePrefix,
+        agentContext,
+        { isBinary: true, isUntracked: true },
+      );
+    }
+
+    const patch = createTwoFilesPatch(
+      "/dev/null",
+      escapeUntrackedPatchPath(filePath),
+      "",
+      fs.readFileSync(absolutePath, "utf8"),
+      "",
+      "",
+      { context: 3 },
+    ).replaceAll("\r\n", "\n");
+
+    return buildDiffFile(
+      parseUntrackedPatchFile(patch, filePath),
+      patch,
+      index,
+      sourcePrefix,
+      agentContext,
+      {
+        isUntracked: true,
+      },
+    );
+  }
+
   const patch = normalizeUntrackedPatchHeaders(
     runGitUntrackedFileDiffText(input, filePath, { repoRoot, gitExecutable }),
     filePath,

src/core/patch/normalize.ts

@@ -1,6 +1,15 @@
 import { normalizeGitPatchPrefixes } from "./gitFormat";
 import { stripGitLogMetadata } from "./gitLog";
 
+/** Escape only path characters that break unified-diff header parsing. */
+export function escapeUntrackedPatchPath(path: string) {
+  return path
+    .replaceAll("\\", "\\\\")
+    .replaceAll("\t", "\\t")
+    .replaceAll("\n", "\\n")
+    .replaceAll("\r", "\\r");
+}
+
 /** Remove terminal escape sequences so Git-colored pager input still parses as plain patch text. */
 export function stripTerminalControl(text: string) {
   return text

src/core/sl.test.ts

@@ -0,0 +1,111 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { buildSlDiffArgs, runSlText } from "./sl";
+
+const slAvailable = (() => {
+  try {
+    return (
+      Bun.spawnSync(["sl", "version"], { stdin: "ignore", stdout: "ignore", stderr: "ignore" })
+        .exitCode === 0
+    );
+  } catch {
+    return false;
+  }
+})();
+const tempDirs: string[] = [];
+
+function cleanupTempDirs() {
+  while (tempDirs.length > 0) {
+    const dir = tempDirs.pop();
+    if (dir) {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  }
+}
+
+function createTempDir(prefix: string) {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), prefix)));
+  tempDirs.push(dir);
+  return dir;
+}
+
+function sl(cwd: string, ...cmd: string[]) {
+  const proc = Bun.spawnSync(["sl", "--noninteractive", "--color", "never", ...cmd], {
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+    stdin: "ignore",
+  });
+
+  if (proc.exitCode !== 0) {
+    const stderr = Buffer.from(proc.stderr).toString("utf8");
+    throw new Error(stderr.trim() || `sl ${cmd.join(" ")} failed`);
+  }
+
+  return Buffer.from(proc.stdout).toString("utf8");
+}
+
+function createTempSlRepo(prefix: string) {
+  const dir = createTempDir(prefix);
+  sl(dir, "init", "--git");
+  sl(dir, "config", "--local", "ui.username", "Test User <test@example.com>");
+  return dir;
+}
+
+afterEach(() => {
+  cleanupTempDirs();
+});
+
+describe("sl command helpers", () => {
+  test("reports a friendly error when sl is not installed or not on PATH", () => {
+    expect(() =>
+      runSlText({
+        input: {
+          kind: "vcs",
+          staged: false,
+          options: { mode: "auto", vcs: "sl" },
+        },
+        args: ["root"],
+        slExecutable: "definitely-not-a-real-sl-binary",
+      }),
+    ).toThrow(
+      'Sapling is required for `hunk diff` when `vcs = "sl"`, but `definitely-not-a-real-sl-binary` was not found in PATH.',
+    );
+  });
+
+  test.skipIf(!slAvailable)("reports a friendly error outside a sl repository", () => {
+    const dir = createTempDir("hunk-sl-nonrepo-");
+
+    expect(() =>
+      runSlText({
+        input: {
+          kind: "vcs",
+          staged: false,
+          options: { mode: "auto", vcs: "sl" },
+        },
+        args: ["root"],
+        cwd: dir,
+      }),
+    ).toThrow('`hunk diff` must be run inside a Sapling repository when `vcs = "sl"`.');
+  });
+
+  test.skipIf(!slAvailable)("reports a friendly error for invalid revsets", () => {
+    const dir = createTempSlRepo("hunk-sl-invalid-revset-");
+    const input = {
+      kind: "vcs" as const,
+      range: "missing_revision",
+      staged: false,
+      options: { mode: "auto" as const, vcs: "sl" as const },
+    };
+
+    expect(() =>
+      runSlText({
+        input,
+        args: buildSlDiffArgs(input),
+        cwd: dir,
+      }),
+    ).toThrow("`hunk diff missing_revision` could not resolve Sapling revset `missing_revision`.");
+  });
+});