The best way to control Claude Code, Codex and more from any computer or phone
perf(server): macOS worktrees open 2x faster by cloning a cached checkout (#32927)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Theo Browne committed
Nov 8, 2026 at 16:13 UTC
b7d33af938c92e00f24d5de94f1ae8e5806184ec
19 files changed
+1766
-27
apps/mobile/src/features/settings/ThreadSettingsSections.tsx
+44
-14
@@ -9,6 +9,7 @@ import { AutoSettleDaysField } from "./components/AutoSettleDaysField";
9
import { ScreenScrollView as ScrollView } from "../../components/ui/ScreenScrollView";
10
import { useAtomSet, useAtomValue } from "@effect/atom-react";
11
import { AsyncResult } from "effect/reactivity";
12
+import type { ComponentProps } from "react";
13
import { View } from "react-native";
14
import { useSafeAreaInsets } from "react-native-safe-area-context";
15
@@ -45,7 +46,20 @@ export function SettingsLabsRouteScreen() {
46
contentContainerStyle={{ paddingBottom: Math.max(insets.bottom, 18) + 18 }}
47
>
48
<ToolCallVisibilitySection />
48
- <BetaSettingsSection />
49
+ <MachineBetaSection
50
+ title="Linked environments"
51
+ icon="link"
52
+ capability="peerLinks"
53
+ setting="linkedEnvironmentsEnabled"
54
+ description="Let agents on a machine work on your other machines, and theirs on it. Turn it on for each machine. While off, nothing new starts over a link; running tasks finish."
55
+ />
56
+ <MachineBetaSection
57
+ title="Fast worktree checkout"
58
+ icon="bolt.circle"
59
+ capability="fastWorktreeCheckout"
60
+ setting="fastWorktreeCheckout"
61
+ description="On a Mac, clone new worktrees from a checkout cached in the T3 home folder instead of writing every file. Uses Git’s normal checkout when it can’t. Turning it off deletes the cache."
62
+ />
63
<LegacySettingsSection />
64
</ScrollView>
65
</SettingsScreen>
@@ -228,48 +242,64 @@ export function NewThreadSettingsSection() {
242
);
243
}
244
231
-/** Per machine, since each machine's own setting decides whether it links and answers links. */
232
-function BetaSettingsSection() {
245
+type MachineBetaSetting = "linkedEnvironmentsEnabled" | "fastWorktreeCheckout";
246
+
247
+/** One switch per connected machine that offers the beta, since each machine's own setting decides. */
248
+function MachineBetaSection({
249
+ title,
250
+ icon,
251
+ capability,
252
+ setting,
253
+ description,
254
+}: {
255
+ readonly title: string;
256
+ readonly icon: ComponentProps<typeof SettingsSwitchRow>["icon"];
257
+ readonly capability: "peerLinks" | "fastWorktreeCheckout";
258
+ readonly setting: MachineBetaSetting;
259
+ readonly description: string;
260
+}) {
261
const { environments } = useEnvironments();
262
const supported = environments.filter(
263
(environment) =>
264
environment.connection.phase === "connected" &&
237
- environment.serverConfig?.environment.capabilities.peerLinks === true,
265
+ environment.serverConfig?.environment.capabilities[capability] === true,
266
);
267
const writable = useEnvironmentsWithScope(supported, AuthSettingsWriteScope);
268
const updateSettings = useAtomCommand(serverEnvironment.updateSettings, {
241
- label: "linked environments beta update",
269
+ label: `${setting} beta update`,
270
reportFailure: true,
271
});
272
if (supported.length === 0) return null;
273
return (
274
<View className="gap-3">
247
- <SettingsSection title="Beta: Linked environments">
275
+ <SettingsSection title={`Beta: ${title}`}>
276
{supported.map((environment) => {
277
const policy = environment.serverConfig?.managedPolicy;
250
- const managed = isManagedSettingPath(policy, "linkedEnvironmentsEnabled");
278
+ const managed = isManagedSettingPath(policy, setting);
279
return (
280
<SettingsSwitchRow
281
key={environment.environmentId}
254
- icon="link"
282
+ icon={icon}
283
label={environment.label}
284
{...(managed ? { subtitle: `Managed by ${policy?.organization}.` } : {})}
257
- value={environment.serverConfig?.settings.linkedEnvironmentsEnabled === true}
285
+ value={environment.serverConfig?.settings[setting] === true}
286
disabled={managed || !writable.has(environment.environmentId)}
287
onValueChange={(value) =>
288
void updateSettings({
289
environmentId: environment.environmentId,
262
- input: { patch: { linkedEnvironmentsEnabled: value } },
290
+ input: {
291
+ patch:
292
+ setting === "linkedEnvironmentsEnabled"
293
+ ? { linkedEnvironmentsEnabled: value }
294
+ : { fastWorktreeCheckout: value },
295
+ },
296
})
297
}
298
/>
299
);
300
})}
301
</SettingsSection>
269
- <Text className="px-2 text-sm text-foreground-muted">
270
- Let agents on a machine work on your other machines, and theirs on it. Turn it on for each
271
- machine. While off, nothing new starts over a link; running tasks finish.
272
- </Text>
302
+ <Text className="px-2 text-sm text-foreground-muted">{description}</Text>
303
</View>
304
);
305
}
apps/mobile/src/features/settings/settings-search.ts
+2
@@ -104,6 +104,8 @@ const SETTINGS_SEARCH_TERMS = {
104
"beta",
105
"linked environments",
106
"link machine",
107
+ "fast worktree checkout",
108
+ "clone cache",
109
"tool calls in chat",
110
"hide tool calls",
111
"commands edits searches",
apps/server/src/config.ts
+2
@@ -42,6 +42,7 @@ export interface ServerDerivedPaths {
42
readonly environmentThemesDir: string;
43
readonly providerStatusCacheDir: string;
44
readonly worktreesDir: string;
45
+ readonly worktreeCheckoutCacheDir: string;
46
readonly attachmentsDir: string;
47
readonly browserArtifactsDir: string;
48
readonly logsDir: string;
@@ -158,6 +159,7 @@ export const deriveServerPaths = Effect.fn(function* (
159
environmentThemesDir: join(stateDir, "themes"),
160
providerStatusCacheDir,
161
worktreesDir: join(baseDir, "worktrees"),
162
+ worktreeCheckoutCacheDir: join(providerStatusCacheDir, "worktree-checkouts"),
163
attachmentsDir,
164
browserArtifactsDir: join(stateDir, "browser-artifacts"),
165
logsDir,
apps/server/src/environment/ServerEnvironment.ts
+1
@@ -239,6 +239,7 @@ export const make = Effect.gen(function* () {
239
projectWorktreeCleanup: true,
240
settledWorktreeCleanup: true,
241
worktreesDirectory: true,
242
+ ...(hostPlatform === "darwin" ? { fastWorktreeCheckout: true } : {}),
243
threadAutoSettlementScope: true,
244
threadRestartContinuation: true,
245
projectSettingsOverrides: true,
apps/server/src/git/GitManager.ts
+16
-6
@@ -750,9 +750,20 @@ export const make = Effect.gen(function* () {
750
}
751
return result;
752
});
753
- const readWorktreesDirectory = serverSettingsService.getSettings.pipe(
754
- Effect.map((settings) => settings.worktreesDirectory),
755
- Effect.orElseSucceed(() => ""),
753
+ const readWorktreeCreationSettings = serverSettingsService.getSettings.pipe(
754
+ Effect.map((settings) => ({
755
+ worktreesDirectory: settings.worktreesDirectory,
756
+ fastCheckout: settings.fastWorktreeCheckout,
757
+ })),
758
+ Effect.orElseSucceed(() => ({ worktreesDirectory: "" })),
759
+ );
760
+ // Turning fast checkout off deletes its cache right away, not at the next worktree.
761
+ yield* serverSettingsService.streamChanges.pipe(
762
+ Stream.map((settings) => settings.fastWorktreeCheckout),
763
+ Stream.changes,
764
+ Stream.filter((enabled) => !enabled),
765
+ Stream.runForEach(() => gitCore.clearWorktreeCheckoutCache),
766
+ Effect.forkScoped,
767
);
768
const createWorktree: GitManager["Service"]["createWorktree"] = Effect.fn(
769
"GitManager.createWorktree",
@@ -764,9 +775,8 @@ export const make = Effect.gen(function* () {
775
Effect.map(({ settings }) => settings.worktreeSubmodules),
776
Effect.orElseSucceed(() => null),
777
);
767
- const worktreesDirectory = yield* readWorktreesDirectory;
778
const result = yield* gitCore.createWorktree(input, {
769
- worktreesDirectory,
779
+ ...(yield* readWorktreeCreationSettings),
780
...options,
781
submodules,
782
});
@@ -3075,7 +3085,7 @@ export const make = Effect.gen(function* () {
3085
path: null,
3086
},
3087
{
3078
- worktreesDirectory: yield* readWorktreesDirectory,
3088
+ ...(yield* readWorktreeCreationSettings),
3089
submodules: yield* projectSettingsFor(input).pipe(
3090
Effect.map(({ settings }) => settings.worktreeSubmodules),
3091
Effect.orElseSucceed(() => null),
apps/server/src/orchestration-v2/testkit/ProviderReplayHarness.ts
+1
@@ -147,6 +147,7 @@ export function makeReplayServerConfig(
147
settingsPath: path.join(stateDir, "settings.json"),
148
providerStatusCacheDir,
149
worktreesDir,
150
+ worktreeCheckoutCacheDir: path.join(providerStatusCacheDir, "worktree-checkouts"),
151
attachmentsDir,
152
browserArtifactsDir: path.join(stateDir, "browser-artifacts"),
153
environmentThemesDir,
apps/server/src/vcs/CheckoutCloner.ts
new
+81
@@ -0,0 +1,81 @@
1
+import * as NodeModule from "node:module";
2
+
3
+import * as HostProcess from "@t3tools/shared/HostProcess";
4
+import * as Context from "effect/Context";
5
+import * as Effect from "effect/Effect";
6
+import * as Layer from "effect/Layer";
7
+import * as Schema from "effect/Schema";
8
+
9
+export class CheckoutCloneError extends Schema.TaggedError<CheckoutCloneError>()(
10
+ "CheckoutCloneError",
11
+ {
12
+ source: Schema.String,
13
+ destination: Schema.String,
14
+ errno: Schema.optional(Schema.Number),
15
+ cause: Schema.optional(Schema.Defect()),
16
+ },
17
+) {
18
+ override get message(): string {
19
+ return `Could not clone ${this.source} to ${this.destination}${this.errno === undefined ? "" : ` (errno ${this.errno})`}.`;
20
+ }
21
+}
22
+
23
+/**
24
+ * Copies a file or a whole folder copy-on-write in one call, sharing data blocks until either
25
+ * copy changes. The destination must not exist. Undefined where the platform has no such call.
26
+ */
27
+export const CheckoutCloner = Context.Reference<
28
+ ((source: string, destination: string) => Effect.Effect<void, CheckoutCloneError>) | undefined
29
+>("t3/vcs/CheckoutCloner", { defaultValue: () => undefined });
30
+
31
+// A single-executable server resolves packages on disk only through `require`.
32
+const requireForFfi = NodeModule.createRequire(import.meta.url);
33
+
34
+/** macOS `clonefile(2)`, which clones a folder hierarchy in the kernel; elsewhere nothing. */
35
+export const layer = Layer.effect(
36
+ CheckoutCloner,
37
+ Effect.gen(function* () {
38
+ if ((yield* HostProcess.Platform) !== "darwin") return undefined;
39
+ const loadClonefile = yield* Effect.cached(
40
+ Effect.try({
41
+ try: () => {
42
+ const { DataType, load, open } = requireForFfi("ffi-rs") as typeof import("ffi-rs");
43
+ open({ library: "t3-libsystem", path: "/usr/lib/libSystem.B.dylib" });
44
+ return (source: string, destination: string) =>
45
+ load({
46
+ library: "t3-libsystem",
47
+ funcName: "clonefile",
48
+ retType: DataType.I32,
49
+ paramsType: [DataType.String, DataType.String, DataType.I32],
50
+ // CLONE_NOFOLLOW: clone a symlink itself rather than its target.
51
+ paramsValue: [source, destination, 0x0001],
52
+ errno: true,
53
+ // A large folder takes hundreds of milliseconds; keep it off the event loop.
54
+ runInNewThread: true,
55
+ });
56
+ },
57
+ catch: (cause) =>
58
+ new CheckoutCloneError({ source: "ffi-rs", destination: "clonefile", cause }),
59
+ }),
60
+ );
61
+ return Effect.fn("CheckoutCloner.clonefile")(function* (source: string, destination: string) {
62
+ const clonefile = yield* loadClonefile.pipe(
63
+ Effect.mapError(
64
+ (error) => new CheckoutCloneError({ source, destination, cause: error.cause }),
65
+ ),
66
+ );
67
+ const result = yield* Effect.tryPromise({
68
+ try: () => clonefile(source, destination),
69
+ catch: (cause) => new CheckoutCloneError({ source, destination, cause }),
70
+ });
71
+ // ffi-rs types the errno form as a union with the plain return value.
72
+ if (typeof result === "number" || result.value !== 0) {
73
+ return yield* new CheckoutCloneError({
74
+ source,
75
+ destination,
76
+ ...(typeof result === "number" ? {} : { errno: result.errnoCode }),
77
+ });
78
+ }
79
+ });
80
+ }),
81
+);
apps/server/src/vcs/GitVcsDriver.ts
+6
-1
@@ -42,6 +42,7 @@ import {
42
PATCH_RENDER_PREFIX_ARGS,
43
splitNullSeparatedGitStdoutPaths,
44
} from "./GitVcsDriverCore.ts";
45
+import * as CheckoutCloner from "./CheckoutCloner.ts";
46
import * as VcsDriver from "./VcsDriver.ts";
47
import * as VcsProcess from "./VcsProcess.ts";
48
@@ -144,6 +145,8 @@ export interface CreateWorktreeOptions {
145
/** Null or omitted defers to the checkout's t3.json. */
146
readonly submodules?: WorktreeSubmodules | null;
147
readonly worktreesDirectory?: string;
148
+ /** Clone the checkout from the macOS worktree checkout cache. */
149
+ readonly fastCheckout?: boolean;
150
}
151
152
export interface GitCommitProgress {
@@ -373,6 +376,8 @@ export class GitVcsDriver extends Context.Service<
376
input: VcsCreateWorktreeInput,
377
options?: CreateWorktreeOptions,
378
) => Effect.Effect<VcsCreateWorktreeResult, GitCommandError>;
379
+ /** Deletes the macOS worktree checkout cache in the background. */
380
+ readonly clearWorktreeCheckoutCache: Effect.Effect<void>;
381
/** Force-updates local `branch` to the primary remote's `ref`. */
382
readonly fetchRefIntoBranch: (
383
input: GitFetchRefInput & { readonly branch: string },
@@ -1594,4 +1599,4 @@ export const make = Effect.gen(function* () {
1599
});
1600
1601
export const layerVcs = Layer.effect(VcsDriver.VcsDriver, makeVcsDriver);
1597
-export const layer = Layer.effect(GitVcsDriver, make);
1602
+export const layer = Layer.effect(GitVcsDriver, make).pipe(Layer.provide(CheckoutCloner.layer));
apps/server/src/vcs/GitVcsDriverCore.ts
+31
-4
@@ -43,6 +43,7 @@ import { gitCommandDuration, gitCommandsTotal, withMetrics } from "../observabil
43
import * as GitVcsDriver from "./GitVcsDriver.ts";
44
import { removeEmptyDirectory, type RemoveEmptyDirectoryError } from "./removeEmptyDirectory.ts";
45
import { explicitBareRepositoryEnv, gitConfigEnv } from "./VcsProcess.ts";
46
+import { makeWorktreeCheckoutCache } from "./worktreeCheckoutCache.ts";
47
import { removeLinkedWorktree } from "./worktreeRemoval.ts";
48
import { resolveWorktreesDirectory } from "../worktreesDirectory.ts";
49
import {
@@ -945,7 +946,7 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
946
const fileSystem = yield* FileSystem.FileSystem;
947
const path = yield* Path.Path;
948
const commandSpawner = yield* ChildProcessSpawner.ChildProcessSpawner;
948
- const { worktreesDir } = yield* ServerConfig.ServerConfig;
949
+ const { worktreesDir, worktreeCheckoutCacheDir } = yield* ServerConfig.ServerConfig;
950
const isServerInternalPath = yield* makeIsServerInternalPath;
951
const digest = yield* Digest.Digest;
952
const hostPlatform = yield* HostProcess.Platform;
@@ -1143,6 +1144,11 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
1144
input.writesSharedConfig ? withSharedConfigLock(input.cwd, execution) : execution,
1145
);
1146
1147
+ const checkoutCache = yield* makeWorktreeCheckoutCache({
1148
+ cacheDir: worktreeCheckoutCacheDir,
1149
+ execute,
1150
+ });
1151
+
1152
const executeGit = (
1153
operation: string,
1154
cwd: string,
@@ -4259,7 +4265,7 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
4265
"git worktree add failed",
4266
);
4267
}
4262
- const args = ["worktree", "add", "--", worktreePath, newRefName ?? input.refName];
4268
+ const checkoutRef = newRefName ?? input.refName;
4269
const progress = options?.progress;
4270
const onCheckoutProgress = progress?.onCheckoutProgress;
4271
@@ -4274,10 +4280,20 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
4280
{ concurrency: "unbounded" },
4281
);
4282
const checkoutWorkers = configuredCheckoutWorkers ?? "0";
4277
- yield* executeGitWithStableDiagnostics(
4283
+ const fastCheckout = checkoutCache !== undefined && options?.fastCheckout === true;
4284
+ const cacheGeneration = fastCheckout ? yield* checkoutCache.currentGeneration : 0;
4285
+ const stockCheckout = executeGitWithStableDiagnostics(
4286
"GitVcsDriver.createWorktree",
4287
input.cwd,
4280
- ["-c", `checkout.workers=${checkoutWorkers}`, ...args],
4288
+ [
4289
+ "-c",
4290
+ `checkout.workers=${checkoutWorkers}`,
4291
+ "worktree",
4292
+ "add",
4293
+ "--",
4294
+ worktreePath,
4295
+ checkoutRef,
4296
+ ],
4297
{
4298
fallbackErrorDetail: "git worktree add failed",
4299
// Large checkouts and post-checkout hooks can legitimately run for many
@@ -4297,6 +4313,13 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
4313
}
4314
: {}),
4315
},
4316
+ );
4317
+ yield* (
4318
+ fastCheckout
4319
+ ? checkoutCache
4320
+ .create({ cwd: input.cwd, worktreePath, refName: checkoutRef, checkoutWorkers })
4321
+ .pipe(Effect.flatMap((cloned) => (cloned ? Effect.void : stockCheckout)))
4322
+ : stockCheckout
4323
).pipe(
4324
Effect.onError(() =>
4325
newRefName
@@ -4308,6 +4331,9 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
4331
: Effect.void,
4332
),
4333
);
4334
+ if (fastCheckout) {
4335
+ yield* checkoutCache.schedule(worktreePath, cacheGeneration);
4336
+ }
4337
4338
if (progress?.onWorktreeClaimed) {
4339
yield* progress.onWorktreeClaimed(worktreePath);
@@ -5097,6 +5123,7 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
5123
Effect.ensuring(invalidateWorktreeCreationCaches(input.cwd)),
5124
);
5125
}),
5126
+ clearWorktreeCheckoutCache: checkoutCache?.clear ?? Effect.void,
5127
fetchRefIntoBranch: Effect.fnUntraced(function* (input) {
5128
return yield* withListRefsInvalidation(input.cwd, fetchRefIntoBranch(input));
5129
}),
apps/server/src/vcs/gitIndexStat.test.ts
new
+130
@@ -0,0 +1,130 @@
1
+// @effect-diagnostics nodeBuiltinImport:off - Fixtures drive git and cp directly and read raw stat data.
2
+import * as NodeChildProcess from "node:child_process";
3
+import * as NodeFS from "node:fs";
4
+import * as NodeOS from "node:os";
5
+import * as NodePath from "node:path";
6
+
7
+import { assert, describe, it } from "@effect/vitest";
8
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
9
+import * as Effect from "effect/Effect";
10
+
11
+import { indexEntryStat, parseIndex, restatIndex } from "./gitIndexStat.ts";
12
+
13
+const git = (cwd: string, args: ReadonlyArray<string>, env: NodeJS.ProcessEnv = {}) =>
14
+ NodeChildProcess.execFileSync("git", args, {
15
+ cwd,
16
+ env: { ...process.env, GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_NOSYSTEM: "1", ...env },
17
+ encoding: "utf8",
18
+ });
19
+
20
+// A repository whose checkout in `source` was written by Git with its own index, then copied
21
+// to `copy` the way a clone would: same contents and mtimes, new inodes and ctimes.
22
+const makeCopiedCheckout = Effect.acquireRelease(
23
+ Effect.sync(() => {
24
+ const root = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "git-index-stat-"));
25
+ const repo = NodePath.join(root, "repo");
26
+ NodeFS.mkdirSync(repo);
27
+ git(repo, ["init", "-q"]);
28
+ git(repo, ["config", "filter.probe.clean", "echo read >> ../clean-runs; cat"]);
29
+ NodeFS.writeFileSync(NodePath.join(repo, ".gitattributes"), "*.txt filter=probe\n");
30
+ NodeFS.mkdirSync(NodePath.join(repo, "nested"));
31
+ NodeFS.writeFileSync(NodePath.join(repo, "a.txt"), "alpha\n");
32
+ NodeFS.writeFileSync(NodePath.join(repo, "nested", "b.txt"), "beta\n");
33
+ NodeFS.writeFileSync(NodePath.join(repo, "run.sh"), "#!/bin/sh\n", { mode: 0o755 });
34
+ NodeFS.symlinkSync("a.txt", NodePath.join(repo, "link"));
35
+ git(repo, ["add", "."]);
36
+ git(repo, ["-c", "user.name=T", "-c", "user.email=t@t", "commit", "-qm", "init"]);
37
+ const tree = git(repo, ["rev-parse", "HEAD^{tree}"]).trim();
38
+ const source = NodePath.join(root, "source");
39
+ const sourceIndex = NodePath.join(root, "source.index");
40
+ NodeFS.mkdirSync(source);
41
+ const env = { GIT_INDEX_FILE: sourceIndex };
42
+ git(
43
+ repo,
44
+ ["-c", "index.version=2", `--work-tree=${source}`, "read-tree", "--reset", "-u", tree],
45
+ env,
46
+ );
47
+ // Old mtimes keep every entry clear of Git's racy-clean re-read.
48
+ for (const name of ["a.txt", "nested/b.txt", "run.sh", ".gitattributes"]) {
49
+ NodeFS.utimesSync(NodePath.join(source, name), 1_000_000, 1_000_000);
50
+ }
51
+ git(
52
+ repo,
53
+ ["-c", "index.version=2", `--work-tree=${source}`, "update-index", "-q", "--refresh"],
54
+ env,
55
+ );
56
+ const copy = NodePath.join(root, "copy");
57
+ NodeChildProcess.execFileSync("cp", ["-a", source, copy]);
58
+ // Setup ran the filter itself; only reads after this point count.
59
+ NodeFS.rmSync(NodePath.join(root, "clean-runs"), { force: true });
60
+ return { root, repo, source, sourceIndex, copy };
61
+ }),
62
+ ({ root }) => Effect.sync(() => NodeFS.rmSync(root, { recursive: true, force: true })),
63
+);
64
+
65
+const statAll = (root: string, paths: ReadonlyArray<string>) =>
66
+ paths.map((entryPath) => {
67
+ try {
68
+ return indexEntryStat(NodeFS.lstatSync(NodePath.join(root, entryPath), { bigint: true }));
69
+ } catch {
70
+ return undefined;
71
+ }
72
+ });
73
+
74
+// The feature is macOS-only; the fixtures need symlinks.
75
+describe.skipIf(!symlinksSupported)("restatIndex", () => {
76
+ it.effect("makes Git trust copied files without reading them", () =>
77
+ Effect.gen(function* () {
78
+ const { root, repo, sourceIndex, copy } = yield* makeCopiedCheckout;
79
+ const parsed = parseIndex(NodeFS.readFileSync(sourceIndex));
80
+ assert.isNotNull(parsed);
81
+ const paths = parsed!.entries.map((entry) => entry.path);
82
+ assert.deepStrictEqual(paths, [".gitattributes", "a.txt", "link", "nested/b.txt", "run.sh"]);
83
+
84
+ const restated = restatIndex(parsed!, statAll(copy, paths), { verify: true });
85
+ assert.isNotNull(restated);
86
+ const copyIndex = NodePath.join(root, "copy.index");
87
+ NodeFS.writeFileSync(copyIndex, restated!);
88
+ const status = git(
89
+ repo,
90
+ [`--work-tree=${copy}`, "status", "--porcelain", "--untracked-files=no"],
91
+ {
92
+ GIT_INDEX_FILE: copyIndex,
93
+ },
94
+ );
95
+ assert.equal(status, "");
96
+ assert.isFalse(NodeFS.existsSync(NodePath.join(root, "clean-runs")));
97
+ }),
98
+ );
99
+
100
+ it.effect("rejects a copy whose file no longer matches what Git recorded", () =>
101
+ Effect.gen(function* () {
102
+ const { sourceIndex, copy } = yield* makeCopiedCheckout;
103
+ const parsed = parseIndex(NodeFS.readFileSync(sourceIndex))!;
104
+ const paths = parsed.entries.map((entry) => entry.path);
105
+ NodeFS.writeFileSync(NodePath.join(copy, "a.txt"), "ALPHA\n");
106
+ assert.isNull(restatIndex(parsed, statAll(copy, paths), { verify: true }));
107
+ assert.isNotNull(restatIndex(parsed, statAll(copy, paths), { verify: false }));
108
+ }),
109
+ );
110
+
111
+ it.effect("rejects two tracked paths that are one file, as on a case-insensitive volume", () =>
112
+ Effect.gen(function* () {
113
+ const { sourceIndex, copy } = yield* makeCopiedCheckout;
114
+ const parsed = parseIndex(NodeFS.readFileSync(sourceIndex))!;
115
+ const paths = parsed.entries.map((entry) => entry.path);
116
+ NodeFS.rmSync(NodePath.join(copy, "nested", "b.txt"));
117
+ NodeFS.linkSync(NodePath.join(copy, "a.txt"), NodePath.join(copy, "nested", "b.txt"));
118
+ assert.isNull(restatIndex(parsed, statAll(copy, paths), { verify: false }));
119
+ }),
120
+ );
121
+
122
+ it.effect("leaves indexes it cannot rewrite safely to Git", () =>
123
+ Effect.gen(function* () {
124
+ const { repo, source, sourceIndex } = yield* makeCopiedCheckout;
125
+ const env = { GIT_INDEX_FILE: sourceIndex };
126
+ git(repo, [`--work-tree=${source}`, "update-index", "--index-version", "4"], env);
127
+ assert.isNull(parseIndex(NodeFS.readFileSync(sourceIndex)));
128
+ }),
129
+ );
130
+});
apps/server/src/vcs/gitIndexStat.ts
new
+190
@@ -0,0 +1,190 @@
1
+// @effect-diagnostics nodeBuiltinImport:off - Pure helpers; the index checksum is SHA-1 over bytes.
2
+import * as NodeCrypto from "node:crypto";
3
+
4
+/** What Git compares in an index entry's stat data. Numbers are already truncated to 32 bits. */
5
+export interface IndexEntryStat {
6
+ readonly ctimeSeconds: number;
7
+ readonly ctimeNanoseconds: number;
8
+ readonly mtimeSeconds: number;
9
+ readonly mtimeNanoseconds: number;
10
+ readonly dev: number;
11
+ readonly ino: number;
12
+ readonly uid: number;
13
+ readonly gid: number;
14
+ readonly size: number;
15
+ readonly kind: "file" | "executable" | "symlink" | "directory" | "other";
16
+}
17
+
18
+export interface ParsedIndex {
19
+ readonly bytes: Uint8Array;
20
+ readonly entries: ReadonlyArray<{ readonly offset: number; readonly path: string }>;
21
+}
22
+
23
+const ENTRY_FIXED_BYTES = 62;
24
+const SHA1_BYTES = 20;
25
+const MODE_TYPE_MASK = 0o170000;
26
+const MODE_REGULAR = 0o100000;
27
+const MODE_SYMLINK = 0o120000;
28
+const MODE_GITLINK = 0o160000;
29
+const FLAG_ASSUME_VALID = 0x8000;
30
+const FLAG_EXTENDED = 0x4000;
31
+const FLAG_STAGE = 0x3000;
32
+const FLAG_NAME_LENGTH = 0x0fff;
33
+const EXTENDED_SKIP_WORKTREE = 0x4000;
34
+// Extensions that let Git trust an entry without checking the file, or that point at another index.
35
+const UNSAFE_EXTENSIONS = new Set(["link", "FSMN", "sdir", "UNTR"]);
36
+
37
+const decoder = new TextDecoder();
38
+
39
+/**
40
+ * Reads a SHA-1 index that T3 wrote itself (versions 2 and 3). Anything else, including
41
+ * conflicts, sparse entries, split indexes and fsmonitor data, returns null so callers use Git.
42
+ */
43
+export function parseIndex(bytes: Uint8Array): ParsedIndex | null {
44
+ if (bytes.length < 12 + SHA1_BYTES) return null;
45
+ const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
46
+ if (decoder.decode(bytes.subarray(0, 4)) !== "DIRC") return null;
47
+ const version = view.getUint32(4);
48
+ if (version !== 2 && version !== 3) return null;
49
+ const expected = NodeCrypto.createHash("sha1")
50
+ .update(bytes.subarray(0, bytes.length - SHA1_BYTES))
51
+ .digest();
52
+ if (!expected.equals(bytes.subarray(bytes.length - SHA1_BYTES))) return null;
53
+
54
+ const count = view.getUint32(8);
55
+ const entries: Array<{ offset: number; path: string }> = [];
56
+ let offset = 12;
57
+ for (let index = 0; index < count; index++) {
58
+ if (offset + ENTRY_FIXED_BYTES > bytes.length - SHA1_BYTES) return null;
59
+ const flags = view.getUint16(offset + 60);
60
+ if (flags & (FLAG_ASSUME_VALID | FLAG_STAGE)) return null;
61
+ let nameStart = offset + ENTRY_FIXED_BYTES;
62
+ if (flags & FLAG_EXTENDED) {
63
+ if (version < 3 || view.getUint16(nameStart) & EXTENDED_SKIP_WORKTREE) return null;
64
+ nameStart += 2;
65
+ }
66
+ const nameLength = flags & FLAG_NAME_LENGTH;
67
+ const nameEnd =
68
+ nameLength < FLAG_NAME_LENGTH ? nameStart + nameLength : bytes.indexOf(0, nameStart);
69
+ if (nameEnd < 0 || bytes[nameEnd] !== 0) return null;
70
+ entries.push({ offset, path: decoder.decode(bytes.subarray(nameStart, nameEnd)) });
71
+ // Entries are NUL-padded to a multiple of eight bytes, with at least one NUL.
72
+ offset += (nameEnd - offset + 8) & ~7;
73
+ }
74
+
75
+ // Extensions follow the entries as a 4-byte signature and a 4-byte length.
76
+ while (offset < bytes.length - SHA1_BYTES) {
77
+ if (offset + 8 > bytes.length - SHA1_BYTES) return null;
78
+ if (UNSAFE_EXTENSIONS.has(decoder.decode(bytes.subarray(offset, offset + 4)))) return null;
79
+ offset += 8 + view.getUint32(offset + 4);
80
+ }
81
+ return offset === bytes.length - SHA1_BYTES ? { bytes, entries } : null;
82
+}
83
+
84
+function kindForMode(mode: number): IndexEntryStat["kind"] {
85
+ switch (mode & MODE_TYPE_MASK) {
86
+ case MODE_REGULAR:
87
+ return mode & 0o111 ? "executable" : "file";
88
+ case MODE_SYMLINK:
89
+ return "symlink";
90
+ case MODE_GITLINK:
91
+ return "directory";
92
+ default:
93
+ return "other";
94
+ }
95
+}
96
+
97
+/**
98
+ * Returns a copy of the index with each entry's stat data replaced by `stats[i]`, so Git trusts
99
+ * files it did not write itself. With `verify`, an entry whose recorded mtime, size or type
100
+ * differs from its file makes the result null: the files no longer match what Git checked out.
101
+ * A missing stat (an uninitialized submodule folder) keeps the entry's recorded data.
102
+ */
103
+export function restatIndex(
104
+ parsed: ParsedIndex,
105
+ stats: ReadonlyArray<IndexEntryStat | undefined>,
106
+ options: { readonly verify: boolean },
107
+): Uint8Array | null {
108
+ const bytes = new Uint8Array(parsed.bytes);
109
+ const view = new DataView(bytes.buffer);
110
+ // Two tracked paths on one file, as on a case-insensitive volume, cannot both match.
111
+ const files = new Set<string>();
112
+ for (const [index, entry] of parsed.entries.entries()) {
113
+ const stat = stats[index];
114
+ const offset = entry.offset;
115
+ const kind = kindForMode(view.getUint32(offset + 24));
116
+ if (stat === undefined) {
117
+ if (kind !== "directory") return null;
118
+ continue;
119
+ }
120
+ if (stat.kind !== kind) return null;
121
+ if (kind !== "directory") {
122
+ const file = `${stat.dev}:${stat.ino}`;
123
+ if (files.has(file)) return null;
124
+ files.add(file);
125
+ }
126
+ if (
127
+ options.verify &&
128
+ kind !== "directory" &&
129
+ (view.getUint32(offset + 8) !== stat.mtimeSeconds ||
130
+ view.getUint32(offset + 12) !== stat.mtimeNanoseconds ||
131
+ view.getUint32(offset + 36) !== stat.size)
132
+ ) {
133
+ return null;
134
+ }
135
+ view.setUint32(offset, stat.ctimeSeconds);
136
+ view.setUint32(offset + 4, stat.ctimeNanoseconds);
137
+ view.setUint32(offset + 8, stat.mtimeSeconds);
138
+ view.setUint32(offset + 12, stat.mtimeNanoseconds);
139
+ view.setUint32(offset + 16, stat.dev);
140
+ view.setUint32(offset + 20, stat.ino);
141
+ view.setUint32(offset + 28, stat.uid);
142
+ view.setUint32(offset + 32, stat.gid);
143
+ view.setUint32(offset + 36, stat.size);
144
+ }
145
+ bytes.set(
146
+ NodeCrypto.createHash("sha1")
147
+ .update(bytes.subarray(0, bytes.length - SHA1_BYTES))
148
+ .digest(),
149
+ bytes.length - SHA1_BYTES,
150
+ );
151
+ return bytes;
152
+}
153
+
154
+const U32 = 0xffff_ffffn;
155
+const BILLION = 1_000_000_000n;
156
+
157
+/** Converts a bigint `lstat` result the way Git does: each field truncated to 32 bits. */
158
+export function indexEntryStat(stat: {
159
+ readonly ctimeNs: bigint;
160
+ readonly mtimeNs: bigint;
161
+ readonly dev: bigint;
162
+ readonly ino: bigint;
163
+ readonly uid: bigint;
164
+ readonly gid: bigint;
165
+ readonly size: bigint;
166
+ readonly mode: bigint;
167
+}): IndexEntryStat {
168
+ const type = Number(stat.mode) & MODE_TYPE_MASK;
169
+ return {
170
+ ctimeSeconds: Number((stat.ctimeNs / BILLION) & U32),
171
+ ctimeNanoseconds: Number(stat.ctimeNs % BILLION),
172
+ mtimeSeconds: Number((stat.mtimeNs / BILLION) & U32),
173
+ mtimeNanoseconds: Number(stat.mtimeNs % BILLION),
174
+ dev: Number(stat.dev & U32),
175
+ ino: Number(stat.ino & U32),
176
+ uid: Number(stat.uid & U32),
177
+ gid: Number(stat.gid & U32),
178
+ size: Number(stat.size & U32),
179
+ kind:
180
+ type === MODE_REGULAR
181
+ ? Number(stat.mode) & 0o111
182
+ ? "executable"
183
+ : "file"
184
+ : type === MODE_SYMLINK
185
+ ? "symlink"
186
+ : type === 0o040000
187
+ ? "directory"
188
+ : "other",
189
+ };
190
+}
apps/server/src/vcs/worktreeCheckoutCache.test.ts
new
+344
@@ -0,0 +1,344 @@
1
+// @effect-diagnostics nodeBuiltinImport:off - Fixtures drive git and cp directly and read raw stat data.
2
+import * as NodeChildProcess from "node:child_process";
3
+import * as NodeFS from "node:fs";
4
+import * as NodePath from "node:path";
5
+
6
+import * as NodeCrypto from "@effect/platform-node/NodeCrypto";
7
+import * as NodeServices from "@effect/platform-node/NodeServices";
8
+import * as HostProcess from "@t3tools/shared/HostProcess";
9
+import { assert, describe, it } from "@effect/vitest";
10
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
11
+import * as Effect from "effect/Effect";
12
+import * as FileSystem from "effect/FileSystem";
13
+import * as Layer from "effect/Layer";
14
+import { ChildProcess, ChildProcessSpawner } from "effect/process";
15
+
16
+import * as ServerConfig from "../config.ts";
17
+import * as CheckoutCloner from "./CheckoutCloner.ts";
18
+import { makeGitVcsDriverCore } from "./GitVcsDriverCore.ts";
19
+import { makeWorktreeCheckoutCache } from "./worktreeCheckoutCache.ts";
20
+
21
+// Tests close their own scope first, so background cache builds finish before the temp folder goes.
22
+const layerTest = ServerConfig.layerTest(process.cwd(), {
23
+ prefix: "t3-worktree-checkout-cache-test-",
24
+}).pipe(Layer.provideMerge(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer)));
25
+
26
+// macOS clones for real; elsewhere `cp -a` stands in, keeping mtimes like a clone does.
27
+const testCloner = Effect.gen(function* () {
28
+ const native = yield* CheckoutCloner.CheckoutCloner.pipe(Effect.provide(CheckoutCloner.layer));
29
+ return (
30
+ native ??
31
+ ((source: string, destination: string) =>
32
+ Effect.try({
33
+ try: () => void NodeChildProcess.execFileSync("cp", ["-a", source, destination]),
34
+ catch: (cause) => new CheckoutCloner.CheckoutCloneError({ source, destination, cause }),
35
+ }))
36
+ );
37
+});
38
+
39
+const sh = (cwd: string, args: ReadonlyArray<string>) =>
40
+ NodeChildProcess.execFileSync("git", args, {
41
+ cwd,
42
+ encoding: "utf8",
43
+ env: { ...process.env, GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_NOSYSTEM: "1" },
44
+ }).trim();
45
+
46
+const setup = Effect.gen(function* () {
47
+ const fileSystem = yield* FileSystem.FileSystem;
48
+ const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "worktree-checkout-cache-" });
49
+ const repo = NodePath.join(root, "repo");
50
+ NodeFS.mkdirSync(repo);
51
+ sh(repo, ["init", "-q", "-b", "main"]);
52
+ sh(repo, ["config", "user.name", "Test"]);
53
+ sh(repo, ["config", "user.email", "test@test.com"]);
54
+ sh(repo, ["config", "filter.probe.smudge", "cat"]);
55
+ sh(repo, ["config", "filter.probe.clean", "cat"]);
56
+ NodeFS.writeFileSync(
57
+ NodePath.join(repo, ".gitattributes"),
58
+ "*.bat text eol=crlf\n*.gen filter=probe\n",
59
+ );
60
+ NodeFS.writeFileSync(NodePath.join(repo, "README.md"), "# test\n");
61
+ NodeFS.writeFileSync(NodePath.join(repo, "run.bat"), "echo hi\r\n");
62
+ NodeFS.mkdirSync(NodePath.join(repo, "src"));
63
+ NodeFS.writeFileSync(NodePath.join(repo, "src", "tool.sh"), "#!/bin/sh\n", { mode: 0o755 });
64
+ NodeFS.symlinkSync("README.md", NodePath.join(repo, "readme-link"));
65
+ sh(repo, ["add", "."]);
66
+ sh(repo, ["commit", "-qm", "initial"]);
67
+
68
+ const spawned: Array<ReadonlyArray<string>> = [];
69
+ const delegate = yield* ChildProcessSpawner.ChildProcessSpawner;
70
+ const spawner = ChildProcessSpawner.make((command) => {
71
+ if (ChildProcess.isStandardCommand(command)) spawned.push(command.args.map(String));
72
+ return delegate.spawn(command);
73
+ });
74
+ const clone = yield* testCloner;
75
+ const provide = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
76
+ effect.pipe(
77
+ Effect.provideService(CheckoutCloner.CheckoutCloner, clone),
78
+ Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
79
+ Effect.provideService(HostProcess.Environment, {
80
+ ...process.env,
81
+ GIT_CONFIG_GLOBAL: "/dev/null",
82
+ GIT_CONFIG_NOSYSTEM: "1",
83
+ }),
84
+ );
85
+ const driver = yield* provide(makeGitVcsDriverCore());
86
+ const { worktreeCheckoutCacheDir } = yield* ServerConfig.ServerConfig;
87
+ const cache = (yield* provide(
88
+ makeWorktreeCheckoutCache({ cacheDir: worktreeCheckoutCacheDir, execute: driver.execute }),
89
+ ))!;
90
+ const create = (name: string, refName = "main", fastCheckout = true) =>
91
+ provide(
92
+ driver.createWorktree(
93
+ { cwd: repo, refName, newRefName: name, path: NodePath.join(root, name) },
94
+ { fastCheckout },
95
+ ),
96
+ ).pipe(Effect.map(({ worktree }) => worktree.path));
97
+ // Whether the last creation of `name` checked out with Git rather than cloning.
98
+ const checkedOutWithGit = (name: string) =>
99
+ spawned.some(
100
+ (args) =>
101
+ args.includes("add") &&
102
+ args.includes(NodePath.join(root, name)) &&
103
+ !args.includes("--no-checkout"),
104
+ );
105
+ return {
106
+ root,
107
+ repo,
108
+ create,
109
+ checkedOutWithGit,
110
+ cacheDir: worktreeCheckoutCacheDir,
111
+ build: (worktreePath: string) => provide(cache.build(worktreePath, 0)),
112
+ };
113
+});
114
+
115
+// Every tracked file and its type, mode and contents, so two checkouts can be compared.
116
+const snapshot = (worktreePath: string) =>
117
+ sh(worktreePath, ["ls-files", "-z"])
118
+ .split("\0")
119
+ .filter(Boolean)
120
+ .map((name) => {
121
+ const file = NodePath.join(worktreePath, name);
122
+ const stat = NodeFS.lstatSync(file);
123
+ return [
124
+ name,
125
+ stat.mode,
126
+ stat.isSymbolicLink() ? NodeFS.readlinkSync(file) : NodeFS.readFileSync(file, "utf8"),
127
+ ];
128
+ });
129
+
130
+// Git's recorded stat data matches each file, so status will not re-read them.
131
+const indexMatchesFiles = (worktreePath: string) => {
132
+ const debug = sh(worktreePath, ["ls-files", "--debug"]);
133
+ for (const block of debug.split(/\n(?=\S)/)) {
134
+ const name = block.split("\n")[0]!;
135
+ const ino = Number(block.match(/ino: (\d+)/)![1]);
136
+ const size = Number(block.match(/size: (\d+)/)![1]);
137
+ const stat = NodeFS.lstatSync(NodePath.join(worktreePath, name), { bigint: true });
138
+ if (ino !== Number(stat.ino & 0xffff_ffffn) || size !== Number(stat.size)) return false;
139
+ }
140
+ return true;
141
+};
142
+
143
+// The feature is macOS-only; the fixtures need symlinks.
144
+describe.skipIf(!symlinksSupported)("worktree checkout cache", () => {
145
+ it.effect("clones a cached checkout that matches what git worktree add writes", () =>
146
+ Effect.gen(function* () {
147
+ const fixture = yield* setup;
148
+ const stock = yield* fixture.create("stock", "main", false);
149
+ yield* fixture.build(stock);
150
+
151
+ const fast = yield* fixture.create("fast");
152
+ assert.isFalse(fixture.checkedOutWithGit("fast"));
153
+ assert.deepStrictEqual(snapshot(fast), snapshot(stock));
154
+ assert.equal(sh(fast, ["status", "--porcelain"]), "");
155
+ assert.equal(sh(fast, ["rev-parse", "--abbrev-ref", "HEAD"]), "fast");
156
+ assert.isTrue(indexMatchesFiles(fast));
157
+ // The clone has its own files: editing one leaves the cache and the other worktree alone.
158
+ NodeFS.writeFileSync(NodePath.join(fast, "README.md"), "changed\n");
159
+ assert.equal(sh(stock, ["status", "--porcelain"]), "");
160
+ }).pipe(Effect.scoped, Effect.provide(layerTest)),
161
+ );
162
+
163
+ it.effect("moves an older cached checkout to the requested commit", () =>
164
+ Effect.gen(function* () {
165
+ const fixture = yield* setup;
166
+ yield* fixture.build(yield* fixture.create("base", "main", false));
167
+ NodeFS.writeFileSync(NodePath.join(fixture.repo, "README.md"), "# newer\n");
168
+ NodeFS.writeFileSync(NodePath.join(fixture.repo, "added.txt"), "new file\n");
169
+ NodeFS.rmSync(NodePath.join(fixture.repo, "run.bat"));
170
+ sh(fixture.repo, ["add", "-A"]);
171
+ sh(fixture.repo, ["commit", "-qm", "newer"]);
172
+
173
+ const fast = yield* fixture.create("fast");
174
+ assert.isFalse(fixture.checkedOutWithGit("fast"));
175
+ const stock = yield* fixture.create("stock", "main", false);
176
+ assert.deepStrictEqual(snapshot(fast), snapshot(stock));
177
+ assert.equal(sh(fast, ["status", "--porcelain"]), "");
178
+ }).pipe(Effect.scoped, Effect.provide(layerTest)),
179
+ );
180
+
181
+ it.effect("caches a far newer commit by moving the older cached checkout", () =>
182
+ Effect.gen(function* () {
183
+ const fixture = yield* setup;
184
+ yield* fixture.build(yield* fixture.create("base", "main", false));
185
+ NodeFS.mkdirSync(NodePath.join(fixture.repo, "many"));
186
+ for (let index = 0; index < 600; index++) {
187
+ NodeFS.writeFileSync(NodePath.join(fixture.repo, "many", `${index}.txt`), `${index}\n`);
188
+ }
189
+ NodeFS.writeFileSync(NodePath.join(fixture.repo, "README.md"), "# newer\n");
190
+ sh(fixture.repo, ["add", "-A"]);
191
+ sh(fixture.repo, ["commit", "-qm", "many files"]);
192
+ const stock = yield* fixture.create("stock", "main", false);
193
+ yield* fixture.build(stock);
194
+
195
+ const fast = yield* fixture.create("fast");
196
+ assert.isFalse(fixture.checkedOutWithGit("fast"));
197
+ assert.deepStrictEqual(snapshot(fast), snapshot(stock));
198
+ assert.equal(sh(fast, ["status", "--porcelain"]), "");
199
+ assert.isTrue(indexMatchesFiles(fast));
200
+ }).pipe(Effect.scoped, Effect.provide(layerTest)),
201
+ );
202
+
203
+ it.effect("runs the post-checkout hook as git worktree add would", () =>
204
+ Effect.gen(function* () {
205
+ const fixture = yield* setup;
206
+ yield* fixture.build(yield* fixture.create("base", "main", false));
207
+ const marker = NodePath.join(fixture.root, "hook-args");
208
+ const hook = NodePath.join(fixture.repo, ".git", "hooks", "post-checkout");
209
+ NodeFS.writeFileSync(hook, `#!/bin/sh\necho "$@" > "${marker}"\n`, { mode: 0o755 });
210
+
211
+ yield* fixture.create("fast");
212
+ assert.isFalse(fixture.checkedOutWithGit("fast"));
213
+ const commit = sh(fixture.repo, ["rev-parse", "main"]);
214
+ assert.equal(NodeFS.readFileSync(marker, "utf8").trim(), `${"0".repeat(40)} ${commit} 1`);
215
+ }).pipe(Effect.scoped, Effect.provide(layerTest)),
216
+ );
217
+
218
+ it.effect("checks out with Git when the checkout adds a post-index-change hook", () =>
219
+ Effect.gen(function* () {
220
+ const fixture = yield* setup;
221
+ const marker = NodePath.join(fixture.root, "index-hook-runs");
222
+ NodeFS.mkdirSync(NodePath.join(fixture.repo, ".hooks"));
223
+ const hook = NodePath.join(fixture.repo, ".hooks", "post-index-change");
224
+ NodeFS.writeFileSync(hook, `#!/bin/sh\necho ran >> "${marker}"\n`);
225
+ sh(fixture.repo, ["add", "--chmod=+x", hook]);
226
+ sh(fixture.repo, ["commit", "-qm", "tracked hooks"]);
227
+ yield* fixture.build(yield* fixture.create("base", "main", false));
228
+ sh(fixture.repo, ["config", "core.hooksPath", ".hooks"]);
229
+ NodeFS.rmSync(marker, { force: true });
230
+
231
+ yield* fixture.create("fallback");
232
+ assert.isTrue(fixture.checkedOutWithGit("fallback"));
233
+ assert.isTrue(NodeFS.existsSync(marker));
234
+ }).pipe(Effect.scoped, Effect.provide(layerTest)),
235
+ );
236
+
237
+ it.effect("clones the branch Git checks out when a tag has the same name", () =>
238
+ Effect.gen(function* () {
239
+ const fixture = yield* setup;
240
+ sh(fixture.repo, ["tag", "fast"]);
241
+ NodeFS.writeFileSync(NodePath.join(fixture.repo, "README.md"), "# newer\n");
242
+ sh(fixture.repo, ["commit", "-qam", "newer"]);
243
+ const stock = yield* fixture.create("stock", "main", false);
244
+ yield* fixture.build(stock);
245
+
246
+ const fast = yield* fixture.create("fast");
247
+ assert.isFalse(fixture.checkedOutWithGit("fast"));
248
+ assert.deepStrictEqual(snapshot(fast), snapshot(stock));
249
+ assert.equal(sh(fast, ["status", "--porcelain"]), "");
250
+ }).pipe(Effect.scoped, Effect.provide(layerTest)),
251
+ );
252
+
253
+ it.effect("does not cache checkouts whose attributes name a filter", () =>
254
+ Effect.gen(function* () {
255
+ const fixture = yield* setup;
256
+ NodeFS.writeFileSync(NodePath.join(fixture.repo, ".gitattributes"), "*.bin filter=lfs\n");
257
+ NodeFS.writeFileSync(NodePath.join(fixture.repo, "asset.bin"), "pointer\n");
258
+ sh(fixture.repo, ["add", "-A"]);
259
+ sh(fixture.repo, ["commit", "-qm", "lfs"]);
260
+ yield* fixture.build(yield* fixture.create("stock", "main", false));
261
+ yield* fixture.create("next");
262
+ assert.isTrue(fixture.checkedOutWithGit("next"));
263
+ }).pipe(Effect.scoped, Effect.provide(layerTest)),
264
+ );
265
+
266
+ const cacheEntry = (fixture: { cacheDir: string }) => {
267
+ const [bucket] = NodeFS.readdirSync(fixture.cacheDir);
268
+ const [entry] = NodeFS.readdirSync(NodePath.join(fixture.cacheDir, bucket!));
269
+ return NodePath.join(fixture.cacheDir, bucket!, entry!, "files");
270
+ };
271
+
272
+ it.effect.each([
273
+ {
274
+ name: "a cached file changed",
275
+ change: (fixture: { cacheDir: string; repo: string; root: string }) =>
276
+ NodeFS.writeFileSync(NodePath.join(cacheEntry(fixture), "README.md"), "tampered with\n"),
277
+ },
278
+ {
279
+ name: "a file was added to the cache",
280
+ change: (fixture: { cacheDir: string; repo: string; root: string }) =>
281
+ NodeFS.writeFileSync(NodePath.join(cacheEntry(fixture), "src", "extra.txt"), "extra\n"),
282
+ },
283
+ {
284
+ name: "the repository's checkout settings changed",
285
+ change: (fixture: { cacheDir: string; repo: string; root: string }) =>
286
+ sh(fixture.repo, ["config", "core.autocrlf", "true"]),
287
+ },
288
+ {
289
+ // Moving the cached checkout forward would keep README.md's old line endings.
290
+ name: "attributes changed since the cached commit",
291
+ change: (fixture: { cacheDir: string; repo: string; root: string }) => {
292
+ NodeFS.appendFileSync(
293
+ NodePath.join(fixture.repo, ".gitattributes"),
294
+ "*.md text eol=crlf\n",
295
+ );
296
+ sh(fixture.repo, ["commit", "-qam", "crlf markdown"]);
297
+ },
298
+ },
299
+ {
300
+ // On a case-insensitive volume the new file would land in the cached `src` folder.
301
+ name: "a new folder's name differs only in case",
302
+ change: (fixture: { cacheDir: string; repo: string; root: string }) => {
303
+ // Plumbing, because a case-insensitive volume cannot hold both folders.
304
+ NodeFS.writeFileSync(NodePath.join(fixture.root, "b.txt"), "b\n");
305
+ const blob = sh(fixture.repo, ["hash-object", "-w", NodePath.join(fixture.root, "b.txt")]);
306
+ sh(fixture.repo, ["update-index", "--add", "--cacheinfo", `100644,${blob},Src/b.txt`]);
307
+ sh(fixture.repo, ["commit", "-qm", "case folder"]);
308
+ },
309
+ },
310
+ {
311
+ // Git would run this hook during its own checkout, with its own environment.
312
+ name: "the move adds a post-index-change hook",
313
+ change: (fixture: { cacheDir: string; repo: string; root: string }) => {
314
+ const hook = NodePath.join(fixture.repo, ".hooks", "post-index-change");
315
+ NodeFS.mkdirSync(NodePath.dirname(hook));
316
+ NodeFS.writeFileSync(hook, "#!/bin/sh\n");
317
+ sh(fixture.repo, ["add", "--chmod=+x", hook]);
318
+ sh(fixture.repo, ["commit", "-qm", "hook"]);
319
+ sh(fixture.repo, ["config", "core.hooksPath", ".hooks"]);
320
+ },
321
+ },
322
+ {
323
+ // The cached tree has the rule but no matching file; the move would run the filter itself.
324
+ name: "the move adds a file that uses a filter",
325
+ change: (fixture: { cacheDir: string; repo: string; root: string }) => {
326
+ NodeFS.writeFileSync(NodePath.join(fixture.repo, "asset.gen"), "generated\n");
327
+ sh(fixture.repo, ["add", "-A"]);
328
+ sh(fixture.repo, ["commit", "-qm", "generated asset"]);
329
+ },
330
+ },
331
+ ])("checks out with Git when $name", ({ change }) =>
332
+ Effect.gen(function* () {
333
+ const fixture = yield* setup;
334
+ yield* fixture.build(yield* fixture.create("base", "main", false));
335
+ change(fixture);
336
+
337
+ const created = yield* fixture.create("fallback");
338
+ assert.isTrue(fixture.checkedOutWithGit("fallback"));
339
+ const stock = yield* fixture.create("stock", "main", false);
340
+ assert.deepStrictEqual(snapshot(created), snapshot(stock));
341
+ assert.equal(sh(created, ["status", "--porcelain"]), "");
342
+ }).pipe(Effect.scoped, Effect.provide(layerTest)),
343
+ );
344
+});
apps/server/src/vcs/worktreeCheckoutCache.ts
new
+845
@@ -0,0 +1,845 @@
1
+// @effect-diagnostics nodeBuiltinImport:off - Git index stat data needs bigint lstat, which FileSystem lacks.
2
+import * as NodeCrypto from "node:crypto";
3
+import * as NodeFSP from "node:fs/promises";
4
+
5
+import { GitCommandError } from "@t3tools/contracts";
6
+import * as HostProcess from "@t3tools/shared/HostProcess";
7
+import * as Clock from "effect/Clock";
8
+import * as Effect from "effect/Effect";
9
+import * as Exit from "effect/Exit";
10
+import * as FileSystem from "effect/FileSystem";
11
+import * as Option from "effect/Option";
12
+import * as Path from "effect/Path";
13
+import * as Schema from "effect/Schema";
14
+import * as Semaphore from "effect/Semaphore";
15
+
16
+import * as CheckoutCloner from "./CheckoutCloner.ts";
17
+import type * as GitVcsDriver from "./GitVcsDriver.ts";
18
+import { indexEntryStat, parseIndex, restatIndex, type IndexEntryStat } from "./gitIndexStat.ts";
19
+
20
+const KEEP_PER_REPOSITORY = 3;
21
+// Moving a cached checkout costs about 0.1 ms per changed file when a worktree is created, while
22
+// replacing it means writing and later deleting a whole checkout, which slows the next clone.
23
+const REBUILD_AFTER_CHANGED_FILES = 500;
24
+const UNUSED_REPOSITORY_MS = 30 * 24 * 60 * 60 * 1000;
25
+// Older leftovers came from a crash, not from work in progress. A full build of a huge repository
26
+// can take minutes, and its staging folder's own mtime does not change while files land inside.
27
+const ABANDONED_STAGING_MS = 24 * 60 * 60 * 1000;
28
+const ABANDONED_TRASH_MS = 10 * 60 * 1000;
29
+const STAT_BATCH = 512;
30
+const TREE_ID = /^[0-9a-f]{40}$/;
31
+// `<tree>-<fingerprint>`: checkouts of one tree under different settings never replace each other.
32
+const ENTRY_NAME = /^([0-9a-f]{40})-([0-9a-f]{16})$/;
33
+const GIT_FALSE = new Set(["false", "no", "off", "0"]);
34
+const MAX_LIST_BYTES = 256 * 1024 * 1024;
35
+const NULL_OID = "0".repeat(40);
36
+// 2.42 names its system attributes file, which the fingerprint needs; `git hook run` is from 2.36.
37
+const MIN_GIT = [2, 42] as const;
38
+// Settings that change what a checkout writes. Read in the new worktree, so conditional includes apply.
39
+const CHECKOUT_CONFIG =
40
+ "^(core\\.(autocrlf|eol|symlinks|safecrlf|checkroundtripencoding|precomposeunicode|ignorecase|filemode|attributesfile|sparsecheckout)|filter\\.|lfs\\.|extensions\\.)";
41
+// Keeps cache indexes in the one format the stat rewriter reads.
42
+const CACHE_INDEX_CONFIG = [
43
+ "index.version=2",
44
+ "index.skipHash=false",
45
+ "core.splitIndex=false",
46
+ "core.untrackedCache=false",
47
+ "core.fsmonitor=false",
48
+ "core.sparseCheckout=false",
49
+ // Private builds must not run the repository's hooks.
50
+ "core.hooksPath=/dev/null",
51
+ "checkout.workers=0",
52
+].flatMap((setting) => ["-c", setting]);
53
+
54
+// How a case- and normalization-insensitive volume such as default APFS compares names.
55
+const foldCase = (file: string) => file.normalize("NFC").toLowerCase();
56
+
57
+// `check-attr --all -z` output: any `filter` attribute counts, as `unset` can also name a driver.
58
+function namesFilter(output: string): boolean {
59
+ const fields = output.split("\0");
60
+ for (let index = 1; index < fields.length; index += 3) {
61
+ if (fields[index] === "filter") return true;
62
+ }
63
+ return false;
64
+}
65
+
66
+/** Every folder that holds one of `paths`, including the root as "". */
67
+function parentDirectories(paths: Iterable<string>): Set<string> {
68
+ const directories = new Set([""]);
69
+ for (const entryPath of paths) {
70
+ for (let slash = entryPath.lastIndexOf("/"); slash > 0;) {
71
+ const directory = entryPath.slice(0, slash);
72
+ if (directories.has(directory)) break;
73
+ directories.add(directory);
74
+ slash = directory.lastIndexOf("/");
75
+ }
76
+ }
77
+ return directories;
78
+}
79
+
80
+class WorktreeCheckoutCacheError extends Schema.TaggedError<WorktreeCheckoutCacheError>()(
81
+ "WorktreeCheckoutCacheError",
82
+ { detail: Schema.String },
83
+) {
84
+ override get message(): string {
85
+ return this.detail;
86
+ }
87
+}
88
+
89
+interface CacheEntry {
90
+ readonly directory: string;
91
+ readonly tree: string;
92
+ readonly fingerprint: string;
93
+ readonly mtimeMs: number;
94
+}
95
+
96
+/**
97
+ * Clones a private, Git-written checkout with APFS copy-on-write, then rewrites the index's stat
98
+ * data so Git trusts the clones without re-reading them. An older cached checkout is moved to the
99
+ * requested tree with `read-tree -m -u`. Undefined where the platform cannot clone a folder.
100
+ */
101
+export const makeWorktreeCheckoutCache = Effect.fn("WorktreeCheckoutCache.make")(function* (input: {
102
+ readonly cacheDir: string;
103
+ readonly execute: GitVcsDriver.GitVcsDriver["Service"]["execute"];
104
+}) {
105
+ const clone = yield* CheckoutCloner.CheckoutCloner;
106
+ if (clone === undefined) return undefined;
107
+ const fileSystem = yield* FileSystem.FileSystem;
108
+ const path = yield* Path.Path;
109
+ const scope = yield* Effect.scope;
110
+ const homeDirectory = yield* HostProcess.HomeDirectory;
111
+ const environment = yield* HostProcess.Environment;
112
+ const builds = yield* Semaphore.make(1);
113
+ const pendingBuilds = new Set<string>();
114
+ // Bumped by `clear`, so a build that started before it does not publish its result.
115
+ let generation = 0;
116
+ const { cacheDir, execute } = input;
117
+
118
+ const git = (
119
+ operation: string,
120
+ cwd: string,
121
+ args: ReadonlyArray<string>,
122
+ env?: NodeJS.ProcessEnv,
123
+ ) =>
124
+ execute({
125
+ operation: `WorktreeCheckoutCache.git.${operation}`,
126
+ cwd,
127
+ args,
128
+ allowNonZeroExit: true,
129
+ timeoutMs: null,
130
+ ...(env ? { env } : {}),
131
+ }).pipe(
132
+ Effect.map((result) => (result.exitCode === 0 ? result.stdout : null)),
133
+ Effect.orElseSucceed(() => null),
134
+ );
135
+
136
+ const gitSupported = yield* Effect.cached(
137
+ git("version", homeDirectory, ["version"]).pipe(
138
+ Effect.map((stdout) => {
139
+ const match = stdout?.match(/git version (\d+)\.(\d+)/);
140
+ if (!match) return false;
141
+ const [major, minor] = [Number(match[1]), Number(match[2])];
142
+ return major > MIN_GIT[0] || (major === MIN_GIT[0] && minor >= MIN_GIT[1]);
143
+ }),
144
+ ),
145
+ );
146
+
147
+ const describe = Effect.fn("WorktreeCheckoutCache.describe")(function* (
148
+ cwd: string,
149
+ rev: string,
150
+ ) {
151
+ const stdout = yield* git("describe", cwd, [
152
+ "rev-parse",
153
+ "--path-format=absolute",
154
+ "--git-common-dir",
155
+ "--show-object-format",
156
+ "--git-path",
157
+ "hooks/post-index-change",
158
+ `${rev}^{commit}`,
159
+ `${rev}^{tree}`,
160
+ ]);
161
+ const [commonDir, objectFormat, indexHook, commit, tree] = stdout?.trim().split("\n") ?? [];
162
+ if (
163
+ !commonDir ||
164
+ objectFormat !== "sha1" ||
165
+ !indexHook ||
166
+ !commit ||
167
+ !tree ||
168
+ !TREE_ID.test(tree)
169
+ ) {
170
+ return null;
171
+ }
172
+ const realCommonDir = yield* fileSystem
173
+ .realPath(commonDir)
174
+ .pipe(Effect.orElseSucceed(() => commonDir));
175
+ const repositoryKey = NodeCrypto.createHash("sha256")
176
+ .update(realCommonDir)
177
+ .digest("hex")
178
+ .slice(0, 16);
179
+ return {
180
+ commonDir,
181
+ commit,
182
+ tree,
183
+ indexHook: path.resolve(cwd, indexHook),
184
+ bucket: path.join(cacheDir, repositoryKey),
185
+ };
186
+ });
187
+
188
+ // Empty when `GIT_ATTR_NOSYSTEM` turns the system attributes file off.
189
+ const systemAttributePaths = yield* Effect.cached(
190
+ git("systemAttributes", homeDirectory, ["var", "GIT_ATTR_SYSTEM"]).pipe(
191
+ Effect.map((stdout) => (stdout?.trim() ? [stdout.trim()] : [])),
192
+ ),
193
+ );
194
+
195
+ // Null for setups the cache cannot reproduce, such as sparse checkouts.
196
+ const fingerprint = Effect.fn("WorktreeCheckoutCache.fingerprint")(function* (
197
+ cwd: string,
198
+ commonDir: string,
199
+ ) {
200
+ const config =
201
+ (yield* git("fingerprint", cwd, ["config", "--null", "--get-regexp", CHECKOUT_CONFIG])) ?? "";
202
+ const pairs = config
203
+ .split("\0")
204
+ .filter(Boolean)
205
+ .map((pair) => {
206
+ const newline = pair.indexOf("\n");
207
+ return newline < 0
208
+ ? ([pair, ""] as const)
209
+ : ([pair.slice(0, newline), pair.slice(newline + 1)] as const);
210
+ });
211
+ const sparse = pairs.findLast(([key]) => key === "core.sparsecheckout")?.[1];
212
+ if (sparse !== undefined && !GIT_FALSE.has(sparse.toLowerCase())) return null;
213
+ const attributesFile = pairs
214
+ .findLast(([key]) => key === "core.attributesfile")?.[1]
215
+ ?.replace(/^~(?=$|\/)/, homeDirectory);
216
+ // Git reads a relative path from each checkout, which differs between the cache and the worktree.
217
+ if (attributesFile !== undefined && !path.isAbsolute(attributesFile)) return null;
218
+ const attributePaths = [
219
+ ...(yield* systemAttributePaths),
220
+ path.join(commonDir, "info", "attributes"),
221
+ attributesFile ??
222
+ path.join(
223
+ environment.XDG_CONFIG_HOME || path.join(homeDirectory, ".config"),
224
+ "git",
225
+ "attributes",
226
+ ),
227
+ ];
228
+ const attributes = yield* Effect.forEach(attributePaths, (file) =>
229
+ fileSystem.readFileString(file).pipe(Effect.orElseSucceed(() => "")),
230
+ );
231
+ const hash = NodeCrypto.createHash("sha256").update(config);
232
+ for (const contents of attributes) hash.update("\0").update(contents);
233
+ return hash.digest("hex").slice(0, 16);
234
+ });
235
+
236
+ const listEntries = Effect.fn("WorktreeCheckoutCache.listEntries")(function* (bucket: string) {
237
+ const names = yield* fileSystem.readDirectory(bucket).pipe(Effect.orElseSucceed(() => []));
238
+ const entries = yield* Effect.forEach(
239
+ names.flatMap((name) => {
240
+ const match = ENTRY_NAME.exec(name);
241
+ return match ? [{ name, tree: match[1]!, fingerprint: match[2]! }] : [];
242
+ }),
243
+ ({ name, tree, fingerprint: entryFingerprint }) => {
244
+ const directory = path.join(bucket, name);
245
+ return fileSystem.stat(directory).pipe(
246
+ Effect.map((info): CacheEntry => ({
247
+ directory,
248
+ tree,
249
+ fingerprint: entryFingerprint,
250
+ mtimeMs: Option.match(info.mtime, {
251
+ onNone: () => 0,
252
+ onSome: (date) => date.getTime(),
253
+ }),
254
+ })),
255
+ Effect.option,
256
+ );
257
+ },
258
+ { concurrency: 8 },
259
+ );
260
+ return entries
261
+ .flatMap((entry) => (entry._tag === "Some" ? [entry.value] : []))
262
+ .toSorted((left, right) => right.mtimeMs - left.mtimeMs);
263
+ });
264
+
265
+ const touch = (target: string) =>
266
+ Clock.currentTimeMillis.pipe(
267
+ Effect.flatMap((now) =>
268
+ Effect.tryPromise({
269
+ try: () => NodeFSP.utimes(target, now / 1000, now / 1000),
270
+ catch: (cause) =>
271
+ new WorktreeCheckoutCacheError({ detail: `could not touch ${target}: ${cause}` }),
272
+ }),
273
+ ),
274
+ Effect.ignore,
275
+ );
276
+
277
+ // Untraced: one stat per tracked file, already covered by the caller's span.
278
+ const statEntries = Effect.fnUntraced(function* (root: string, paths: ReadonlyArray<string>) {
279
+ return yield* Effect.tryPromise({
280
+ try: async () => {
281
+ const stats: Array<IndexEntryStat | undefined> = [];
282
+ for (let start = 0; start < paths.length; start += STAT_BATCH) {
283
+ const batch = await Promise.all(
284
+ paths.slice(start, start + STAT_BATCH).map((entryPath) =>
285
+ NodeFSP.lstat(`${root}/${entryPath}`, { bigint: true }).then(
286
+ indexEntryStat,
287
+ (error) => {
288
+ if (error?.code === "ENOENT") return undefined;
289
+ throw error;
290
+ },
291
+ ),
292
+ ),
293
+ );
294
+ stats.push(...batch);
295
+ }
296
+ return stats;
297
+ },
298
+ catch: (cause) =>
299
+ new WorktreeCheckoutCacheError({ detail: `could not stat ${root}: ${cause}` }),
300
+ });
301
+ });
302
+
303
+ /**
304
+ * Writes `target` from the index at `source` with stat data from the files under `root`, and
305
+ * returns what it read. Null when the index or the files cannot be trusted.
306
+ */
307
+ const restate = Effect.fn("WorktreeCheckoutCache.restate")(function* (input: {
308
+ readonly source: string;
309
+ readonly target: string;
310
+ readonly root: string;
311
+ readonly verify: boolean;
312
+ }) {
313
+ const parsed = parseIndex(yield* fileSystem.readFile(input.source));
314
+ if (parsed === null) return null;
315
+ const paths = parsed.entries.map((entry) => entry.path);
316
+ const stats = yield* statEntries(input.root, paths);
317
+ const restated = restatIndex(parsed, stats, { verify: input.verify });
318
+ if (restated === null) return null;
319
+ const temporary = `${input.target}.t3-${NodeCrypto.randomUUID()}`;
320
+ yield* Effect.uninterruptible(
321
+ fileSystem
322
+ .writeFile(temporary, restated)
323
+ .pipe(Effect.andThen(fileSystem.rename(temporary, input.target))),
324
+ );
325
+ return { paths, stats };
326
+ });
327
+
328
+ // Untraced: one stat per folder, already covered by the caller's span.
329
+ const directoryTimes = Effect.fnUntraced(function* (
330
+ root: string,
331
+ directories: ReadonlyArray<string>,
332
+ ) {
333
+ return yield* Effect.tryPromise({
334
+ try: () =>
335
+ Promise.all(
336
+ directories.map((directory) =>
337
+ NodeFSP.lstat(directory === "" ? root : `${root}/${directory}`, { bigint: true }).then(
338
+ (stat) => String(stat.mtimeNs),
339
+ () => "missing",
340
+ ),
341
+ ),
342
+ ),
343
+ catch: (cause) =>
344
+ new WorktreeCheckoutCacheError({ detail: `could not stat folders in ${root}: ${cause}` }),
345
+ });
346
+ });
347
+
348
+ // Adding or removing a file changes its folder's mtime, so this catches files the index lacks.
349
+ const recordDirectories = Effect.fn("WorktreeCheckoutCache.recordDirectories")(function* (
350
+ entryDirectory: string,
351
+ recorded: {
352
+ readonly paths: ReadonlyArray<string>;
353
+ readonly stats: ReadonlyArray<IndexEntryStat | undefined>;
354
+ },
355
+ ) {
356
+ const directories = parentDirectories(recorded.paths);
357
+ for (const [index, entryPath] of recorded.paths.entries()) {
358
+ if (recorded.stats[index]?.kind === "directory") directories.add(entryPath);
359
+ }
360
+ // Folders whose names differ only in case share one spelling on disk, which depends on history.
361
+ const folded = new Set([...directories].map((directory) => foldCase(directory)));
362
+ if (folded.size !== directories.size) {
363
+ return yield* new WorktreeCheckoutCacheError({ detail: "folder names differ only in case" });
364
+ }
365
+ const list = [...directories];
366
+ // Backdated, so any later change moves the time even on a filesystem with a coarse clock.
367
+ const root = path.join(entryDirectory, "files");
368
+ yield* Effect.tryPromise({
369
+ try: () =>
370
+ Promise.all(
371
+ list.map((directory) =>
372
+ NodeFSP.utimes(directory === "" ? root : `${root}/${directory}`, 1_000_000, 1_000_000),
373
+ ),
374
+ ),
375
+ catch: (cause) =>
376
+ new WorktreeCheckoutCacheError({ detail: `could not backdate cached folders: ${cause}` }),
377
+ });
378
+ const times = yield* directoryTimes(root, list);
379
+ yield* fileSystem.writeFileString(
380
+ path.join(entryDirectory, "directories"),
381
+ list.map((directory, index) => `${times[index]}\0${directory}\0`).join(""),
382
+ );
383
+ });
384
+
385
+ const directoriesUnchanged = Effect.fn("WorktreeCheckoutCache.directoriesUnchanged")(
386
+ function* (entry: CacheEntry) {
387
+ const recorded = (yield* fileSystem.readFileString(path.join(entry.directory, "directories")))
388
+ .split("\0")
389
+ .slice(0, -1);
390
+ const times = recorded.filter((_, index) => index % 2 === 0);
391
+ const directories = recorded.filter((_, index) => index % 2 === 1);
392
+ const current = yield* directoryTimes(path.join(entry.directory, "files"), directories);
393
+ return directories.length > 0 && current.every((time, index) => time === times[index]);
394
+ },
395
+ (effect) => Effect.orElseSucceed(effect, () => false),
396
+ );
397
+
398
+ const changedPaths = Effect.fn("WorktreeCheckoutCache.changedPaths")(function* (
399
+ cwd: string,
400
+ from: string,
401
+ to: string,
402
+ ) {
403
+ const stdout = yield* git("changes", cwd, [
404
+ "diff-tree",
405
+ "-r",
406
+ "-z",
407
+ "--name-status",
408
+ "--no-renames",
409
+ from,
410
+ to,
411
+ ]);
412
+ if (stdout === null) return null;
413
+ const fields = stdout.split("\0");
414
+ const added: Array<string> = [];
415
+ const deleted: Array<string> = [];
416
+ // Added or changed: what `read-tree -m -u` writes itself.
417
+ const written: Array<string> = [];
418
+ let count = 0;
419
+ let attributes = false;
420
+ for (let index = 0; index + 1 < fields.length; index += 2) {
421
+ const [status, file] = [fields[index]!, fields[index + 1]!];
422
+ count++;
423
+ // `read-tree -m -u` leaves unchanged files alone, even when their attributes changed.
424
+ if (file === ".gitattributes" || file.endsWith("/.gitattributes")) attributes = true;
425
+ if (status === "A") added.push(file);
426
+ if (status === "D") deleted.push(file);
427
+ else written.push(file);
428
+ }
429
+ return { count, attributes, added, deleted, written };
430
+ });
431
+
432
+ // A smudge filter's output can depend on the environment and the network, as with Git LFS.
433
+ const usesFilter = Effect.fn("WorktreeCheckoutCache.usesFilter")(function* (
434
+ cwd: string,
435
+ bucket: string,
436
+ tree: string,
437
+ ) {
438
+ // An index of the tree lets `check-attr` read its `.gitattributes` on any Git version.
439
+ const index = path.join(bucket, `.attributes-${NodeCrypto.randomUUID()}`);
440
+ const env = { GIT_INDEX_FILE: index };
441
+ const run = (args: ReadonlyArray<string>, stdin?: string) =>
442
+ execute({
443
+ operation: "WorktreeCheckoutCache.git.filters",
444
+ cwd,
445
+ args,
446
+ env,
447
+ allowNonZeroExit: true,
448
+ maxOutputBytes: MAX_LIST_BYTES,
449
+ ...(stdin === undefined ? {} : { stdin }),
450
+ }).pipe(Effect.map((result) => (result.exitCode === 0 ? result.stdout : null)));
451
+ return yield* Effect.gen(function* () {
452
+ if ((yield* run([...CACHE_INDEX_CONFIG, "read-tree", tree])) === null) return true;
453
+ const files = yield* run(["ls-files", "-z"]);
454
+ if (files === null) return true;
455
+ const output = yield* run(["check-attr", "--cached", "--all", "-z", "--stdin"], files);
456
+ return output === null || namesFilter(output);
457
+ }).pipe(
458
+ Effect.orElseSucceed(() => true),
459
+ Effect.ensuring(fileSystem.remove(index).pipe(Effect.ignore)),
460
+ );
461
+ });
462
+
463
+ // Attributes come from the cloned `.gitattributes` files, which the move leaves unchanged.
464
+ const writesWithFilter = Effect.fn("WorktreeCheckoutCache.writesWithFilter")(function* (
465
+ cwd: string,
466
+ files: ReadonlyArray<string>,
467
+ ) {
468
+ if (files.length === 0) return false;
469
+ const output = yield* execute({
470
+ operation: "WorktreeCheckoutCache.git.filters",
471
+ cwd,
472
+ args: ["check-attr", "--all", "-z", "--stdin"],
473
+ stdin: files.map((file) => `${file}\0`).join(""),
474
+ allowNonZeroExit: true,
475
+ maxOutputBytes: MAX_LIST_BYTES,
476
+ }).pipe(
477
+ Effect.map((result) => (result.exitCode === 0 ? result.stdout : null)),
478
+ Effect.orElseSucceed(() => null),
479
+ );
480
+ return output === null || namesFilter(output);
481
+ });
482
+
483
+ // Renamed first so nothing clones a half-deleted checkout; deleting a large one takes seconds.
484
+ const discard = Effect.fn("WorktreeCheckoutCache.discard")(
485
+ function* (target: string) {
486
+ const trashed = `${target}.trash-${NodeCrypto.randomUUID()}`;
487
+ yield* fileSystem.rename(target, trashed);
488
+ yield* fileSystem.remove(trashed, { recursive: true });
489
+ },
490
+ // Uninterruptible: deleting is not resumable, and a half-deleted folder must not be left named.
491
+ (effect) => Effect.ignore(Effect.uninterruptible(effect)),
492
+ );
493
+
494
+ const gitDirOf = Effect.fn("WorktreeCheckoutCache.gitDirOf")(function* (worktreePath: string) {
495
+ const contents = yield* fileSystem.readFileString(path.join(worktreePath, ".git"));
496
+ const gitDir = contents.match(/^gitdir: (.+)$/m)?.[1];
497
+ if (gitDir === undefined) {
498
+ return yield* new WorktreeCheckoutCacheError({
499
+ detail: `${worktreePath} is not a linked worktree`,
500
+ });
501
+ }
502
+ return path.resolve(worktreePath, gitDir.trim());
503
+ });
504
+
505
+ /**
506
+ * Creates the worktree from the cache. False means nothing was created and the caller should
507
+ * run `git worktree add`; any partial worktree has been removed again.
508
+ */
509
+ const create = Effect.fn("WorktreeCheckoutCache.create")(function* (input: {
510
+ readonly cwd: string;
511
+ readonly worktreePath: string;
512
+ readonly refName: string;
513
+ readonly checkoutWorkers: string;
514
+ }) {
515
+ if (!(yield* gitSupported)) return false;
516
+ const worktreePath = path.resolve(input.cwd, input.worktreePath);
517
+ const requested = yield* describe(input.cwd, input.refName);
518
+ if (requested === null) return false;
519
+ const entries = yield* listEntries(requested.bucket);
520
+ if (entries.length === 0) return false;
521
+ // A clone only works within one volume.
522
+ const parent = path.dirname(worktreePath);
523
+ yield* fileSystem.makeDirectory(parent, { recursive: true }).pipe(Effect.ignore);
524
+ const [bucketInfo, parentInfo] = yield* Effect.all([
525
+ fileSystem.stat(requested.bucket),
526
+ fileSystem.stat(parent),
527
+ ]).pipe(Effect.orElseSucceed(() => [null, null] as const));
528
+ if (bucketInfo === null || parentInfo === null || bucketInfo.dev !== parentInfo.dev) {
529
+ return false;
530
+ }
531
+
532
+ const populate = Effect.gen(function* () {
533
+ // What Git checked out, which can differ from `requested` when a tag shares the branch name.
534
+ const target = yield* describe(worktreePath, "HEAD");
535
+ if (target === null || (yield* fileSystem.exists(target.indexHook))) return null;
536
+ const worktreeFingerprint = yield* fingerprint(worktreePath, target.commonDir);
537
+ if (worktreeFingerprint === null) return null;
538
+ const compatible = entries.filter((entry) => entry.fingerprint === worktreeFingerprint);
539
+ let base = compatible.find((entry) => entry.tree === target.tree);
540
+ let changes: Effect.Success<ReturnType<typeof changedPaths>> = null;
541
+ for (const entry of base === undefined ? compatible : []) {
542
+ changes = yield* changedPaths(worktreePath, entry.tree, target.tree);
543
+ if (changes !== null && !changes.attributes) {
544
+ base = entry;
545
+ break;
546
+ }
547
+ }
548
+ if (base === undefined) return null;
549
+ // A cached file changed after Git wrote it; never hand it out again.
550
+ const reject = (entry: CacheEntry) =>
551
+ Effect.logWarning("worktree checkout cache entry changed; discarding it", {
552
+ directory: entry.directory,
553
+ }).pipe(Effect.andThen(discard(entry.directory)), Effect.as(null));
554
+ if (!(yield* directoriesUnchanged(base))) return yield* reject(base);
555
+ yield* Effect.all([touch(base.directory), touch(requested.bucket)], { discard: true });
556
+
557
+ const files = path.join(base.directory, "files");
558
+ // The worktree folder already holds Git's `.git` file, so its entries are cloned one by one.
559
+ yield* Effect.forEach(
560
+ yield* fileSystem.readDirectory(files),
561
+ (name) => clone(path.join(files, name), path.join(worktreePath, name)),
562
+ { discard: true },
563
+ );
564
+ // Checked again: a file added during the clone would otherwise come along unnoticed.
565
+ if (!(yield* directoriesUnchanged(base))) return yield* reject(base);
566
+ // A tracked hooks folder only exists once the files do; Git would have run this hook.
567
+ if (yield* fileSystem.exists(target.indexHook)) return null;
568
+ const restated = yield* restate({
569
+ source: path.join(base.directory, "index"),
570
+ target: path.join(yield* gitDirOf(worktreePath), "index"),
571
+ root: worktreePath,
572
+ verify: true,
573
+ });
574
+ if (restated === null) return yield* reject(base);
575
+ if (base.tree === target.tree || changes === null) return target;
576
+ // On a case-insensitive volume an added path can land on a file the cached tree kept.
577
+ const deleted = new Set(changes.deleted);
578
+ const kept = restated.paths.filter((file) => !deleted.has(file));
579
+ const names = new Set(kept.map((file) => foldCase(file)));
580
+ // A new folder whose name differs only in case would keep the cached spelling.
581
+ const keptFolders = parentDirectories(kept);
582
+ for (const [index, file] of restated.paths.entries()) {
583
+ if (restated.stats[index]?.kind === "directory" && !deleted.has(file))
584
+ keptFolders.add(file);
585
+ }
586
+ const spellings = new Map(
587
+ [...keptFolders].map((directory) => [foldCase(directory), directory]),
588
+ );
589
+ for (const file of changes.added) {
590
+ if (names.has(foldCase(file))) return null;
591
+ names.add(foldCase(file));
592
+ for (const directory of parentDirectories([file])) {
593
+ const existing = spellings.get(foldCase(directory));
594
+ if (existing !== undefined && existing !== directory) return null;
595
+ spellings.set(foldCase(directory), directory);
596
+ }
597
+ }
598
+ // A smudge filter run here would see the cached index, not the one Git builds from scratch.
599
+ if (yield* writesWithFilter(worktreePath, changes.written)) return null;
600
+ // Hooks off: a hook the move adds runs with Git's checkout environment there, so its
601
+ // presence afterwards means the caller falls back to that checkout.
602
+ const moved = yield* git("update", worktreePath, [
603
+ "-c",
604
+ `checkout.workers=${input.checkoutWorkers}`,
605
+ "-c",
606
+ "core.hooksPath=/dev/null",
607
+ "read-tree",
608
+ "-m",
609
+ "-u",
610
+ base.tree,
611
+ target.tree,
612
+ ]);
613
+ if (moved === null || (yield* fileSystem.exists(target.indexHook))) return null;
614
+ return target;
615
+ });
616
+ const rollback = git("rollback", input.cwd, [
617
+ "worktree",
618
+ "remove",
619
+ "--force",
620
+ "--",
621
+ worktreePath,
622
+ ]).pipe(
623
+ Effect.flatMap((removed) =>
624
+ removed === null
625
+ ? Effect.logWarning("could not remove a partially created worktree", { worktreePath })
626
+ : Effect.void,
627
+ ),
628
+ );
629
+ // Registration and the rollback that undoes it can't be separated by an interruption.
630
+ const target = yield* Effect.uninterruptibleMask((restore) =>
631
+ Effect.gen(function* () {
632
+ const registered = yield* git("register", input.cwd, [
633
+ "worktree",
634
+ "add",
635
+ "--no-checkout",
636
+ "--",
637
+ worktreePath,
638
+ input.refName,
639
+ ]);
640
+ if (registered === null) return null;
641
+ return yield* restore(populate).pipe(
642
+ Effect.catch((cause) =>
643
+ Effect.logWarning("worktree checkout cache failed; using git worktree add", {
644
+ cause,
645
+ }).pipe(Effect.as(null)),
646
+ ),
647
+ Effect.onExit((exit) =>
648
+ Exit.isSuccess(exit) && exit.value !== null ? Effect.void : rollback,
649
+ ),
650
+ );
651
+ }),
652
+ );
653
+ if (target === null) return false;
654
+
655
+ // `git worktree add --no-checkout` skips this hook; a normal add runs it.
656
+ const hook = yield* execute({
657
+ operation: "GitVcsDriver.createWorktree.postCheckout",
658
+ cwd: worktreePath,
659
+ args: [
660
+ "hook",
661
+ "run",
662
+ "--ignore-missing",
663
+ "post-checkout",
664
+ "--",
665
+ NULL_OID,
666
+ target.commit,
667
+ "1",
668
+ ],
669
+ env: { LANGUAGE: "C" },
670
+ allowNonZeroExit: true,
671
+ timeoutMs: null,
672
+ });
673
+ if (hook.exitCode !== 0) {
674
+ return yield* new GitCommandError({
675
+ operation: "GitVcsDriver.createWorktree",
676
+ command: "git worktree add",
677
+ cwd: input.cwd,
678
+ detail: "git worktree add failed: the post-checkout hook failed",
679
+ exitCode: hook.exitCode,
680
+ stderrLength: hook.stderr.length,
681
+ });
682
+ }
683
+ return true;
684
+ });
685
+
686
+ const removeIfAbandoned = Effect.fn("WorktreeCheckoutCache.removeIfAbandoned")(
687
+ function* (target: string, maxAgeMs: number) {
688
+ const info = yield* fileSystem.stat(target);
689
+ const modified = Option.getOrUndefined(info.mtime)?.getTime() ?? 0;
690
+ if ((yield* Clock.currentTimeMillis) - modified > maxAgeMs) {
691
+ yield* fileSystem.remove(target, { recursive: true });
692
+ }
693
+ },
694
+ (effect) => Effect.ignore(effect),
695
+ );
696
+
697
+ /** Caches the tree checked out in `worktreePath`, unless a cached checkout is already close to it. */
698
+ const build = Effect.fn("WorktreeCheckoutCache.build")(function* (
699
+ worktreePath: string,
700
+ // From before the worktree was checked out, so a `clear` during the checkout also counts.
701
+ generationAtStart: number,
702
+ ) {
703
+ if (!(yield* gitSupported)) return;
704
+ const target = yield* describe(worktreePath, "HEAD");
705
+ if (target === null) return;
706
+ const entryFingerprint = yield* fingerprint(worktreePath, target.commonDir);
707
+ if (entryFingerprint === null) return;
708
+ const entryName = `${target.tree}-${entryFingerprint}`;
709
+ yield* fileSystem.makeDirectory(target.bucket, { recursive: true });
710
+ const entries = yield* listEntries(target.bucket);
711
+ const compatible = entries.filter((entry) => entry.fingerprint === entryFingerprint);
712
+ if (compatible.some((entry) => entry.tree === target.tree)) return;
713
+ // Skip when a cached checkout is close enough to move forward cheaply.
714
+ let base: CacheEntry | undefined;
715
+ for (const entry of compatible) {
716
+ const changes = yield* changedPaths(worktreePath, entry.tree, target.tree);
717
+ if (changes === null || changes.attributes) continue;
718
+ if (changes.count < REBUILD_AFTER_CHANGED_FILES) return;
719
+ base ??= entry;
720
+ }
721
+ if (yield* usesFilter(worktreePath, target.bucket, target.tree)) return;
722
+
723
+ for (const name of yield* fileSystem.readDirectory(target.bucket)) {
724
+ if (!ENTRY_NAME.test(name)) {
725
+ const leftover = path.join(target.bucket, name);
726
+ yield* removeIfAbandoned(
727
+ leftover,
728
+ name.includes(".trash-") ? ABANDONED_TRASH_MS : ABANDONED_STAGING_MS,
729
+ );
730
+ }
731
+ }
732
+ const staging = path.join(target.bucket, `.staging-${NodeCrypto.randomUUID()}`);
733
+ const stagingFiles = path.join(staging, "files");
734
+ const stagingIndex = path.join(staging, "index");
735
+ yield* fileSystem.makeDirectory(staging);
736
+ const withIndex = (args: ReadonlyArray<string>) =>
737
+ git("build", worktreePath, [...CACHE_INDEX_CONFIG, `--work-tree=${stagingFiles}`, ...args], {
738
+ GIT_INDEX_FILE: stagingIndex,
739
+ });
740
+
741
+ yield* Effect.gen(function* () {
742
+ let built = false;
743
+ if (base !== undefined && (yield* directoriesUnchanged(base))) {
744
+ const from = base;
745
+ built = yield* Effect.gen(function* () {
746
+ yield* Effect.uninterruptible(clone(path.join(from.directory, "files"), stagingFiles));
747
+ if (!(yield* directoriesUnchanged(from))) return false;
748
+ const restated = yield* restate({
749
+ source: path.join(from.directory, "index"),
750
+ target: stagingIndex,
751
+ root: stagingFiles,
752
+ verify: true,
753
+ });
754
+ if (restated === null) return false;
755
+ return (yield* withIndex(["read-tree", "-m", "-u", from.tree, target.tree])) !== null;
756
+ }).pipe(Effect.orElseSucceed(() => false));
757
+ if (!built) {
758
+ yield* fileSystem.remove(stagingFiles, { recursive: true }).pipe(Effect.ignore);
759
+ yield* fileSystem.remove(stagingIndex).pipe(Effect.ignore);
760
+ }
761
+ }
762
+ if (!built) {
763
+ yield* fileSystem.makeDirectory(stagingFiles);
764
+ if ((yield* withIndex(["read-tree", "--reset", "-u", target.tree])) === null) {
765
+ return yield* new WorktreeCheckoutCacheError({ detail: "git read-tree failed" });
766
+ }
767
+ }
768
+ // Record the files' own stat data; Git leaves racily written entries for a later re-read.
769
+ const recorded = yield* restate({
770
+ source: stagingIndex,
771
+ target: stagingIndex,
772
+ root: stagingFiles,
773
+ verify: false,
774
+ });
775
+ if (recorded === null) {
776
+ return yield* new WorktreeCheckoutCacheError({
777
+ detail: "the cache index has an unsupported format or colliding paths",
778
+ });
779
+ }
780
+ yield* recordDirectories(staging, recorded);
781
+ if (generation !== generationAtStart) {
782
+ return yield* new WorktreeCheckoutCacheError({ detail: "the cache was cleared" });
783
+ }
784
+ yield* Effect.uninterruptible(
785
+ fileSystem.rename(staging, path.join(target.bucket, entryName)),
786
+ );
787
+ }).pipe(Effect.onError(() => discard(staging)));
788
+
789
+ yield* touch(target.bucket);
790
+ yield* Effect.forEach(
791
+ (yield* listEntries(target.bucket)).slice(KEEP_PER_REPOSITORY),
792
+ (entry) => discard(entry.directory),
793
+ { discard: true },
794
+ );
795
+ const now = yield* Clock.currentTimeMillis;
796
+ for (const name of yield* fileSystem.readDirectory(cacheDir)) {
797
+ const bucket = path.join(cacheDir, name);
798
+ if (bucket === target.bucket) continue;
799
+ if (name.includes(".trash-")) {
800
+ yield* removeIfAbandoned(bucket, ABANDONED_TRASH_MS);
801
+ continue;
802
+ }
803
+ const info = yield* fileSystem.stat(bucket).pipe(Effect.option);
804
+ const used = info.pipe(
805
+ Option.flatMap((value) => value.mtime),
806
+ Option.map((date) => date.getTime()),
807
+ );
808
+ if (Option.isSome(used) && now - used.value > UNUSED_REPOSITORY_MS) {
809
+ yield* discard(bucket);
810
+ }
811
+ }
812
+ });
813
+
814
+ /** Caches the worktree's checkout in the background, so the next worktree can clone it. */
815
+ const schedule = (worktreePath: string, generationAtStart: number) =>
816
+ Effect.suspend(() => {
817
+ if (pendingBuilds.has(worktreePath)) return Effect.void;
818
+ pendingBuilds.add(worktreePath);
819
+ return build(worktreePath, generationAtStart).pipe(
820
+ builds.withPermits(1),
821
+ Effect.ignoreCause({ log: true }),
822
+ Effect.ensuring(Effect.sync(() => pendingBuilds.delete(worktreePath))),
823
+ Effect.forkIn(scope),
824
+ Effect.asVoid,
825
+ );
826
+ });
827
+
828
+ /** Deletes every cached checkout in the background; builds already running are dropped. */
829
+ const clear = Effect.suspend(() => {
830
+ generation++;
831
+ return fileSystem.exists(cacheDir);
832
+ }).pipe(
833
+ Effect.flatMap((exists) =>
834
+ exists
835
+ ? discard(cacheDir).pipe(builds.withPermits(1), Effect.forkIn(scope), Effect.asVoid)
836
+ : Effect.void,
837
+ ),
838
+ Effect.ignore,
839
+ );
840
+
841
+ /** Pass to `schedule` from before a checkout starts. */
842
+ const currentGeneration = Effect.sync(() => generation);
843
+
844
+ return { create, build, schedule, clear, currentGeneration };
845
+});
apps/web/src/components/settings/LabsSettingsPanel.tsx
+35
-1
@@ -14,7 +14,7 @@ import { SettingsPageContainer, SettingsRow, SettingsSection } from "./settingsL
14
import { searchableSetting } from "./settingsSearch";
15
import { LegacyFeaturesSection } from "./SettingsPanels";
16
import { useScopedSettings, useUpdateScopedSettings } from "./useScopedSettings";
17
-import { useOptionalSettingsScope } from "./SettingsScopeContext";
17
+import { useOptionalSettingsScope, useSettingsScope } from "./SettingsScopeContext";
18
import { firstManagedDenial, usePrimaryManagedPolicy } from "~/state/managedPolicy";
19
20
/** Features still settling in, and legacy behavior kept for people who rely on it. */
@@ -29,6 +29,7 @@ export function LabsSettingsPanel() {
29
{hasCloudPublicConfig() ? <GuestLinksRowWithSignIn /> : <GuestLinksRow />}
30
<LinkedEnvironmentsRow />
31
<SimlockHostsRow />
32
+ <FastWorktreeCheckoutRow />
33
</SettingsSection>
34
<LegacyFeaturesSection />
35
</SettingsPageContainer>
@@ -247,3 +248,36 @@ function SimlockHostsRow() {
248
/>
249
);
250
}
251
+
252
+/** Shows only when every machine in scope is a Mac, since only macOS servers honor it. */
253
+function FastWorktreeCheckoutRow() {
254
+ const { scope, connectedEnvironments } = useSettingsScope();
255
+ const settings = useScopedSettings();
256
+ const updateSettings = useUpdateScopedSettings();
257
+ if (
258
+ scope.kind === "project" ||
259
+ scope.kind === "checkout" ||
260
+ connectedEnvironments.length === 0 ||
261
+ connectedEnvironments.some(
262
+ (environment) =>
263
+ environment.serverConfig?.environment.capabilities.fastWorktreeCheckout !== true,
264
+ )
265
+ )
266
+ return null;
267
+ return (
268
+ <SettingsRow
269
+ serverScoped
270
+ {...searchableSetting("worktree-fast-checkout")}
271
+ settingKeys={["fastWorktreeCheckout"]}
272
+ description="On a Mac, clone new worktrees from a checkout cached in the T3 home folder instead of writing every file. Uses Git’s normal checkout when it can’t. Turning it off deletes the cache."
273
+ control={
274
+ <ScopedSwitch
275
+ settingKeys={["fastWorktreeCheckout"]}
276
+ checked={settings.fastWorktreeCheckout}
277
+ onCheckedChange={(checked) => updateSettings({ fastWorktreeCheckout: Boolean(checked) })}
278
+ aria-label="Fast worktree checkout"
279
+ />
280
+ }
281
+ />
282
+ );
283
+}
apps/web/src/components/settings/settingsSearch.ts
+12
-1
@@ -68,6 +68,7 @@ export interface SettingsSearchItem {
68
readonly wslAvailableOnly?: boolean;
69
readonly managedTunnelOnly?: boolean;
70
readonly peerLinksOnly?: boolean;
71
+ readonly fastWorktreeCheckoutOnly?: boolean;
72
readonly secondary?: boolean;
73
readonly requiresThreadAutoSettlement?: boolean;
74
}
@@ -82,6 +83,7 @@ export interface SettingsSearchAvailability {
83
readonly hasThreadAutoSettlement: boolean;
84
readonly managedTunnelActive?: boolean;
85
readonly hasPeerLinkHost?: boolean;
86
+ readonly hasFastWorktreeCheckoutEnvironment?: boolean;
87
}
88
89
export const SETTINGS_SECTION_LABELS: Readonly<Record<SettingsPath, string>> = {
@@ -495,6 +497,14 @@ export const SETTINGS_SEARCH_ITEMS = [
497
scope: "environment",
498
searchTerms: ["beta alpha simlock callstack simulator emulator ios android pool lease gateway"],
499
},
500
+ {
501
+ id: "worktree-fast-checkout",
502
+ title: "Fast worktree checkout",
503
+ to: "/settings/labs",
504
+ scope: "environment",
505
+ fastWorktreeCheckoutOnly: true,
506
+ searchTerms: ["beta fast worktree checkout clone apfs copy-on-write cache macos speed"],
507
+ },
508
{
509
id: "voice-transcription-destination",
510
title: "Transcribe with",
@@ -1444,7 +1454,8 @@ export function filterAvailableSettingsSearchItems(
1454
(!item.wslAvailableOnly || availability.isWslSettingsRowVisible) &&
1455
(!item.requiresThreadAutoSettlement || availability.hasThreadAutoSettlement) &&
1456
(!item.managedTunnelOnly || availability.managedTunnelActive === true) &&
1447
- (!item.peerLinksOnly || availability.hasPeerLinkHost === true),
1457
+ (!item.peerLinksOnly || availability.hasPeerLinkHost === true) &&
1458
+ (!item.fastWorktreeCheckoutOnly || availability.hasFastWorktreeCheckoutEnvironment === true),
1459
);
1460
}
1461
apps/web/src/components/settings/useAvailableSettingsSearchItems.ts
+8
@@ -28,6 +28,13 @@ export function useAvailableSettingsSearchItems() {
28
hasServerConfig: environment.serverConfig !== null,
29
}),
30
) === true;
31
+ // Any machine that offers it; the row then shows for a settings scope where all selected ones do.
32
+ const hasFastWorktreeCheckoutEnvironment =
33
+ environments.some(
34
+ (environment) =>
35
+ environment.connection.phase === "connected" &&
36
+ environment.serverConfig?.environment.capabilities.fastWorktreeCheckout === true,
37
+ ) === true;
38
const hasThreadAutoSettlement =
39
getThreadAutoSettlementSearchAvailability(environments).eligibleEnvironmentIds.length > 0;
40
const primaryEnvironmentId = usePrimaryEnvironmentId();
@@ -57,5 +64,6 @@ export function useAvailableSettingsSearchItems() {
64
hasThreadAutoSettlement,
65
managedTunnelActive,
66
hasPeerLinkHost,
67
+ hasFastWorktreeCheckoutEnvironment,
68
});
69
}
docs/user/project-settings.md
+13
@@ -201,6 +201,19 @@ such as another drive, set **Settings → Worktrees → Worktree location** to a
201
`D:\worktrees` or `~/worktrees`. The setting is per machine. Existing worktrees stay where they
202
are, and cleanup covers both the default folder and the custom one.
203
204
+## Fast worktree checkout on macOS
205
+
206
+Fast worktree checkout is a beta. Turn it on for each Mac in **Settings → Labs → Fast worktree
207
+checkout**. T3 Code then keeps a few recent checkouts of each repository in the `caches` folder of
208
+the T3 home directory. A new worktree is cloned from one of them with APFS copy-on-write, which is
209
+about twice as fast as writing every file and makes the first `git status` in it fast as well.
210
+Turning it off deletes the cache.
211
+
212
+The first worktree of a repository uses Git's normal checkout and fills the cache. It needs Git 2.42
213
+or newer. Git's normal checkout is also used for worktrees on a different drive from the T3 home
214
+directory, sparse checkouts, repositories whose attributes use filters such as Git LFS, and
215
+repositories whose checkout settings changed.
216
+
217
## Storage cleanup
218
219
Open **Settings → Worktrees → Cleanup** to enable automatic cleanup on one machine or all connected
packages/contracts/src/environment.ts
+2
@@ -101,6 +101,8 @@ export const ExecutionEnvironmentCapabilities = Schema.Struct({
101
projectWorktreeCleanup: Schema.optionalKey(Schema.Boolean),
102
settledWorktreeCleanup: Schema.optionalKey(Schema.Boolean),
103
worktreesDirectory: Schema.optionalKey(Schema.Boolean),
104
+ /** Sent by macOS servers, which honor the fastWorktreeCheckout setting. */
105
+ fastWorktreeCheckout: Schema.optionalKey(Schema.Boolean),
106
threadAutoSettlementScope: Schema.optionalKey(Schema.Boolean),
107
threadRestartContinuation: Schema.optionalKey(Schema.Boolean),
108
projectSettingsOverrides: Schema.optionalKey(Schema.Boolean),
packages/contracts/src/settings.ts
+3
@@ -1259,6 +1259,8 @@ export const ServerSettings = Schema.Struct({
1259
),
1260
1261
worktreesDirectory: TrimmedString.pipe(Schema.withDecodingDefault(Effect.succeed(""))),
1262
+ /** macOS only, Labs beta: clone new worktrees from a cached checkout instead of writing every file. */
1263
+ fastWorktreeCheckout: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
1264
/** Server-maintained history keeps old worktrees eligible for cleanup and review diffs. */
1265
previousWorktreesDirectories: Schema.Array(TrimmedString).pipe(
1266
Schema.withDecodingDefault(Effect.succeed([])),
@@ -1687,6 +1689,7 @@ export const ServerSettingsPatch = Schema.Struct({
1689
}),
1690
),
1691
worktreesDirectory: Schema.optionalKey(TrimmedString),
1692
+ fastWorktreeCheckout: Schema.optionalKey(Schema.Boolean),
1693
responseStreamingMode: Schema.optionalKey(ResponseStreamingMode),
1694
enableProviderUpdateChecks: Schema.optionalKey(Schema.Boolean),
1695
continueThreadsAfterServerUpdate: Schema.optionalKey(Schema.Boolean),