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,

docs/watch-benchmark.md

@@ -0,0 +1,80 @@
+# Watch Mode Benchmark: Evented vs Polling
+
+Benchmark comparing the old 250ms polling watch implementation (npm `hunkdiff@0.17.0`) against the evented Chokidar-based hybrid observer (`elucid/file-watch` PR #531).
+
+## Setup
+
+- **Repo:** `modem/modem` (large production monorepo)
+- **Branch state:** dirty working tree with untracked files
+- **OLD binary:** `/Users/justin/.npm-global/bin/hunk` (npm release 0.17.0, 250ms `setInterval` polling)
+- **NEW binary:** `/Users/justin/.local/bin/hunk` (PR build from `elucid/file-watch`, Chokidar + 10s safety poll)
+- **Command:** `hunk diff --watch`
+
+## Method
+
+### Git subprocess counting
+
+A wrapper script was placed ahead of real `git` on PATH. It logs every invocation with a timestamp to a per-version log file, then `exec`s the real git binary:
+
+```bash
+#!/bin/bash
+printf '%s %s\n' "$(date +%s.%N)" "$*" >> "${HUNK_BENCH_GIT_LOG}"
+exec /nix/store/.../git "$@"
+```
+
+Both versions were launched in separate herdr panes with `HUNK_BENCH_GIT_LOG` and `PATH` set via `--env` on `herdr pane split`. After both rendered their initial diff, the log files were zeroed and CPU times recorded. The benchmark then sampled every 10 seconds for 60 seconds using `ps -p $PID -o cputime=` and `wc -l` on the log files.
+
+### Startup time
+
+Both versions were launched sequentially in herdr panes on the same repo. A polling loop read each pane's visible content via `herdr pane read` at ~20ms intervals, looking for hunk's menu bar (`File  View`). The elapsed time from `herdr pane run` to first detection was recorded. Each version was quit (`q`) and relaunched between trials. Five trials were run per version.
+
+## Results
+
+### Idle overhead (60 seconds, no file changes)
+
+Sampled at 10-second intervals:
+
+```
+t=10s  OLD cpu=0:02.68  git= 199  |  NEW cpu=0:01.61  git=   6
+t=20s  OLD cpu=0:02.93  git= 319  |  NEW cpu=0:01.63  git=   9
+t=30s  OLD cpu=0:03.14  git= 439  |  NEW cpu=0:01.65  git=  12
+t=40s  OLD cpu=0:03.35  git= 559  |  NEW cpu=0:01.67  git=  15
+t=50s  OLD cpu=0:03.55  git= 679  |  NEW cpu=0:01.69  git=  18
+t=60s  OLD cpu=0:03.76  git= 799  |  NEW cpu=0:01.71  git=  21
+```
+
+| Metric                           | OLD (polling) | NEW (evented) | Improvement   |
+| -------------------------------- | ------------- | ------------- | ------------- |
+| Git invocations in 60s           | 799           | 21            | **38× fewer** |
+| Git calls/second                 | ~13.3/s       | ~0.35/s       | —             |
+| CPU time consumed (idle portion) | ~1.50s        | ~0.13s        | **~12× less** |
+
+The old version fires multiple git commands per 250ms poll cycle (~13/s). The new version fires a small batch every ~10 seconds (safety poll only).
+
+### Startup time (5 trials)
+
+| Trial    | OLD        | NEW        |
+| -------- | ---------- | ---------- |
+| 1        | 1708ms     | 1674ms     |
+| 2        | 1669ms     | 1703ms     |
+| 3        | 1671ms     | 1670ms     |
+| 4        | 1662ms     | 1756ms     |
+| 5        | 1684ms     | 1691ms     |
+| **Mean** | **1679ms** | **1699ms** |
+
+Startup time is identical within noise (~1.7s). Both versions are dominated by the initial `git diff` load cost on this repo. The PR's improvement is entirely in the idle steady-state after the diff is rendered.
+
+### Refresh latency (evented PR, separate E2E test repo)
+
+| Scenario                    | Latency |
+| --------------------------- | ------- |
+| Simple tracked-file write   | ~340ms  |
+| Atomic temp-file + rename   | ~418ms  |
+| Large 241-line diff update  | ~406ms  |
+| New untracked file creation | ~682ms  |
+
+All refreshes were passive — no keyboard or mouse input was sent to hunk.
+
+## Conclusion
+
+The evented observer eliminates virtually all idle CPU and subprocess overhead while maintaining identical startup performance and sub-second passive refresh latency. The improvement scales with the number of open `--watch` sessions: each idle tab drops from ~13 git calls/second to ~0.35.

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

@@ -96,6 +96,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 } from "node:path";
 import {
   buildGitDiffArgs,
+  buildGitIgnoredDirectoryArgs,
   buildGitStashShowArgs,
   buildGitStatusArgs,
+  listGitIgnoredDirectoryRoots,
+  parseGitIgnoredDirectoryRoots,
   resolveGitDiffEndpoints,
+  resolveGitMetadata,
   runGitText,
 } from "./git";
 import type { VcsDiffCommandInput } from "./types";
@@ -39,6 +43,11 @@ function createTempRepo(prefix: string) {
   return dir;
 }
 
+/** Normalize symlinked and Windows short/long temp path spellings before path comparisons. */
+function normalizeComparablePath(path: string) {
+  return realpathSync.native(path).replace(/\\/g, "/");
+}
+
 function makeGitInput(overrides: Partial<VcsDiffCommandInput> = {}): VcsDiffCommandInput {
   return {
     kind: "vcs",
@@ -95,6 +104,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 +144,114 @@ 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.map(normalizeComparablePath)).toEqual([
+      normalizeComparablePath(join(repoRoot, "node_modules")),
+    ]);
+    expect(roots.map(normalizeComparablePath)).not.toContain(
+      normalizeComparablePath(join(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 }).map(normalizeComparablePath),
+    ).toEqual([normalizeComparablePath(join(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 }).map(normalizeComparablePath),
+    ).toEqual([normalizeComparablePath(join(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 comparableRoots = roots.map(normalizeComparablePath);
+    const trackedPath = normalizeComparablePath(join(repoRoot, "vendor", "tracked.txt"));
+
+    expect(comparableRoots).toEqual([
+      normalizeComparablePath(join(repoRoot, "vendor", "generated")),
+    ]);
+    expect(comparableRoots.some((root) => trackedPath.startsWith(`${root}/`))).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(normalizeComparablePath(normal.repoRoot)).toBe(normalizeComparablePath(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(normalizeComparablePath(linked.repoRoot)).toBe(normalizeComparablePath(linkedRoot));
+    expect(linked.gitDir).not.toBe(linked.commonDir);
+    expect(normalizeComparablePath(linked.gitDir)).toContain("/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-");