Diff Backend Git and File State
Overview
This area is the diff pane's backend and file-state layer. mods/…/backend-of.ts chooses the version-control backend for the session directory by asking INSTALLED_BACKEND_PROBES from mods/…/installed-backend-probes.ts first, then falling back to the Git backend in mods/…/git-backend-of.ts. The shipped probe set is empty; a compiling host may add non-Git probes before plugin registration. A selected backend exposes its pinned repository, base modes, wording, fetchDiff, fetchHunks, and headKeyOf through mods/…/backend.ts.
The Git backend starts by resolving the repository with one unpinned git rev-parse --path-format=absolute --show-toplevel --git-dir --git-common-dir in mods/…/repository-of.ts. After that, mods/…/git-backend-of.ts pins every child process with --git-dir=<gitDir>, --work-tree=<toplevel>, cwd set to the top-level, LC_ALL=C, LANGUAGE='', and Limits.GIT_TIMEOUT_MS from mods/…/git-timeout-ms.ts. Failed or timed-out children resolve to FAILED_RUN instead of rejecting, so fetch code reports unavailable data rather than throwing.
Each Git fetch runs through mods/…/fetch-diff.ts. Before reading diffs it checks transient repository state with mods/…/is-transient.ts, which lists the git directory and treats real merge, rebase, cherry-pick, and revert markers as busy. Busy or unreadable states return { kind: 'unavailable' }, allowing callers to keep the last good view. Otherwise mods/…/fetch-context-of.ts builds a fetch context with a working-tree stamp probe, then dispatches branch mode to mods/…/branch-tier.ts and session/uncommitted modes to mods/…/working-tree-tier.ts.
Branch mode resolves its base in mods/…/branch-base-of.ts: it reads the current branch, chooses a default branch via origin/HEAD or conventional remote refs in mods/…/default-branch-of.ts, then checks merge-base candidates against origin/<default> and local <default> in mods/…/merge-base-candidates-of.ts. mods/…/branch-source-of.ts turns that into either a branch source with a merge base, a branch source at HEAD, or a plain working-tree source. A transient merge-base/stat failure returns unavailable; a permanent no-base condition falls back to a working-tree diff.
Session and uncommitted modes use mods/…/working-tree-tier.ts to compare the working tree against HEAD. Session mode tags pre-session tracked rows with mods/…/tag-pre-session.ts; uncommitted mode keeps tracked rows as-is. Both modes merge untracked files through mods/…/with-untracked.ts. If a HEAD diff cannot run because the repository is before its first commit, mods/…/unborn-tier.ts verifies an unborn HEAD, reads staged rows with --cached, overlays unstaged edits using mods/…/overlay-unstaged.ts, and marks stale paths whose staged bodies no longer match the working tree.
Diff rows and totals are read by mods/…/stats-of.ts. It first tries git diff <base> --numstat -z --, parses raw paths and rename records in mods/…/parse-numstat.ts, and caps kept rows at Limits.MAX_FILES while preserving full totals. If host output was cut, it records the base in GitDeps.cutBases and falls back to --shortstat only when the totals exceed Limits.MAX_FILES_FOR_DETAILS; otherwise the diff is unreadable. Past MAX_FILES_FOR_DETAILS, rows are intentionally empty, hunks are not fetched, and untracked probing is skipped.
Untracked rows are added after tracked rows. mods/…/untracked-files.ts lists untracked, unignored paths with git ls-files -z --others --exclude-standard --full-name; mods/…/untracked-rows-of.ts turns them into 0/0 FileStat rows. Session mode can include pre-session untracked files, while branch and uncommitted modes use only session untracked files. Dating uses mods/…/datings-of.ts, mods/…/stamp-if-file.ts, and mods/…/was-dirty-at-start.ts: a path is pre-session only when its mtime is before sessionStartMs and the first-fetch baseline from mods/…/dirty-paths-of.ts says it was dirty then. This prevents a rename or moved-in file with an old filesystem timestamp from being hidden as old work.
File dating and HEAD tracking deliberately go through host file probes instead of following paths blindly. mods/…/entry-kinds-of.ts adapts Host.listDir into directory-entry maps with kinds, mods/…/mtime-of.ts adapts Host.stat into nullable mtimes, and mods/…/kind-walk-of.ts lists each directory once, refuses to descend through symlinks, and returns over-budget after Limits.MAX_LISTED_DIRECTORIES. mods/…/head-key-of.ts builds a key from .git/HEAD, its target ref or logs/HEAD, and packed-refs, falling back to git rev-parse HEAD when HEAD is not a plain file or an unsafe symbolic ref cannot be dated.
Hunk bodies are read separately by mods/…/fetch-hunks.ts against the same DiffData.baseRef used for stats. It omits bodiless rows: untracked files, binary files, renames, and stale unborn-head paths. For the rest, it chunks literal pathspecs under Limits.MAX_PATHSPEC_CHARS, runs git diff --raw -z -p, and parses bodies in mods/…/parse-file-diffs.ts. If an answer is cut, files without a paired patch wait for recursive smaller requests; if no file can be settled, the remaining rows get null hunks. Parsed hunks are keyed by row path, with closing empty rows inserted except for the last file in the diff.
The pane uses several small file-state helpers around this backend data. mods/…/drawn-files-of.ts decides which fetched FileStat rows need bodies drawn or opened: inline placement only draws the visible dialog window and skips turn entries; docked placement draws listed session rows and, when expanded and under Limits.PRE_SESSION_BODY_CAP, pre-session rows. mods/…/is-noise-file.ts hides tests and generated files behind the tests/generated row using mods/…/is-test-file.ts and mods/…/is-generated-file.ts; their rule tables live under the matching test-* and generated-* files. mods/…/open-outcome-of.ts interprets $.ui.open results as placed, awaited for no-surface*, or withdrawn. mods/…/is-checkpointing.ts mirrors the built-in checkpoint gate: checkpointing is off if settings set fileCheckpointingEnabled false or CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING is a truthy string.
Coverage / Routing
This doc owns the diff backend and file-state helpers under:
mods/diff/hooks/backend/**mods/diff/hooks/git/**mods/diff/hooks/drawn-files-of/**mods/diff/hooks/entry-kinds-of/**mods/diff/hooks/classify/**mods/diff/hooks/kept-of/**mods/diff/hooks/open-outcome/**mods/diff/hooks/mtime-of/**mods/diff/hooks/count-of/**mods/diff/hooks/limits/**mods/diff/hooks/array-of/**mods/diff/hooks/is-checkpointing/**
Route changes here when they alter Git command orchestration, base selection, diff/stat/hunk parsing, untracked/pre-session dating, HEAD-key detection, file kind/mtime probing, noise classification, row drawing/open outcomes, or the shared limits that bound those behaviors.
Coupling
- If a Git command's stdout shape changes in mods/…/stats-of.ts, mods/…/untracked-files.ts, or mods/…/fetch-hunks.ts, update the corresponding parsers in mods/…/parse-numstat.ts, mods/…/parse-file-diffs.ts, and mods/…/parse-shortstat.ts; the fetch layer treats parser failure as unavailable or missing hunks rather than surfacing a schema error.
- If mods/…/max-files.ts, mods/…/max-files-for-details.ts, mods/…/max-untracked-probes.ts, or mods/…/max-listed-directories.ts changes, verify mods/…/stats-of.ts, mods/…/with-untracked.ts, mods/…/untracked-rows-of.ts, and mods/…/kind-walk-of.ts; these limits jointly decide whether rows, untracked files, and dates exist at all.
- If
FileStatorDiffDatachanges in mods/…/file-stat.ts or mods/…/diff-data.ts, verify producers in mods/…/parse-numstat.ts, mods/…/untracked-rows-of.ts, mods/…/diff-data-of.ts, and consumers in mods/…/fetch-hunks.ts and mods/…/drawn-files-of.ts; the same row flags determine rendering, hunk eligibility, and pre-session hiding. - If the host adapters in mods/…/entry-kinds-of.ts or mods/…/mtime-of.ts change to follow symlinks or throw on unreadable paths, re-check mods/…/kind-walk-of.ts, mods/…/stamp-if-file.ts, mods/…/datings-of.ts, and mods/…/head-key-of.ts; their safety depends on nullable, lstat-like host probes.
- If branch-base telemetry or source labels change in mods/…/branch-base-of.ts or mods/…/branch-source-of.ts, verify mods/…/branch-tier.ts; it calls
onBranchBaseon every branch fetch and uses the resolved source both to choosebaseRefand to label the data. - If checkpoint or UI-open behavior changes in mods/…/is-checkpointing.ts or mods/…/open-outcome-of.ts, verify the pane lifecycle code that calls these helpers; their return values decide whether an edit-triggered pane appears, waits for a surface, or is withdrawn.
Risks
- mods/…/stats-of.ts relies on detecting host-output truncation and then accepting
--shortstatonly when totals exceedLimits.MAX_FILES_FOR_DETAILS. IfParse.isWholeAnswerorLimits.HOST_OUTPUT_CAP_BYTESdrift from the process host's real cap, a cut--numstatcan be mistaken for a complete small diff, dropping rows or totals silently. - mods/…/head-key-of.ts derives refresh keys from filesystem timestamps of HEAD, refs, and
packed-refs. On filesystems with coarse mtimes or packed refs rewritten without an mtime change, a HEAD move can fail to change the key and the pane can miss a refresh until another poll signal changes. - mods/…/fetch-hunks.ts recursively retries unsettled paths after parsing partial
git diff --raw -z -poutput. If mods/…/parse-file-diffs.ts cannot pair names to patches because user Git config changes prefixes beyond the forced--src-prefix/--dst-prefixassumptions, rows receivenullhunks even though stats are present. - mods/…/datings-of.ts and mods/…/was-dirty-at-start.ts classify pre-session work from mtimes plus a first-fetch dirty baseline. If the first baseline read in mods/…/git-backend-of.ts fails,
wasDirtyAtStartreturns true for every path, so old mtimes can hide moved or renamed files as pre-session work.