@devries-cameron20 / t3code-1 / commits / b7d33af938
Fork 0

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),