feat(worktree): copy ignored files into new worktrees (#156)

- add a project setting for gitignore-style worktree copy patterns
- wire the patterns through worktree creation and copy matching ignored files
- add tests plus design docs for the new worktree-copy flow

Author: SDSLeon

docs/superpowers/specs/2026-06-10-worktree-copy-ignored-files-design.md

@@ -0,0 +1,100 @@
+# Copy gitignored files into new worktrees
+
+**Date:** 2026-06-10
+**Status:** Approved
+
+## Problem
+
+Files excluded by `.gitignore` (most commonly `.env` and friends) are not part of a
+checkout, so a freshly created worktree is missing them. Users currently have to copy
+them by hand or script it via the setup script. Project worktree settings should let
+users declare which ignored files to carry over, and Lightcode should copy them
+automatically when a worktree is created.
+
+## Decisions
+
+- Users specify files with **gitignore-style patterns** (e.g. `.env.*`), one per line —
+  not a file picker.
+- Copying happens **only at worktree creation**. No sync action for existing worktrees.
+- Candidate files are enumerated with git, not a filesystem walk: only files that are
+  actually ignored in the main project can match, so tracked files in the fresh
+  checkout are never clobbered, and fully-ignored directories (`node_modules/`)
+  collapse to a single entry, keeping enumeration fast.
+
+## Design
+
+### Settings schema
+
+Add to `projectScriptsSchema` in `src/shared/contracts/project.ts`:
+
+```ts
+worktreeCopyPatterns: z.array(z.string()).optional(),
+```
+
+The field rides in the existing `scripts` JSON column of the `projects` table — no DB
+migration. Patterns are stored as a cleaned array (trimmed, no blanks, no `#` comments).
+
+### UI
+
+`src/renderer/views/ProjectSettingsOverlay/parts/ScriptsSection.tsx` (the "Worktrees"
+settings page) gains a third field alongside Setup script and Cleanup script:
+
+- Label: "Copy ignored files"
+- Help text: copied from the main project into each new worktree; gitignore-style
+  patterns, one per line.
+- `TextArea`, monospace, placeholder `.env\n.env.*`
+- Saved on blur like the other fields. The textarea shows raw lines; on save, lines are
+  trimmed and blank lines / `#` comments dropped before storing as `string[]`.
+
+### IPC plumbing
+
+- `gitAddWorktreePayloadSchema` (`src/shared/contracts/git.ts`) gains
+  `copyIgnoredPatterns: z.array(z.string()).optional()`.
+- The renderer call site (`AppContent.tsx`, `gitAddWorktree` call) passes
+  `project.scripts?.worktreeCopyPatterns`.
+- `runtime.gitAddWorktree` forwards the field to `worktreeService.addWorktree`.
+
+### Copy step (supervisor)
+
+In `src/supervisor/git/worktreeService.ts`, after `git worktree add` succeeds and
+before returning:
+
+1. If no patterns, skip.
+2. Run `git ls-files --others --ignored --exclude-standard --directory` in the main
+   project to enumerate ignored entries (files, plus collapsed `dir/` entries for
+   fully-ignored directories).
+3. Filter entries with the existing `micromatch` dependency initialized from the
+   user's patterns.
+4. For each match, copy from main project to the same relative path in the new
+   worktree with `fs.cp` (`recursive: true` so matched directory entries copy whole).
+   Destination parent directories are created as needed. Existing destination files are
+   never overwritten (`force: false`).
+
+Path handling: posix and windows locations use the repo path directly; WSL locations
+use the UNC path, which Node `fs` on Windows can read and write.
+
+The matching/copy logic lives in a small helper module (e.g.
+`src/supervisor/git/copyIgnoredFiles.ts`) so it is unit-testable without a real
+worktree.
+
+### Error handling
+
+The copy step is non-fatal. Any failure (enumeration, matching, individual copy) is
+caught, logged with a warning, and worktree creation still returns success. A missing
+or empty pattern list is a no-op.
+
+### Testing
+
+- Unit tests for the helper: pattern filtering (`.env.*` matches `.env.local`, not
+  `node_modules/`), directory entries, no-overwrite behavior, empty/comment lines.
+- Extend the existing renderer test that asserts the `gitAddWorktree` payload
+  (`src/renderer/app.test.tsx`) to cover `copyIgnoredPatterns` being passed from
+  project settings.
+
+## Out of scope
+
+- Re-syncing files into existing worktrees after pattern changes.
+- A file-picker UI for selecting ignored files.
+- Copying files that live inside fully-ignored directories without matching the
+  directory itself (e.g. `dist/.env` when all of `dist/` is ignored — git collapses it
+  to `dist/`, so only a pattern matching `dist/` would copy it).

src/renderer/app.test.tsx

@@ -895,6 +895,7 @@ describe("App", () => {
             kind: "windows",
             path: "C:\\repo",
           },
+          scripts: { actions: [], worktreeCopyPatterns: [".env", ".env.*"] },
           createdAt: "2026-03-22T00:00:00.000Z",
         },
       ],
