Files
archived-orca/src/main/git/source-control/worktree-diff-stamp.ts
T
Neil 26dfa46aa9 fix(wsl): resolve sparse-checkout and diff-stamp gitdirs through the caller's distro (#17932)
Two main-process `resolveGitDir` call sites dropped the WSL distro their caller
already held, so they could only resolve a gitdir pointer whose spelling carries
its own translation: a `//wsl.localhost/<Distro>/...` base, or a `/mnt/<letter>`
drvfs pointer that maps to a drive letter on its own.

The layout that needs the third case is a repo inside the distro's filesystem
with its worktrees on the Windows drive. `git worktree list` reports the worktree
as `/mnt/c/wt/x`, which the listing translates to `C:\wt\x` — a base that no
longer names a distro — while the `.git` gitfile beside it points at
`/home/me/repo/.git/worktrees/x`, which has no drive to derive. Win32 then treats
that pointer as absolute and reads a path that names nothing:

- `detectSparseCheckout` stats `info/sparse-checkout` under the fabricated path,
  always misses, and reports the worktree as non-sparse — no sparse badge, and
  the file list claims files that are not on disk.
- `readWorktreeDiffStamp` reads HEAD under the same path, gets nothing, and
  returns null. Null is the safe answer ("cannot prove unchanged"), but it
  retires the settled-diff cache for every file in that worktree, so each diff
  respawns Git.

