Configurable worktree include: bring git-ignored files in, carry untracked files back on merge

[FourWindff]

Background & motivation

A git worktree only contains tracked files, so ignored files never appear in a new worktree. Under AI-driven workflows this causes two pain points:

1. Broken context: AI workflows often generate documents in the repo root (plans, design notes, context files). We usually don't want to commit them, so we ignore them via .gitignore — but agents working inside a worktree need exactly those documents to keep context consistent.
2. Lost output: untracked files an agent newly creates inside a worktree (e.g. docs/xxx.md) are permanently lost when the task is merged and the worktree is removed.

Today parallel-code works around this with a hardcoded allowlist (SYMLINK_CANDIDATES, only 8 entries such as .env and node_modules) that gets symlinked into each worktree. It cannot cover user-defined ignored files.

Proposal

Make worktree creation and merge behavior configurable per task:

1. On task creation: let the user check which ignored files/directories to bring into the worktree (e.g. .env, docs/), and choose how each entry is brought in:
   • Symlink: shared with the main checkout (good for large directories that don't need isolation, like node_modules);
   • Copy: an independent copy inside the worktree (good for documents the agent may modify, like .env).
2. On task merge: optionally carry untracked files newly created inside the worktree (e.g. docs/xxx.md) back into the project root, so output isn't lost when the worktree is removed.

Relationship to Claude Code's .worktreeinclude

Claude Code's .worktreeinclude solves a similar problem, but it only copies ignored files one way, at creation time; they are deleted together with the worktree on cleanup and never carried back to the main checkout. This proposal extends that idea with:

• a per-entry choice of symlink vs. copy (symlink avoids the copy cost of large directories like node_modules; copy guarantees isolation);
• carrying untracked files created in the worktree back to the project root on merge, preventing output loss.

Implementation sketch

• Enumeration: git ls-files --others --ignored --exclude-standard --directory, collapsed to top-level entries of the repo root. A single command covers all ignore mechanisms (.gitignore, nested gitignores, .git/info/exclude, global excludesFile) — no need to parse gitignore syntax ourselves. .worktrees/ and .git must be force-excluded (to avoid linking the worktree directory into itself).
• Creation: symlink or copy each checked entry according to its config.
• Merge: in mergeTask(), before removeWorktree, copy the entries marked as "carry back" from the worktree to the project root.
• This feature can replace the existing hardcoded SYMLINK_CANDIDATES allowlist.

Open questions

• Where should the configuration live: a .worktreeinclude-style file inside the repo (shareable via git, compatible with Claude Code conventions) vs. an in-app per-project setting?
• On carry-back in copy mode, if the same file was also modified in the main checkout, how should conflicts be handled (overwrite / skip with a warning / keep both)?
• Default selection policy (large ignored directories like dist/ should presumably not be copied by default?)

[johannesjo]

Thanks for the writeup — the diagnosis is accurate and the .worktreeinclude comparison is useful framing. I verified the premises against the code and they hold: SYMLINK_CANDIDATES really is 8 hardcoded names, so user-defined ignored paths can't be selected, and the picker UI already exists — so widening this is a smaller change than it looks.

I'd like to state a direction before we settle the design, since it answers several of your open questions at once.

Direction: worktrees stay ephemeral

Isolation is the point of the feature. A worktree is a sandbox, and anything crossing that boundary — in or out — should be something the user consciously chose, not something that happens implicitly. Applying that:

Bringing ignored files in — yes, let's extend this. The user is already explicitly checking boxes; today the list is just too short to be useful. This is the part I'd like to move on.

Automatic carry-back on merge — I'd rather not. Copying files into the project root as a side effect of merging is an implicit crossing, and one git can't undo (the files are ignored, so there's nothing to revert to). Your own open question about conflict handling is the tell: overwrite loses main's version, skip silently loses agent output, keep-both litters the repo. When every option is wrong some of the time, that's a sign the step shouldn't be automatic.

But the underlying problem is real, and worth solving in a way that fits the principle: right now, worktree deletion silently destroys ignored files with no warning. Untracked-but-visible files already trigger a warning in the close dialog (git status --porcelain sees them); ignored ones are invisible to it, and merge-with-cleanup skips the check entirely. So the conscious-decision version of your part 2 is: before deleting a worktree, show what's about to be destroyed — including ignored files — and let the user act on it. Same enumeration work, same exclusion list, but the user makes the call rather than a conflict policy making it for them.

One finding that affects your implementation sketch

I measured the proposed enumeration command against two repos: 26 entries here, 1207 in another. --directory only collapses directories that are entirely ignored — where ignored files sit under a tracked directory, you get every file individually (src/ alone was 938).

That breaks the "collapse to top-level entries" step: it turns those 938 into a single src/ checkbox, but src/ is a tracked directory that already exists in the worktree, so selecting it silently does nothing. I think the fix is small — enumerate only paths where the entire top-level entry is ignored (node_modules/, dist/, .env), and treat ignored files nested under tracked directories as out of scope. That set is small and stable: 9 here, ~14 in the other repo.

Implementation constraints worth knowing before writing code

• .git/info/exclude growth is a one-way door. ensureSymlinkExcludes writes to --git-common-dir — the main repo's exclude file — permanently, with no removal path (electron/ipc/git-exclude.ts:8). Enumerating 30 entries means appending 30 permanent lines to the user's repo config that a later version can't reliably clean up. Another reason to keep the enumerated set small.
• Nested paths are silently skipped. createWorktree rejects any name containing / (electron/ipc/git.ts:802), and ensureSymlinkExcludes root-anchors as /${name}. No error, no UI feedback. git-symlink-excludes.test.ts pins that format.
• Defaults need care. Both entry points currently check everything enumerated by default — NewTaskDialog.tsx:611 (setSelectedDirs(new Set(dirs))) and remoteTaskHandler.ts:57 (no confirmation at all). Widening enumeration without touching those means every new task starts symlinking dist/ and release/. I'd keep the current 8 checked by default and start newly-enumerated entries unchecked.
• symlinkDirs isn't persisted. It exists only as a createTask argument, not as a field on Task. Per-entry modes would need a new persisted shape.
• Two other places bypass the picker entirely: mcp/coordinator.ts:816 hardcodes ['.claude','node_modules'] and arena hardcodes ['node_modules']. Not blockers, but they shouldn't drift further apart.
• No test coverage currently exists on createWorktree, removeWorktree, or getGitIgnoredDirs.

Open for discussion

Symlink vs. copy — should it be in the first change, or a follow-up? Genuinely unsure. Argument for including it: symlinking is itself a quiet boundary crossing. An agent writing .env in a worktree writes through the symlink into the main checkout, affecting the main repo and every concurrent task — which is exactly the kind of unconscious crossing the principle above is meant to prevent. So copy mode isn't only about convenience. Argument against: "widen the list" is a ~20-line change to getGitIgnoredDirs that could ship quickly, while copy mode needs persisted per-entry state. Splitting them might get value out sooner.

Config location — my current lean is an in-app per-project setting rather than a repo file, since the selection is per-task and symlink-vs-copy is machine-local (my node_modules isn't yours). But reading .worktreeinclude as a default seed for the checkboxes seems like cheap Claude Code compat. Open to arguments the other way.

@FourWindff — if you'd like to take the enumeration-widening part, that'd be very welcome. And I'd like to hear from others on the ephemeral-by-default stance before we commit to it, particularly anyone who's actually lost agent output this way — if that's happening often, it's an argument I want to hear.

[FourWindff]

Thanks for the detailed reply — I fully agree with the direction. Here's where I've landed:

On splitting: Agreed, two PRs. The first PR only widens the enumeration — exactly as you described: only enumerate paths where the entire top-level entry is ignored, and treat ignored files nested under tracked directories as out of scope. It will also keep the current 8 SYMLINK_CANDIDATES checked by default while newly enumerated entries start unchecked, with consistent behavior across both entry points (NewTaskDialog and remoteTaskHandler). I'll add test coverage for getGitIgnoredDirs / createWorktree along the way.

On config location: Agreed on an in-app per-project setting, for the same reasons you gave — the selection is per-task, and symlink-vs-copy is a machine-local decision that doesn't belong in a repo file. Reading .worktreeinclude as a default seed for the checkboxes is a nice, cheap bit of compatibility, but I'd leave it as a follow-up optimization rather than including it in the first PR, to keep the scope tight.

On symlink-vs-copy and carrying untracked files back: I'm working on a unified design for these two. I'll post the design in this issue for discussion before writing any code, and target it for the second PR.

On automatic carry-back on merge: Your ephemeral-by-default principle convinced me — the conflict policy really is unsolvable. The alternative you proposed (showing what's about to be destroyed, including ignored files, before worktree deletion) makes sense to me, and the enumeration work it needs is the same as in the first PR, so they should connect naturally.

I'll get started on the first PR.