@@ -910,6 +911,7 @@ describe("App", () => {
         branch: "feature/x",
         createBranch: true,
         startPoint: "main",
+        copyIgnoredPatterns: [".env", ".env.*"],
       });
     });
 

src/renderer/views/MainView/parts/AppContent/AppContent.tsx

@@ -110,6 +110,7 @@ export function AppContent() {
           branch: worktreeBranch,
           createBranch: worktreeIsNewBranch ?? false,
           startPoint: worktreeBaseBranch,
+          copyIgnoredPatterns: project.scripts?.worktreeCopyPatterns,
         });
         worktreePath = result.path;
         newWorktreeSetupPath = result.path;

src/renderer/views/ProjectSettingsOverlay/parts/ScriptsSection.test.tsx

@@ -0,0 +1,57 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { beforeEach, describe, expect, it } from "vitest";
+import type { Project } from "@/shared/contracts";
+import { useAppStore } from "@/renderer/state/appStore";
+import { ScriptsSection } from "./ScriptsSection";
+
+function seedProject(overrides: Partial<Project> = {}) {
+  useAppStore.setState((state) => ({
+    ...state,
+    projects: [
+      {
+        id: "project-1",
+        name: "Repo",
+        location: { kind: "posix", path: "/repo" },
+        createdAt: "2026-06-10T00:00:00.000Z",
+        ...overrides,
+      },
+    ],
+  }));
+}
+
+describe("ScriptsSection copy ignored files", () => {
+  beforeEach(() => {
+    seedProject();
+  });
+
+  it("shows stored patterns one per line", () => {
+    seedProject({ scripts: { actions: [], worktreeCopyPatterns: [".env", ".env.*"] } });
+    render(<ScriptsSection projectId="project-1" />);
+
+    expect(screen.getByLabelText("Copy ignored files")).toHaveValue(".env\n.env.*");
+  });
+
+  it("saves parsed patterns on blur, dropping blanks and comments", () => {
+    render(<ScriptsSection projectId="project-1" />);
+
+    const textarea = screen.getByLabelText("Copy ignored files");
+    fireEvent.change(textarea, { target: { value: " .env \n\n# secrets\n.env.*" } });
+    fireEvent.blur(textarea);
+
+    expect(useAppStore.getState().projects[0]?.scripts?.worktreeCopyPatterns).toEqual([
+      ".env",
+      ".env.*",
+    ]);
+  });
+
+  it("clears the setting when the textarea is emptied", () => {
+    seedProject({ scripts: { actions: [], worktreeCopyPatterns: [".env"] } });
+    render(<ScriptsSection projectId="project-1" />);
+
+    const textarea = screen.getByLabelText("Copy ignored files");
+    fireEvent.change(textarea, { target: { value: "" } });
+    fireEvent.blur(textarea);
+
+    expect(useAppStore.getState().projects[0]?.scripts?.worktreeCopyPatterns).toBeUndefined();
+  });
+});

src/renderer/views/ProjectSettingsOverlay/parts/ScriptsSection.tsx

@@ -3,6 +3,7 @@ import type { ProjectScripts } from "@/shared/contracts";
 import { useAppStore } from "@/renderer/state/appStore";
 import { useProject } from "@/renderer/state/useThread";
 import { TextArea } from "@/renderer/components/common";
