feat(watch): replace 250 ms watch polling with evented filesystem observation

.changeset/calm-files-watch.md

@@ -0,0 +1,5 @@
+---
+"hunkdiff": patch
+---
+
+Reduce Git polling and CPU use in watch mode while preserving continuous refreshes with a polling fallback.

.changeset/native-recursive-watch.md

@@ -0,0 +1,5 @@
+---
+"hunkdiff": patch
+---
+
+Reduce watch-mode startup cost on macOS and Windows by using bounded native recursive filesystem observation.

.github/workflows/ci.yml

@@ -207,6 +207,11 @@ jobs:
       - name: Build binary
         run: bun run build:bin
 
+      - name: Verify compiled binary watch mode
+        run: bun test ./test/pty/watch.test.ts
+        env:
+          HUNK_TEST_EXECUTABLE: ${{ github.workspace }}/dist/hunk
+
       - name: Upload binary artifact
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:

.github/workflows/pr-ci.yml

@@ -180,6 +180,11 @@ jobs:
       - name: Stage prebuilt npm packages
         run: bun run build:prebuilt:npm
 
+      - name: Verify compiled binary watch mode
+        run: bun test ./test/pty/watch.test.ts
+        env:
+          HUNK_TEST_EXECUTABLE: ${{ github.workspace }}/dist/hunk
+
       - name: Verify staged prebuilt packs
         run: bun run check:prebuilt-pack
 

README.md

