The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 09:45 UTC
feat(server): t3.json can name sparse-checkout patterns for new worktrees (#26820)
Co-authored-by: maria-rcks <maria@kuuro.net> Co-authored-by: Julius Marminge <julius0216@outlook.com>
Michael Huo committed
Nov 16, 2026 at 23:41 UTC
4f781196e12337e5c14a6f621fbb2715d425bd95
4 files changed
+287
-22
apps/server/src/vcs/GitVcsDriverCore.test.ts
+150
@@ -6906,6 +6906,51 @@ it.layer(layerTest)("GitVcsDriver core integration", (it) => {
6906
}).pipe(withGitFileProtocol),
6907
);
6908
6909
+ it.effect("sparse worktrees read .gitmodules and t3.json from HEAD", () =>
6910
+ Effect.gen(function* () {
6911
+ const fileSystem = yield* FileSystem.FileSystem;
6912
+ const pathService = yield* Path.Path;
6913
+ const submoduleRepo = yield* makeTmpDir("git-submodule-");
6914
+ yield* initRepoWithCommit(submoduleRepo);
6915
+ yield* writeTextFile(submoduleRepo, "SHARED.md", "# shared\n");
6916
+ yield* git(submoduleRepo, ["add", "."]);
6917
+ yield* git(submoduleRepo, ["commit", "-m", "shared"]);
6918
+ const cwd = yield* makeTmpDir();
6919
+ const { initialBranch } = yield* initRepoWithCommit(cwd);
6920
+ yield* git(cwd, ["submodule", "add", NodeURL.pathToFileURL(submoduleRepo).href, "shared"]);
6921
+ yield* writeTextFile(cwd, "sparse-patterns.txt", "/shared/\n");
6922
+ const driver = yield* GitVcsDriver.GitVcsDriver;
6923
+ const worktrees = yield* makeTmpDir("git-worktrees-");
6924
+
6925
+ const createSparse = Effect.fn(function* (projectFile: string, branch: string) {
6926
+ yield* writeTextFile(cwd, "t3.json", projectFile);
6927
+ yield* git(cwd, ["add", "."]);
6928
+ yield* git(cwd, ["commit", "-m", branch]);
6929
+ const sparsePath = pathService.join(worktrees, branch);
6930
+ // A relative path also covers the git commands that run inside the new worktree.
6931
+ yield* driver.createWorktree({
6932
+ cwd,
6933
+ path: pathService.relative(cwd, sparsePath),
6934
+ refName: initialBranch,
6935
+ newRefName: branch,
6936
+ });
6937
+ assert.isFalse(yield* fileSystem.exists(pathService.join(sparsePath, ".gitmodules")));
6938
+ assert.isFalse(yield* fileSystem.exists(pathService.join(sparsePath, "t3.json")));
6939
+ return yield* fileSystem.exists(pathService.join(sparsePath, "shared", "SHARED.md"));
6940
+ });
6941
+
6942
+ assert.isTrue(
6943
+ yield* createSparse(`{ "worktreeSparsePatternsPath": "sparse-patterns.txt" }`, "sparse"),
6944
+ );
6945
+ assert.isFalse(
6946
+ yield* createSparse(
6947
+ `{ "worktreeSparsePatternsPath": "sparse-patterns.txt", "worktreeSubmodules": "none" }`,
6948
+ "sparse-none",
6949
+ ),
6950
+ );
6951
+ }).pipe(withGitFileProtocol),
6952
+ );
6953
+
6954
it.effect("still creates the worktree when submodule checkout fails", () =>
6955
Effect.gen(function* () {
6956
const fileSystem = yield* FileSystem.FileSystem;
@@ -7157,6 +7202,111 @@ it.layer(layerTest)("GitVcsDriver core integration", (it) => {
7202
}).pipe(withGitFileProtocol),
7203
);
7204
7205
+ it.effect("checks out only the t3.json sparse patterns in a new worktree", () =>
7206
+ Effect.gen(function* () {
7207
+ const fileSystem = yield* FileSystem.FileSystem;
7208
+ const pathService = yield* Path.Path;
7209
+ const repo = yield* makeTmpDir();
7210
+ const { initialBranch } = yield* initRepoWithCommit(repo);
7211
+ yield* writeTextFile(repo, "src/app.ts", "export {};\n");
7212
+ yield* writeTextFile(repo, "assets/large.bin", "large\n");
7213
+ yield* writeTextFile(repo, "sparse-patterns.txt", "/*\n!/assets/\n");
7214
+ yield* writeTextFile(
7215
+ repo,
7216
+ "t3.json",
7217
+ `{ "worktreeSparsePatternsPath": "./sparse-patterns.txt" }`,
7218
+ );
7219
+ yield* git(repo, ["add", "."]);
7220
+ yield* git(repo, ["commit", "-m", "sparse patterns"]);
7221
+ yield* git(repo, ["checkout", "-q", "-b", "previous"]);
7222
+ yield* git(repo, ["checkout", "-q", initialBranch]);
7223
+ const driver = yield* GitVcsDriver.GitVcsDriver;
7224
+ const worktrees = yield* makeTmpDir("git-worktrees-");
7225
+ // A project opened at a subdirectory still reads both files from the repository root.
7226
+ const cwd = pathService.join(repo, "src");
7227
+
7228
+ const assertSparse = Effect.fn(function* (worktreePath: string, branch: string) {
7229
+ assert.isTrue(yield* fileSystem.exists(pathService.join(worktreePath, "src", "app.ts")));
7230
+ assert.isFalse(
7231
+ yield* fileSystem.exists(pathService.join(worktreePath, "assets", "large.bin")),
7232
+ );
7233
+ assert.equal(yield* git(worktreePath, ["sparse-checkout", "list"]), "/*\n!/assets/");
7234
+ assert.equal(yield* git(worktreePath, ["branch", "--show-current"]), branch);
7235
+ });
7236
+
7237
+ const sparse = pathService.join(worktrees, "sparse");
7238
+ yield* driver.createWorktree({
7239
+ cwd,
7240
+ path: pathService.relative(cwd, sparse),
7241
+ refName: initialBranch,
7242
+ newRefName: "feature/sparse",
7243
+ });
7244
+ yield* assertSparse(sparse, "feature/sparse");
7245
+
7246
+ const fromPrevious = pathService.join(worktrees, "from-previous");
7247
+ yield* driver.createWorktree({
7248
+ cwd,
7249
+ path: fromPrevious,
7250
+ refName: "-",
7251
+ newRefName: "feature/from-previous",
7252
+ });
7253
+ yield* assertSparse(fromPrevious, "feature/from-previous");
7254
+ assert.notInclude(yield* git(repo, ["worktree", "list", "--porcelain"]), "locked");
7255
+
7256
+ // Only the sparse checkout runs the hook, so its failure removes the locked registration.
7257
+ yield* writeTextFile(repo, ".git/hooks/post-checkout", "#!/bin/sh\nexit 1\n");
7258
+ yield* fileSystem.chmod(pathService.join(repo, ".git/hooks/post-checkout"), 0o755);
7259
+ const failed = pathService.join(worktrees, "failed");
7260
+ yield* Effect.flip(
7261
+ driver.createWorktree({
7262
+ cwd,
7263
+ path: failed,
7264
+ refName: initialBranch,
7265
+ newRefName: "feature/failed",
7266
+ }),
7267
+ );
7268
+ assert.isFalse(yield* fileSystem.exists(failed));
7269
+ assert.notInclude(yield* git(repo, ["worktree", "list", "--porcelain"]), "feature/failed");
7270
+ assert.equal(yield* git(repo, ["branch", "--list", "feature/failed"]), "");
7271
+ }),
7272
+ );
7273
+
7274
+ it.effect("fails without a worktree when the t3.json sparse pattern path is not a file", () =>
7275
+ Effect.gen(function* () {
7276
+ const fileSystem = yield* FileSystem.FileSystem;
7277
+ const pathService = yield* Path.Path;
7278
+ const cwd = yield* makeTmpDir();
7279
+ const { initialBranch } = yield* initRepoWithCommit(cwd);
7280
+ yield* writeTextFile(cwd, "patterns/keep.txt", "/*\n");
7281
+ const driver = yield* GitVcsDriver.GitVcsDriver;
7282
+ const worktrees = yield* makeTmpDir("git-worktrees-");
7283
+ for (const patternsPath of ["missing.txt", "patterns"]) {
7284
+ yield* writeTextFile(
7285
+ cwd,
7286
+ "t3.json",
7287
+ JSON.stringify({ worktreeSparsePatternsPath: patternsPath }),
7288
+ );
7289
+ yield* git(cwd, ["add", "."]);
7290
+ yield* git(cwd, ["commit", "-m", "missing sparse patterns"]);
7291
+ const worktreePath = pathService.join(worktrees, patternsPath);
7292
+
7293
+ const error = yield* Effect.flip(
7294
+ driver.createWorktree({
7295
+ cwd,
7296
+ path: worktreePath,
7297
+ refName: initialBranch,
7298
+ newRefName: `feature/${patternsPath}`,
7299
+ }),
7300
+ );
7301
+
7302
+ assert.include(error.detail, patternsPath);
7303
+ assert.isFalse(yield* fileSystem.exists(worktreePath));
7304
+ assert.notInclude(yield* git(cwd, ["worktree", "list"]), worktreePath);
7305
+ assert.equal(yield* git(cwd, ["branch", "--list", `feature/${patternsPath}`]), "");
7306
+ }
7307
+ }),
7308
+ );
7309
+
7310
it.effect("still creates the worktree when the base-ref config stays locked", () =>
7311
Effect.gen(function* () {
7312
const cwd = yield* makeTmpDir();
apps/server/src/vcs/GitVcsDriverCore.ts
+119
-22
@@ -5018,6 +5018,47 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
5018
},
5019
);
5020
5021
+ // A new worktree has no files yet, so t3.json and its pattern file come from the ref itself.
5022
+ const readWorktreeSparsePatterns = Effect.fn("readWorktreeSparsePatterns")(function* (
5023
+ cwd: string,
5024
+ refName: string,
5025
+ ) {
5026
+ // `git show` does not read a lone - as the previous checkout either.
5027
+ const ref = refName === "-" ? "@{-1}" : refName;
5028
+ const projectFile = yield* executeGit(
5029
+ "GitVcsDriver.createWorktree.readProjectFile",
5030
+ cwd,
5031
+ ["show", `${ref}:${T3_PROJECT_FILE_NAME}`],
5032
+ { allowNonZeroExit: true },
5033
+ );
5034
+ if (projectFile.exitCode !== 0) return null;
5035
+ const file = parseT3ProjectFile(projectFile.stdout);
5036
+ if (file === null) {
5037
+ yield* Effect.logWarning("t3.json is invalid; checking out the full worktree", { cwd, ref });
5038
+ return null;
5039
+ }
5040
+ if (file.worktreeSparsePatternsPath === undefined) return null;
5041
+ // Git reads <ref>:./path from the working directory, so keep the path repository-relative.
5042
+ const patternsPath = file.worktreeSparsePatternsPath.replace(/^(?:\.\/)+/, "");
5043
+ const patterns = patternsPath.split("/").includes("..")
5044
+ ? null
5045
+ : yield* executeGit(
5046
+ "GitVcsDriver.createWorktree.readSparsePatterns",
5047
+ cwd,
5048
+ ["cat-file", "blob", `${ref}:${patternsPath}`],
5049
+ { allowNonZeroExit: true },
5050
+ );
5051
+ if (patterns === null || patterns.exitCode !== 0) {
5052
+ return yield* new GitCommandError({
5053
+ operation: "GitVcsDriver.createWorktree",
5054
+ command: "git worktree add",
5055
+ cwd,
5056
+ detail: `t3.json names the sparse-checkout pattern file "${file.worktreeSparsePatternsPath}", which is not a file in ${refName}.`,
5057
+ });
5058
+ }
5059
+ return patterns.stdout;
5060
+ });
5061
+
5062
// A checkout stamps most files in the second it writes the index, and Git re-reads every file
5063
// stamped in the index's own second or later ("racily clean") on each status, diff and add.
5064
// T3's own git calls never rewrite a worktree's index, so refresh it once.
@@ -5141,6 +5182,10 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
5182
worktreePath = `${basePath}-${suffix}`;
5183
}
5184
}
5185
+ // Later steps run git inside the worktree, so resolve a relative path the way worktree add does.
5186
+ worktreePath = path.resolve(input.cwd, worktreePath);
5187
+ // Read before the branch exists, so a missing pattern file leaves nothing behind.
5188
+ const sparsePatterns = yield* readWorktreeSparsePatterns(input.cwd, input.refName);
5189
const newRefName = input.newRefName;
5190
// Older Git still creates worktrees normally, but cannot prove ownership for cancellation.
5191
const addHelp = newRefName
@@ -5167,6 +5212,19 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
5212
const checkoutRef = newRefName ?? input.refName;
5213
const progress = options?.progress;
5214
const onCheckoutProgress = progress?.onCheckoutProgress;
5215
+ const checkoutProgressOptions: ExecuteGitOptions = onCheckoutProgress
5216
+ ? {
5217
+ // Git only prints checkout progress when stderr is a tty or the
5218
+ // delay elapsed. GIT_PROGRESS_DELAY=0 forces it through the pipe.
5219
+ env: { GIT_PROGRESS_DELAY: "0" },
5220
+ progress: {
5221
+ onStderrLine: (line) => {
5222
+ const parsed = parseGitCheckoutProgressLine(line);
5223
+ return parsed ? onCheckoutProgress(parsed) : Effect.void;
5224
+ },
5225
+ },
5226
+ }
5227
+ : {};
5228
5229
// Both reads leave the repository alone, so they share one round trip before the checkout.
5230
const [configuredCheckoutWorkers, base] = yield* Effect.all(
@@ -5179,7 +5237,9 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
5237
{ concurrency: "unbounded" },
5238
);
5239
const checkoutWorkers = configuredCheckoutWorkers ?? "0";
5182
- const fastCheckout = checkoutCache !== undefined && options?.fastCheckout === true;
5240
+ // The cache clones a full checkout, so a sparse worktree uses Git's own checkout.
5241
+ const fastCheckout =
5242
+ checkoutCache !== undefined && options?.fastCheckout === true && sparsePatterns === null;
5243
const cacheGeneration = fastCheckout ? yield* checkoutCache.currentGeneration : 0;
5244
const stockCheckout = executeGitWithStableDiagnostics(
5245
"GitVcsDriver.createWorktree",
@@ -5189,6 +5249,7 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
5249
`checkout.workers=${checkoutWorkers}`,
5250
"worktree",
5251
"add",
5252
+ ...(sparsePatterns === null ? [] : ["--no-checkout"]),
5253
...(lockReason ? ["--lock", "--reason", lockReason] : []),
5254
"--",
5255
worktreePath,
@@ -5202,21 +5263,42 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
5263
// Hooks and filter drivers may print without bound; only progress lines are read.
5264
appendTruncationMarker: true,
5265
keepLineCallbacksAfterTruncation: true,
5205
- ...(onCheckoutProgress
5206
- ? {
5207
- // Git only prints checkout progress when stderr is a tty or the
5208
- // delay elapsed. GIT_PROGRESS_DELAY=0 forces it through the pipe.
5209
- env: { GIT_PROGRESS_DELAY: "0" },
5210
- progress: {
5211
- onStderrLine: (line) => {
5212
- const parsed = parseGitCheckoutProgressLine(line);
5213
- return parsed ? onCheckoutProgress(parsed) : Effect.void;
5214
- },
5215
- },
5216
- }
5217
- : {}),
5266
+ ...(sparsePatterns === null ? checkoutProgressOptions : {}),
5267
},
5268
);
5269
+ const sparseCheckout =
5270
+ sparsePatterns === null
5271
+ ? Effect.void
5272
+ : Effect.gen(function* () {
5273
+ // The first sparse-checkout in a repository enables extensions.worktreeConfig.
5274
+ yield* runGit(
5275
+ "GitVcsDriver.createWorktree.sparseCheckout",
5276
+ worktreePath,
5277
+ ["sparse-checkout", "set", "--no-cone", "--stdin"],
5278
+ { stdin: sparsePatterns, writesSharedConfig: true },
5279
+ );
5280
+ yield* executeGitWithStableDiagnostics(
5281
+ "GitVcsDriver.createWorktree.checkout",
5282
+ worktreePath,
5283
+ ["-c", `checkout.workers=${checkoutWorkers}`, "checkout"],
5284
+ {
5285
+ fallbackErrorDetail: "git checkout failed",
5286
+ timeoutMs: null,
5287
+ appendTruncationMarker: true,
5288
+ keepLineCallbacksAfterTruncation: true,
5289
+ ...checkoutProgressOptions,
5290
+ },
5291
+ );
5292
+ }).pipe(
5293
+ // A worktree without its files is no use. removeWorktree refuses a locked worktree,
5294
+ // so one that carries the lock reason is unlocked first.
5295
+ Effect.onError(() =>
5296
+ (lockReason
5297
+ ? releaseWorktreeRegistration(input.cwd, lockReason, true)
5298
+ : removeWorktree({ cwd: input.cwd, path: worktreePath, force: true })
5299
+ ).pipe(Effect.ignore),
5300
+ ),
5301
+ );
5302
// Set inside the claim's uninterruptible region: a pending cancel still surfaces as it ends.
5303
let claimed = false;
5304
const onWorktreeClaimed = progress?.onWorktreeClaimed;
@@ -5233,6 +5315,7 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
5315
.pipe(Effect.flatMap((cloned) => (cloned ? Effect.void : stockCheckout)))
5316
: stockCheckout
5317
).pipe(
5318
+ Effect.andThen(sparseCheckout),
5319
Effect.andThen(
5320
fastCheckout ? checkoutCache.schedule(worktreePath, cacheGeneration) : Effect.void,
5321
),
@@ -5279,9 +5362,15 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
5362
);
5363
5364
// worktree add leaves submodules empty, potentially omitting project skills, tools or source.
5282
- const hasSubmodules = yield* fileSystem
5283
- .exists(path.join(worktreePath, ".gitmodules"))
5284
- .pipe(Effect.orElseSucceed(() => false));
5365
+ // Ask HEAD, because sparse patterns can leave .gitmodules out of the working tree.
5366
+ const hasSubmodules = yield* runGit(
5367
+ "GitVcsDriver.createWorktree.findSubmodules",
5368
+ worktreePath,
5369
+ ["cat-file", "-e", "HEAD:.gitmodules"],
5370
+ ).pipe(
5371
+ Effect.as(true),
5372
+ Effect.orElseSucceed(() => false),
5373
+ );
5374
const submoduleMode = !hasSubmodules
5375
? { value: "none" as const, source: "environment" as const }
5376
: resolveProjectFileBackedSetting(
@@ -5289,9 +5378,16 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
5378
options?.submodules ?? null,
5379
options?.submodules != null
5380
? null
5292
- : yield* fileSystem.readFileString(path.join(worktreePath, T3_PROJECT_FILE_NAME)).pipe(
5293
- Effect.flatMap((contents) => {
5294
- const file = parseT3ProjectFile(contents);
5381
+ : // Read HEAD for the same reason: sparse patterns can leave t3.json out too.
5382
+ yield* executeGit(
5383
+ "GitVcsDriver.createWorktree.readProjectFile",
5384
+ worktreePath,
5385
+ ["show", `HEAD:${T3_PROJECT_FILE_NAME}`],
5386
+ { allowNonZeroExit: true },
5387
+ ).pipe(
5388
+ Effect.flatMap((result) => {
5389
+ if (result.exitCode !== 0) return Effect.succeed(null);
5390
+ const file = parseT3ProjectFile(result.stdout);
5391
return file === null
5392
? Effect.logWarning("t3.json is invalid; initializing submodules recursively", {
5393
worktreePath,
@@ -5347,8 +5443,9 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
5443
yield* runGitStdout("GitVcsDriver.createWorktree.listSubmodules", worktreePath, [
5444
"config",
5445
"-z",
5350
- "--file",
5351
- ".gitmodules",
5446
+ // HEAD, not the working tree: sparse patterns can leave .gitmodules out.
5447
+ "--blob",
5448
+ "HEAD:.gitmodules",
5449
"--get-regexp",
5450
"^submodule\\..*\\.path$",
5451
]),
docs/user/project-settings.md
+9
@@ -197,6 +197,15 @@ itself, or **Skip** to leave them for a setup script. It resolves in the same or
197
workspace default: a `"worktreeSubmodules"` value in the `t3.json` of the branch being checked out
198
applies when the project and environment are both on **Inherit**.
199
200
+New worktrees check out every file. For a large repository, set `"worktreeSparsePatternsPath"` in
201
+`t3.json` to a repository-relative file of git sparse-checkout patterns in non-cone syntax. New
202
+worktrees then check out only the matching files, before any other file is written. Both files are
203
+read from the branch being checked out, so the patterns can leave out `t3.json` and `.gitmodules`.
204
+If the pattern file is missing, creating the worktree fails instead of checking out everything.
205
+Submodules still follow **Submodules** above, also under excluded paths; set it to **Skip** to leave
206
+them empty. The first sparse worktree turns on Git's `extensions.worktreeConfig` for the repository.
207
+This needs Git 2.35 or newer.
208
+
209
## Worktree location
210
211
New worktrees go in the `worktrees` folder of the T3 home directory. To put them somewhere else,
packages/contracts/src/t3ProjectFile.ts
+9
@@ -102,6 +102,15 @@ export const T3ProjectFile = Schema.Struct({
102
'How new worktrees populate git submodules: "recursive" (the default) initializes nested submodules too, "top-level" initializes only those declared by this repository, and "none" leaves every submodule empty for a setup script to handle. A project or environment setting in T3 Code overrides this.',
103
}),
104
),
105
+ worktreeSparsePatternsPath: Schema.optionalKey(
106
+ trimmedNonEmpty(
107
+ {
108
+ description:
109
+ 'Repository-relative path to a git sparse-checkout pattern file in non-cone syntax (e.g. ".t3/sparse-checkout"). New worktrees check out only the files it matches. Both files are read from the branch being checked out; a missing pattern file fails the worktree instead of checking out everything.',
110
+ },
111
+ T3_PROJECT_FILE_PATH_MAX_LENGTH,
112
+ ),
113
+ ),
114
scripts: Schema.optionalKey(
115
Schema.Array(T3ProjectFileScript)
116
.annotate({