@devries-cameron20 / t3code Mirror · read-only / commits / 4f781196e1
Fork 0

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({