@@ -80,6 +80,8 @@ hunk diff before.ts after.ts --watch        # auto-reload when either file chang
 git diff --no-color | hunk patch -          # review a patch from stdin
 ```
 
+Watch mode remains continuous. Direct-file and Git-backed reviews normally use filesystem observation to refresh promptly, with periodic polling retained as a fallback for missed events or unavailable watchers. Jujutsu and Sapling reviews currently use polling rather than filesystem observation.
+
 ### Working with agents
 
 1. Open Hunk in another terminal with `hunk diff` or `hunk show`.

benchmarks/highlight-prefetch.ts

@@ -52,6 +52,7 @@ function createDiffFile(index: number, marker: string): DiffFile {
 
 function createBootstrap(): AppBootstrap {
   return {
+    reloadContext: { cwd: process.cwd() },
     input: {
       kind: "vcs",
       staged: false,

benchmarks/large-stream-fixture.ts

@@ -130,6 +130,7 @@ export function createLargeSplitStreamBootstrap({
   contentVariant = "ascii",
 }: LargeSplitStreamFixtureOptions = {}): AppBootstrap {
   return {
+    reloadContext: { cwd: process.cwd() },
     input: {
       kind: "vcs",
       staged: false,
@@ -230,6 +231,7 @@ export function createHugeStreamBootstrap(): AppBootstrap {
   files.push(createGiantSingleDiffFile(HUGE_FILE_COUNT + 1));
 
   return {
+    reloadContext: { cwd: process.cwd() },
     input: {
       kind: "vcs",
       staged: false,

nix/bun.lock.nix

@@ -429,6 +429,10 @@
     url = "https://registry.npmjs.org/character-entities-legacy/-/character-entities-legacy-3.0.0.tgz";
     hash = "sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==";
   };
+  "chokidar@4.0.3" = fetchurl {
+    url = "https://registry.npmjs.org/chokidar/-/chokidar-4.0.3.tgz";
+    hash = "sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==";
+  };
   "cli-cursor@5.0.0" = fetchurl {
     url = "https://registry.npmjs.org/cli-cursor/-/cli-cursor-5.0.0.tgz";
     hash = "sha512-aCj4O5wKyszjMmDT4tZj93kxyydN/K5zPWSCe6/0AV/AA1pqe5ZBIw0a2ZfPQV7lL5/yb5HsUreJ6UFAF1tEQw==";
@@ -681,6 +685,10 @@
     url = "https://registry.npmjs.org/react/-/react-19.2.4.tgz";
     hash = "sha512-9nfp2hYpCwOjAN+8TZFGhtWEwgvWHXqESH8qT89AT/lWklpLON22Lc8pEtnpsZz7VmawabSU0gCjnj8aC0euHQ==";
   };
+  "readdirp@4.1.2" = fetchurl {
+    url = "https://registry.npmjs.org/readdirp/-/readdirp-4.1.2.tgz";
+    hash = "sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg==";
+  };
   "regex-recursion@6.0.2" = fetchurl {
     url = "https://registry.npmjs.org/regex-recursion/-/regex-recursion-6.0.2.tgz";
     hash = "sha512-0YCaSCq2VRIebiaUviZNs0cBz1kg5kVS2UKUfNIx8YVs1cN3AV7NTctO5FOKBA+UT2BPJIWZauYHPqJODG50cg==";

package.json

@@ -95,6 +95,7 @@
   "dependencies": {
     "@pierre/diffs": "1.2.2",
     "bun": "^1.3.14",
+    "chokidar": "^4.0.3",
     "commander": "^14.0.3",
     "diff": "^8.0.3",
     "shell-quote": "1.8.4",

src/core/git.test.ts

@@ -1,12 +1,16 @@
 import { afterEach, describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { join, resolve, sep } from "node:path";
 import {
   buildGitDiffArgs,
+  buildGitIgnoredDirectoryArgs,
   buildGitStashShowArgs,
   buildGitStatusArgs,
+  listGitIgnoredDirectoryRoots,
+  parseGitIgnoredDirectoryRoots,
   resolveGitDiffEndpoints,
+  resolveGitMetadata,
   runGitText,
 } from "./git";
 import type { VcsDiffCommandInput } from "./types";
@@ -95,6 +99,29 @@ describe("git command helpers", () => {
     ]);
   });
 
+  test("builds the collapsed ignored-directory query", () => {
+    expect(buildGitIgnoredDirectoryArgs()).toEqual([
+      "ls-files",
+      "--full-name",
+      "--others",
+      "--ignored",
+      "--exclude-standard",
+      "--directory",
+      "-z",
+    ]);
+  });
+
+  test("parses only NUL-delimited collapsed directories into unique absolute roots", () => {
+    const repoRoot = resolve(tmpdir(), "hunk-ignored-parser");
+
+    expect(
+      parseGitIgnoredDirectoryRoots(
+        ["dependencies/", "ignored.log", "build/nested/", "dependencies/", ""].join("\0"),
+        repoRoot,
+      ),
+    ).toEqual([resolve(repoRoot, "dependencies"), resolve(repoRoot, "build/nested")]);
+  });
+
   test("reports a friendly error when git is not installed or not on PATH", () => {
     expect(() =>
       runGitText({
@@ -112,6 +139,107 @@ describe("git command helpers", () => {
   });
 });
 
+describe("listGitIgnoredDirectoryRoots", () => {
+  test("collapses a dependency-heavy ignored tree without pruning nonignored paths", () => {
+    const repoRoot = createTempRepo("hunk-git-ignored-dependencies-");
+    writeFileSync(join(repoRoot, ".gitignore"), "node_modules/\nignored.log\n");
+    for (let index = 0; index < 25; index += 1) {
+      const packageRoot = join(repoRoot, "node_modules", `package-${index}`, "cache");
+      mkdirSync(packageRoot, { recursive: true });
+      writeFileSync(join(packageRoot, "index.js"), `${index}\n`);
+    }
+    writeFileSync(join(repoRoot, "ignored.log"), "ignored file\n");
+    mkdirSync(join(repoRoot, "src"), { recursive: true });
+    writeFileSync(join(repoRoot, "src", "untracked.ts"), "export {};\n");
+
+    const roots = listGitIgnoredDirectoryRoots(makeGitInput(), { cwd: join(repoRoot, "src") });
+
+    expect(roots).toEqual([join(realpathSync(repoRoot), "node_modules")]);
+    expect(roots).not.toContain(join(realpathSync(repoRoot), "src"));
+  });
+
+  test("honors nested ignore negation instead of pruning its visible ancestor", () => {
+    const repoRoot = createTempRepo("hunk-git-ignored-negation-");
+    writeFileSync(
+      join(repoRoot, ".gitignore"),
+      ["generated/*", "!generated/.gitignore", "!generated/keep/", ""].join("\n"),
+    );
+    mkdirSync(join(repoRoot, "generated", "discard"), { recursive: true });
+    mkdirSync(join(repoRoot, "generated", "keep"), { recursive: true });
+    writeFileSync(
+      join(repoRoot, "generated", ".gitignore"),
+      ["keep/*", "!keep/visible.txt", ""].join("\n"),
+    );
+    writeFileSync(join(repoRoot, "generated", "discard", "output.js"), "ignored\n");
+    writeFileSync(join(repoRoot, "generated", "keep", "hidden.txt"), "ignored file\n");
+    writeFileSync(join(repoRoot, "generated", "keep", "visible.txt"), "visible\n");
+
+    expect(listGitIgnoredDirectoryRoots(makeGitInput(), { cwd: repoRoot })).toEqual([
+      join(realpathSync(repoRoot), "generated", "discard"),
+    ]);
+  });
+
+  test("honors repository-local excludes", () => {
+    const repoRoot = createTempRepo("hunk-git-ignored-info-exclude-");
+    writeFileSync(join(repoRoot, ".git", "info", "exclude"), "local-cache/\n");
+    mkdirSync(join(repoRoot, "local-cache", "nested"), { recursive: true });
+    writeFileSync(join(repoRoot, "local-cache", "nested", "data"), "ignored\n");
+
+    expect(listGitIgnoredDirectoryRoots(makeGitInput(), { cwd: repoRoot })).toEqual([
+      join(realpathSync(repoRoot), "local-cache"),
+    ]);
+  });
+
+  test("does not prune an ignored parent containing a forced tracked file", () => {
+    const repoRoot = createTempRepo("hunk-git-ignored-tracked-");
+    writeFileSync(join(repoRoot, ".gitignore"), "vendor/\n");
+    mkdirSync(join(repoRoot, "vendor", "generated"), { recursive: true });
+    writeFileSync(join(repoRoot, "vendor", "tracked.txt"), "tracked\n");
+    writeFileSync(join(repoRoot, "vendor", "generated", "output.txt"), "ignored\n");
+    git(repoRoot, "add", ".gitignore");
+    git(repoRoot, "add", "-f", "vendor/tracked.txt");
+    git(repoRoot, "commit", "-m", "track forced file");
+
+    const roots = listGitIgnoredDirectoryRoots(makeGitInput(), { cwd: repoRoot });
+    const trackedPath = join(realpathSync(repoRoot), "vendor", "tracked.txt");
+
+    expect(roots).toEqual([join(realpathSync(repoRoot), "vendor", "generated")]);
+    expect(roots.some((root) => trackedPath.startsWith(`${root}${sep}`))).toBe(false);
+  });
+
+  test("falls back to no pruning when best-effort discovery fails", () => {
+    expect(
+      listGitIgnoredDirectoryRoots(makeGitInput(), {
+        cwd: tmpdir(),
+        repoRoot: tmpdir(),
+        gitExecutable: "definitely-not-a-real-git-binary",
+      }),
+    ).toEqual([]);
+  });
+});
+
+describe("resolveGitMetadata", () => {
+  test("resolves normal and linked-worktree metadata directories", () => {
+    const repoRoot = createTempRepo("hunk-git-metadata-");
+    writeFileSync(join(repoRoot, "x.txt"), "x\n");
+    git(repoRoot, "add", "x.txt");
+    git(repoRoot, "commit", "-m", "initial");
+
+    const normal = resolveGitMetadata(makeGitInput(), { cwd: repoRoot });
+    expect(normal.repoRoot).toBe(realpathSync(repoRoot));
+    expect(normal.gitDir).toBe(normal.commonDir);
+
+    const linkedRoot = mkdtempSync(join(tmpdir(), "hunk-git-linked-"));
+    tempDirs.push(linkedRoot);
+    git(repoRoot, "worktree", "add", linkedRoot, "-b", "linked-test");
+    const linked = resolveGitMetadata(makeGitInput(), { cwd: linkedRoot });
+    expect(linked.repoRoot).toBe(realpathSync(linkedRoot));
+    expect(linked.gitDir).not.toBe(linked.commonDir);
+    expect(linked.gitDir).toContain(join("worktrees", "hunk-git-linked-"));
+    expect(linked.commonDir).toBe(normal.commonDir);
+  });
+});
+
 describe("resolveGitDiffEndpoints", () => {
   test("staged diffs compare HEAD against the index", () => {
     const repoRoot = createTempRepo("hunk-endpoints-staged-");