+import { parseCopyPatterns } from "@/shared/worktree";
 
 export function ScriptsSection(props: { projectId: string }) {
   const project = useProject(props.projectId);
@@ -11,6 +12,7 @@ export function ScriptsSection(props: { projectId: string }) {
   const scripts = project?.scripts ?? { actions: [] };
   const [setupScript, setSetupScript] = useState(scripts.setupScript ?? "");
   const [cleanupScript, setCleanupScript] = useState(scripts.cleanupScript ?? "");
+  const [copyPatterns, setCopyPatterns] = useState((scripts.worktreeCopyPatterns ?? []).join("\n"));
 
   if (!project) return null;
 
@@ -60,6 +62,28 @@ export function ScriptsSection(props: { projectId: string }) {
               onBlur={() => save({ cleanupScript: cleanupScript.trim() || undefined })}
             />
           </div>
+
+          <div className="space-y-2">
+            <div>
+              <p className="text-sm font-medium text-foreground">Copy ignored files</p>
+              <p className="text-xs text-muted">
+                Gitignored files to copy from the main project into each new worktree.
+                Gitignore-style patterns, one per line (e.g., <code>.env.*</code>).
+              </p>
+            </div>
+            <TextArea
+              aria-label="Copy ignored files"
+              className="w-full font-mono text-xs"
+              rows={3}
+              placeholder={".env\n.env.*"}
+              value={copyPatterns}
+              onChange={(e) => setCopyPatterns(e.target.value)}
+              onBlur={() => {
+                const patterns = parseCopyPatterns(copyPatterns);
+                save({ worktreeCopyPatterns: patterns.length > 0 ? patterns : undefined });
+              }}
+            />
+          </div>
         </div>
       </div>
     </div>

src/shared/contracts/git.ts

@@ -322,6 +322,8 @@ export const gitAddWorktreePayloadSchema = z.object({
   branch: z.string().optional(),
   createBranch: z.boolean().default(false),
   startPoint: z.string().optional(),
+  /** Gitignore-style patterns for ignored files to copy from the main project. */
+  copyIgnoredPatterns: z.array(z.string()).optional(),
 });
 export type GitAddWorktreePayload = z.infer<typeof gitAddWorktreePayloadSchema>;
 

src/shared/contracts/project.ts

@@ -13,6 +13,8 @@ export type ProjectAction = z.infer<typeof projectActionSchema>;
 export const projectScriptsSchema = z.object({
   setupScript: z.string().optional(),
   cleanupScript: z.string().optional(),
+  /** Gitignore-style patterns for ignored files to copy into new worktrees (e.g. `.env.*`). */
+  worktreeCopyPatterns: z.array(z.string()).optional(),
   actions: z.array(projectActionSchema).default([]),
 });
 export type ProjectScripts = z.infer<typeof projectScriptsSchema>;

src/shared/worktree.ts

@@ -22,6 +22,17 @@ export function sanitizeWorktreePathSegment(value: string): string {
   return sanitized || "project";
 }
 
+/**
+ * Parse the "copy ignored files" textarea into a clean pattern list:
+ * one gitignore-style pattern per line, blanks and `#` comments dropped.
+ */
+export function parseCopyPatterns(text: string): string[] {
+  return text
+    .split(/\r?\n/g)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && !line.startsWith("#"));
+}
+
 /**
  * Build a ProjectLocation pointing at a worktree directory.
  * Inherits kind/distro from the original project location.

src/supervisor/git.ts

@@ -299,8 +299,16 @@ export class GitService {
     branch?: string,
     createBranch?: boolean,
     startPoint?: string,
+    copyIgnoredPatterns?: string[],
   ): Promise<GitAddWorktreeResult> {
-    return this.worktreeService.addWorktree(location, path, branch, createBranch, startPoint);
+    return this.worktreeService.addWorktree(
+      location,
+      path,
+      branch,
+      createBranch,
+      startPoint,
+      copyIgnoredPatterns,
+    );
   }
 
   async removeWorktree(

src/supervisor/git/copyIgnoredFiles.test.ts

@@ -0,0 +1,115 @@
+/**
+ * Tests for the worktree "copy ignored files" step: pattern parsing,
+ * gitignore-style matching against `git ls-files` output, and the actual
+ * copy into a freshly created worktree. The copy test uses a real git repo
+ * in a temp directory so git decides which entries are actually ignored.
+ */
+
+import { mkdtemp, mkdir, readFile, rm, writeFile, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { execFile } from "node:child_process";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { parseCopyPatterns } from "@/shared/worktree";
+import { copyIgnoredFilesIntoWorktree, matchIgnoredCopyEntries } from "./copyIgnoredFiles";
+
+const execFileAsync = promisify(execFile);
+
+describe("parseCopyPatterns", () => {
+  it("splits lines, trims, and drops blanks and comments", () => {
+    expect(parseCopyPatterns("  .env  \n\n# comment\n.env.*\r\n")).toEqual([".env", ".env.*"]);
+  });
+
+  it("returns empty array for empty input", () => {
+    expect(parseCopyPatterns("")).toEqual([]);
+    expect(parseCopyPatterns("\n# only a comment\n")).toEqual([]);
+  });
+});
+
+describe("matchIgnoredCopyEntries", () => {
+  it("matches files with gitignore-style wildcards", () => {
+    expect(matchIgnoredCopyEntries([".env.local", "node_modules/"], [".env.*"])).toEqual([
+      ".env.local",
+    ]);
+  });
+
+  it("matches nested files for patterns without a slash", () => {
+    expect(matchIgnoredCopyEntries(["packages/app/.env", "dist/"], [".env"])).toEqual([
+      "packages/app/.env",
+    ]);
+  });
+
+  it("matches collapsed directory entries", () => {
+    expect(matchIgnoredCopyEntries(["secrets/", ".env"], ["secrets"])).toEqual(["secrets/"]);
+  });
+
+  it("matches collapsed directory entries with trailing-slash patterns", () => {
+    expect(matchIgnoredCopyEntries(["secrets/", ".env"], ["secrets/"])).toEqual(["secrets/"]);
+  });
+
+  it("returns nothing when patterns are empty", () => {
+    expect(matchIgnoredCopyEntries([".env"], [])).toEqual([]);
+  });
+});
+
+describe("copyIgnoredFilesIntoWorktree", () => {
+  let repoDir: string;
+  let worktreeDir: string;
+
+  beforeEach(async () => {
+    repoDir = await mkdtemp(join(tmpdir(), "lightcode-copy-src-"));
+    worktreeDir = await mkdtemp(join(tmpdir(), "lightcode-copy-dest-"));
+
+    await execFileAsync("git", ["init"], { cwd: repoDir });
+    await writeFile(join(repoDir, ".gitignore"), ".env*\nsecrets/\n");
+    await writeFile(join(repoDir, ".env"), "ROOT=1\n");
+    await writeFile(join(repoDir, ".env.local"), "LOCAL=1\n");
+    await mkdir(join(repoDir, "packages", "app"), { recursive: true });
+    await writeFile(join(repoDir, "packages", "app", ".env"), "NESTED=1\n");
+    await mkdir(join(repoDir, "secrets"), { recursive: true });
+    await writeFile(join(repoDir, "secrets", "key.pem"), "KEY\n");
+    await writeFile(join(repoDir, "tracked.ts"), "export {};\n");
+  });
+
+  afterEach(async () => {
+    await rm(repoDir, { recursive: true, force: true });
+    await rm(worktreeDir, { recursive: true, force: true });
+  });
+
+  function location() {
+    return { kind: "posix" as const, path: repoDir };
+  }
+
+  it("copies matching ignored files preserving relative paths", async () => {
+    await copyIgnoredFilesIntoWorktree(location(), worktreeDir, [".env", ".env.*"]);
+
+    expect(await readFile(join(worktreeDir, ".env"), "utf8")).toBe("ROOT=1\n");
+    expect(await readFile(join(worktreeDir, ".env.local"), "utf8")).toBe("LOCAL=1\n");
+    expect(await readFile(join(worktreeDir, "packages", "app", ".env"), "utf8")).toBe("NESTED=1\n");
+    await expect(stat(join(worktreeDir, "secrets"))).rejects.toThrow(/ENOENT/);
+    await expect(stat(join(worktreeDir, "tracked.ts"))).rejects.toThrow(/ENOENT/);
+  });
+
+  it("copies matched directories recursively", async () => {
+    await copyIgnoredFilesIntoWorktree(location(), worktreeDir, ["secrets"]);
+
+    expect(await readFile(join(worktreeDir, "secrets", "key.pem"), "utf8")).toBe("KEY\n");
+    await expect(stat(join(worktreeDir, ".env"))).rejects.toThrow(/ENOENT/);
+  });
+
+  it("never overwrites files that already exist in the worktree", async () => {
+    await writeFile(join(worktreeDir, ".env"), "EXISTING=1\n");
+
+    await copyIgnoredFilesIntoWorktree(location(), worktreeDir, [".env", ".env.*"]);
+
+    expect(await readFile(join(worktreeDir, ".env"), "utf8")).toBe("EXISTING=1\n");
+    expect(await readFile(join(worktreeDir, ".env.local"), "utf8")).toBe("LOCAL=1\n");
+  });
+
+  it("is a no-op when patterns are empty", async () => {
+    await copyIgnoredFilesIntoWorktree(location(), worktreeDir, []);
+
+    await expect(stat(join(worktreeDir, ".env"))).rejects.toThrow(/ENOENT/);
+  });
+});