Both callers already have the distro: the listing threads its
`GitWorktreeExecOptions` to `annotateSparseCheckoutStatus`, on through
`detectSparseCheckoutCached` (the annotation cache added by #17859) and its
background revalidation probe, and finally to `detectSparseCheckout`; and
`file-diff` already forwards its `GitRuntimeOptions` to `readWorktreeDiffStamp`,
which now forwards it to `resolveGitDir` as well.

`resolveGitMetadataPath` still prefers a UNC base's distro and still tries drvfs
before the caller-named distro, so nothing that resolved before resolves
differently.

The cache hop matters twice over. It is the only remaining caller of
`detectSparseCheckout`, so without threading it the fix would not reach the
probe at all. And the cache is where the bug turns sticky. #17859 keyed entries
on `repoPath` + `worktreePath` alone, on the reasoning that the distro is a
property of the repo and so every read for a given `repoPath` carries the same
one. That invariant does not hold. `listRepoWorktrees(repo)` is called with no
options at all from the filesystem-auth root rebuild
(`registered-worktree-roots-cache.ts`, reached from `ensureAuthorizedRootsCache`
on any auth check with a dirty cache) and from the local worktree-ownership
check in `filesystem-worktree-helpers.ts`. Both land on the *same* key as the
distro-carrying listing, because `translateWslOutputPaths` derives the distro
from the cwd spelling before falling back to `options.wslDistro`, so a
UNC-spelled repo path yields the identical `C:\...` worktree row either way.
Measured on Windows in one process, branch build: a distro-less read followed by
a distro-carrying read reported the sparse worktree as non-sparse both times.

So `wslDistro` now joins the cache key -- trimmed and lowercased, matching how
the rest of the codebase compares distro names, and appended last so the
repo-scoped prefix delete still matches every variant. The per-path invalidate
becomes a prefix delete for the same reason, dropping every distro variant of a
removed or moved worktree.

Keying on it closes both halves of the defect. A correct caller can no longer be
served an answer derived without the distro it supplied. And because the entry a
reader reaches is now selected by the same distro it would re-probe with,
`revalidateInBackground` can no longer re-derive a warm entry under weaker
options -- which mattered on its own: a distro-less reader crossing the
five-minute window would otherwise flip a correct `true` to `false`, and the
resulting change notification runs the registered invalidator, clearing the
whole repo's cache and re-probing every worktree cold, on a five-minute loop.

Cost of the extra key dimension is bounded by the number of distinct distros a
given repo is actually read under: one where a distro is threaded everywhere,
two while the distro-less callers above still exist. Entries are still
repo-scoped, and both clears already sweep by prefix.

Per-platform delta:
- macOS/Linux: no change. Guest-pointer translation is gated to win32 and a
  caller-named distro is ignored off Windows; no caller supplies one there, so
  the cache keys and probes exactly as before.
- native Windows, no WSL: no change. `wslDistro` is undefined, so the resolver
  takes exactly the branches it took before and every read keys on the same
  empty distro component, so the cache behaves exactly as it did.
- Windows + WSL, UNC-spelled worktree: no change. The base already names the
  distro and outranks the caller's.
- Windows + WSL, drvfs-spelled worktree with a drvfs pointer: no change. The
  drive-letter derivation still runs first.
- Windows + WSL, drvfs-spelled worktree with a non-drvfs pointer: the sparse
  badge appears and the settled-diff cache starts hitting. Both previously
  failed toward "not sparse" / "do not cache", so neither can now serve a stale
  answer, and the distro-less listings no longer share the badge's cache entry.
- SSH/relay: none. Those paths return through the provider branch before
  reaching either function.
- folder workspaces, GitLab: none. Neither is on these code paths.

Not in this change:
- `readRepoCommonDirFromDisk` (worktree-listing). Passing the distro there is
  inert: a repo root's `.git` is a directory, so the gitfile-pointer branch never
  runs, and when `repoPath` itself is guest-spelled the preceding `stat` already
  fails — which no `resolveGitDir` option can fix.
- The two `findExistingWorktreeSymlinkPaths` calls on the removal paths. Both
  receive `registeredWorktree.path` from `listWorktreesStrict`, which already
  translates every row out of the guest namespace, so the distro would be a
  no-op. The `removeWorktreeLinkedPaths` unlink beside them is untranslated too,
  so a half-threaded fix would only move the refusal from Orca's preflight to
  `git worktree remove`.
- An absolute `commondir` payload, which `resolveGitCommonDir` still resolves
  untranslated. Git writes that file relative in the layouts above, and the
  failure direction is unchanged.
- Giving the two distro-less `listRepoWorktrees(repo)` callers a distro. Neither
  reads `isSparse` -- both use only `worktree.path` -- so the distro would buy
  them nothing they consume, while resolving a project runtime inside the
  filesystem-auth rebuild would put a call that throws on `repair-required`
  behind a catch that skips the whole repo's authorized roots. The cache key
  makes their reads harmless; skipping the annotation for callers that never
  read it is a separate, larger change. The third no-options call in
  `hosted-review.ts` is inside the `repo.connectionId` branch and returns
  through the SSH provider, so it never reaches this cache.
2026-09-01 04:25:19 -07:00

238 lines
9.5 KiB
TypeScript

import { readFile, stat } from 'node:fs/promises'
import * as path from 'node:path'
import { resolveWorktreeHostPath } from '../../../shared/git-metadata-path'
import type { GitRuntimeOptions } from '../git-runtime-options'
import { resolveGitDir } from './resolve-git-dir'
/**
* Subprocess-free proof of every input one working-tree file diff is built from:
* the HEAD tree, the index, `.gitmodules` (which decides submodule routing) and
* the working-tree file itself.
*
* Two equal stamps mean `git show HEAD:<path>`, `git show :<path>` and the
* working-tree bytes would still return what they returned when the stamp was
* taken, so a caller may reuse a settled diff instead of respawning Git — on a
* WSL/UNC worktree that trades two `wsl.exe` spawns for a handful of 9p stats.
*
* `null` means "cannot prove unchanged" — not a repo, an unreadable layout, or a
* filesystem that reports no usable mtime — and callers must not cache.
*/
export type WorktreeDiffStamp = {
/** Opaque; compare for equality only. */
value: string
/** Newest mtime any component reported, or -Infinity when every one was absent. */
newestMtimeMs: number
capturedAtMs: number
}
/**
* How long after a component's mtime the stamp has to be taken before a later
* write is guaranteed to move that mtime.
*
* Why 2s: FAT/exFAT truncate mtime to a 2s bucket, the coarsest granularity a
* repo can realistically sit on. Below the margin a second write inside the same
* bucket would leave the stamp identical, so the read stays uncached instead.
*/
export const DIFF_STAMP_RACY_WRITE_MARGIN_MS = 2_000
const MISSING = '-'
const ABSENT: StampComponent = { text: MISSING, mtimeMs: Number.NEGATIVE_INFINITY }
type StampComponent = { text: string; mtimeMs: number }
/**
* A write that lands in the same timestamp bucket as the stamp is invisible, so
* only a stamp taken a full bucket after its newest component can be trusted.
*
* The margin compares two clocks: `capturedAtMs` is this host's, while the mtimes
* come from whatever wrote the files. On a `\\wsl.localhost` worktree the guest
* sets them, and a guest running ahead pushes every recently-touched file past the
* margin — silently, and for as long as the skew lasts. `isDiffStampClockSkewed`
* separates that from an honestly-too-fresh file so the caller can count it.
*/
export function canProveUnchangedByStamp(stamp: WorktreeDiffStamp): boolean {
return stamp.capturedAtMs - stamp.newestMtimeMs >= DIFF_STAMP_RACY_WRITE_MARGIN_MS
}
/**
* True when a component's mtime is in this host's future, which no local write can
* produce — so the margin above is measuring skew, not freshness, and will keep
* refusing to store until the clocks converge.
*/
export function isDiffStampClockSkewed(stamp: WorktreeDiffStamp): boolean {
return Number.isFinite(stamp.newestMtimeMs) && stamp.newestMtimeMs > stamp.capturedAtMs
}
/**
* Stamp the inputs of one file diff. Pass `includeWorkingTree: false` for a
* staged diff, which compares HEAD to the index and never reads the working tree.
*/
export async function readWorktreeDiffStamp(
worktreePath: string,
filePath: string,
includeWorkingTree: boolean,
options: Pick<GitRuntimeOptions, 'wslDistro'> = {}
): Promise<WorktreeDiffStamp | null> {
const capturedAtMs = Date.now()
try {
// Git can run in the distro against a raw Linux worktree path while Node stats it through Win32.
const hostWorktreePath = resolveWorktreeHostPath(worktreePath, options)
if (!hostWorktreePath) {
// Only an empty worktree path lands here, and nothing about it is provably unchanged.
return null
}
// Why still pass options: the host spelling above only encodes the distro when it lands on a
// UNC share, so a drvfs-spelled worktree needs it again to resolve a non-drvfs gitdir pointer.
const gitDir = await resolveGitDir(hostWorktreePath, options)
const [head, index, gitmodules, workingTree] = await Promise.all([
readHeadComponent(gitDir),
// Over-invalidates on purpose: git run outside Orca (a terminal `git status`/`git add`)
// can refresh a stat-dirty index and rewrite this file without changing a single blob,
// which costs one re-read. That is the safe direction — do not "fix" it by dropping the
// index from the stamp, because `git add` then becomes invisible and the cache serves a
// pre-staging diff.
readFileStampComponent(path.join(gitDir, 'index')),
readFileStampComponent(path.join(hostWorktreePath, '.gitmodules')),
includeWorkingTree
? readWorkingTreeComponent(path.join(hostWorktreePath, filePath))
: Promise.resolve(ABSENT)
])
if (!head) {
return null
}
const components = [head, index, gitmodules, workingTree]
return {
// Why JSON: a path or a ref can contain any separator character, and an ambiguous
// join is a stamp collision — two different states that compare equal.
value: JSON.stringify([
worktreePath,
filePath,
...components.map((component) => component.text)
]),
newestMtimeMs: Math.max(...components.map((component) => component.mtimeMs)),
capturedAtMs
}
} catch {
return null
}
}
/**
* Identify the commit HEAD resolves to. Reading the tip is what makes a plain
* commit visible: it rewrites `refs/heads/<branch>` and leaves HEAD untouched.
*
* A loose tip is recorded by content, so it needs no mtime margin. Only when no
* loose ref exists at all — packed refs, the reftable backend, or an unborn
* branch — does this fall back to the coarser stamps of the files a packed tip
* moves, and the recorded "no loose ref" marker still catches the ref appearing.
*/
async function readHeadComponent(gitDir: string): Promise<StampComponent | null> {
const [head, commonDirEntry] = await Promise.all([
readTrimmedFile(path.join(gitDir, 'HEAD')),
readTrimmedFile(path.join(gitDir, 'commondir'))
])
if (!head) {
return null
}
const commonDir = commonDirEntry ? path.resolve(gitDir, commonDirEntry) : gitDir
const refName = head.match(/^ref:\s*(.+?)\s*$/)?.[1]
if (!refName || !isSafeRefName(refName)) {
// Detached HEAD already holds the object id; an unrecognized HEAD is covered by its own text.
return { text: head, mtimeMs: Number.NEGATIVE_INFINITY }
}
// Per-worktree refs (`refs/bisect`, `refs/worktree`) live beside the checkout; branches are shared.
const [perWorktreeTip, sharedTip] = await Promise.all([
readTrimmedFile(path.join(gitDir, refName)),
commonDir === gitDir ? Promise.resolve(null) : readTrimmedFile(path.join(commonDir, refName))
])
const looseTip = perWorktreeTip ?? sharedTip
if (looseTip) {
// A loose ref shadows any packed entry, so its bytes settle the tip on their own.
return {
text: JSON.stringify([head, 'loose', perWorktreeTip ? 'worktree' : 'common', looseTip]),
mtimeMs: Number.NEGATIVE_INFINITY
}
}
const [packedRefs, reftable] = await Promise.all([
readFileStampComponent(path.join(commonDir, 'packed-refs')),
readFileStampComponent(path.join(commonDir, 'reftable'))
])
return {
text: JSON.stringify([head, 'packed', packedRefs.text, reftable.text]),
mtimeMs: Math.max(packedRefs.mtimeMs, reftable.mtimeMs)
}
}
/** Keep a hand-edited HEAD from steering the stamp outside the repo's ref store. */
function isSafeRefName(refName: string): boolean {
const segments = refName.split(/[\\/]/)
return (
segments[0] === 'refs' &&
segments.length > 1 &&
segments.every((segment) => segment.length > 0 && segment !== '.' && segment !== '..') &&
!path.isAbsolute(refName)
)
}
async function readTrimmedFile(filePath: string): Promise<string | null> {
try {
const trimmed = (await readFile(filePath, 'utf-8')).trim()
return trimmed.length > 0 ? trimmed : null
} catch (error) {
if (isMissingEntryError(error)) {
return null
}
throw error
}
}
async function readFileStampComponent(filePath: string): Promise<StampComponent> {
try {
const stats = await stat(filePath)
return { text: `${requireMtimeMs(stats.mtimeMs)}:${stats.size}`, mtimeMs: stats.mtimeMs }
} catch (error) {
if (isMissingEntryError(error)) {
return ABSENT
}
throw error
}
}
async function readWorkingTreeComponent(filePath: string): Promise<StampComponent> {
try {
const stats = await stat(filePath)
// Why ino is optional: an atomic-rename save can keep both the size and the mtime bucket,
// so a changed inode is extra proof — but Windows reports 0 for it on the network
// redirector behind `\\wsl.localhost`, and requiring an unstable 0 to match would make
// the stamp never hit on exactly the host this cache exists for. Fold it in only when
// the filesystem gives a real one.
const inode = isUsableInode(stats.ino) ? String(stats.ino) : MISSING
return {
text: `${requireMtimeMs(stats.mtimeMs)}:${stats.size}:${inode}`,
mtimeMs: stats.mtimeMs
}
} catch (error) {
if (isMissingEntryError(error)) {
return ABSENT
}
throw error
}
}
function isUsableInode(ino: unknown): boolean {
return typeof ino === 'number' && Number.isFinite(ino) && ino !== 0
}
/** A filesystem (or a stub) that reports no usable mtime cannot prove anything unchanged. */
function requireMtimeMs(mtimeMs: unknown): number {
if (typeof mtimeMs !== 'number' || !Number.isFinite(mtimeMs)) {
throw new Error('stat reported no usable mtime')
}
return mtimeMs
}
function isMissingEntryError(error: unknown): boolean {
const code = (error as NodeJS.ErrnoException | null)?.code
return code === 'ENOENT' || code === 'ENOTDIR'
}