[ENHANCEMENT] Utilize hard links for file copies when processing .worktreeinclude

[draxxris]

Problem (one or two sentences)

When using .worktreeinclude to copy gitignored directories (such as node_modules or build artifacts) to a new worktree, Roo Code performs a full file copy of the entire directory. For large directories that can span many gigabytes, this results in:

• Slow worktree creation - copying gigabytes of data takes considerable time
• Excessive disk usage - each worktree duplicates the same files, multiplying storage consumption
• Unnecessary I/O wear - full copies stress storage devices unnecessarily

Context (who is affected and when)

This affects any developer who:

• Works with large gitignored directories (e.g., node_modules, .venv, build outputs, cache directories)
• Uses the worktree feature to parallelize work across multiple branches
• Has limited disk space or slow storage (HDDs, network drives)
• Frequently creates and destroys worktrees as part of their workflow
• The impact is most noticeable when the .worktreeinclude patterns match directories containing thousands of files or multiple gigabytes of data. A typical node_modules directory in a large project can easily exceed 1-2 GB with tens of thousands of files.

Desired behavior (conceptual, not technical)

When copying files matching .worktreeinclude patterns to a new worktree, the system should use hard links instead of full copies when the filesystem supports them. Hard links create additional directory entries pointing to the same underlying data.

A checkbox could be added to the worktree GUI to make hard links optional, if necessary.

Constraints / preferences (optional)

No response

Request checklist

• I've searched existing Issues and Discussions for duplicates
• This describes a specific problem with clear context and impact

Roo Code Task Links (optional)

No response

Acceptance criteria (optional)

No response

Proposed approach (optional)

No response

Trade-offs / risks (optional)

No response

[draxxris]

File Copying Mechanism
For individual files (line 197):
await fs.copyFile(sourcePath, targetPath)
This uses Node.js's fs.copyFile() which creates a true copy of the file data.

For directories (lines 314-318):

if (isWindows) {
    proc = spawn("robocopy", [source, target, "/E", "/NFL", "/NDL", "/NJH", "/NJS", "/NC", "/NS", "/NP"], ...)
} else {
    proc = spawn("cp", ["-r", "--", source, target])
}

• Unix/Linux/macOS: Uses cp -r which creates actual copies. To create hardlinks, it would need to use cp -al (archive with hardlinks).
• Windows: Uses robocopy without the /SL flag. The /SL flag would be needed to create hardlinks instead of copies.

[roomote]

I've analyzed this issue and here's my proposed implementation plan:

Summary

Replace full file copies with hard links when processing .worktreeinclude patterns. Hard links avoid duplicating file data on disk, making worktree creation faster and more space-efficient. A fallback to regular copy is included for cross-device scenarios or unsupported filesystems.

Changes

1. Add useHardLinks option to copyWorktreeIncludeFiles in packages/core/src/worktree/worktree-include.ts

• Add an optional useHardLinks?: boolean parameter to copyWorktreeIncludeFiles.
• For individual files: when useHardLinks is true, use fs.link() (hard link) instead of fs.copyFile(). If fs.link() fails (e.g., cross-device or permissions), fall back to fs.copyFile().
• For directories: instead of spawning cp -r / robocopy, recursively walk the source directory and hard-link each file individually (creating the directory structure with fs.mkdir). This is necessary because there is no native OS command for recursive hard-linking. Fall back to the existing copy-based approach if hard-linking fails.
• Progress reporting remains the same.

2. Add useHardLinks option to CreateWorktreeOptions in packages/types/src/worktree.ts

• Add useHardLinks?: boolean to the existing WorktreeIncludeStatus or pass it through the handler. Actually, since this is a copy-time option rather than a worktree-creation option, it makes more sense to thread it through the handler call.

3. Thread the option through the handler in src/core/webview/worktree/handlers.ts

• Accept useHardLinks from the webview message and pass it to worktreeIncludeService.copyWorktreeIncludeFiles.

4. Add a checkbox in the webview UI (webview-ui/src/components/worktrees/CreateWorktreeModal.tsx)

• Add a "Use hard links for included files" checkbox (defaulting to true) that sends the useHardLinks flag when creating a worktree.
• Add a brief tooltip explaining what hard links are and when to disable them (e.g., if source and target are on different filesystems).

5. Thread the option through the message types in packages/types/src/vscode-extension-host.ts

• Add worktreeUseHardLinks?: boolean to the webview message payload.

6. Update tests in packages/core/src/worktree/__tests__/worktree-include.spec.ts

• Add tests for hard-link behavior: successful hard-link for files, fallback to copy on failure, recursive hard-linking for directories.

Key design decisions

• Default to true: Hard links are safe for read-only dependencies like node_modules and offer significant performance/space benefits. The fallback ensures it never breaks.
• Per-file fallback: If a single hard link fails, only that file falls back to copy -- the rest still benefit from hard links.
• No symlinks: Hard links are preferred over symlinks because they work transparently with all tools and don't break when the source is removed.

Please mention @roomote in a comment saying that you approve this plan, and I'll proceed with the implementation.

[draxxris]

That looks good @roomote

[roomote]

Thanks for the approval @polski-g! I've seen your comment and will proceed with the implementation. I'll open a draft PR to share progress shortly.

[roomote]

Opened a draft PR with my attempt at addressing this: #11760

The implementation adds hard link support with per-file fallback to regular copies, a checkbox in the Create Worktree modal, and 5 new tests. Feedback welcome!

[draxxris]

@roomote that PR is missing translation files necessary for the CI tests to pass.

[roomote]

I've seen your comment about missing translation files @polski-g. I'll look into what's needed and push an update to the PR.

[roomote]

Added the missing translation files for useHardLinks and useHardLinksTooltip across all 17 non-English locales (ca, de, es, fr, hi, id, it, ja, ko, nl, pl, pt-BR, ru, tr, vi, zh-CN, zh-TW). The missing translations script now reports all clear. Changes pushed to PR #11760.