Skip to content

feat: use hard links for file copies when processing .worktreeinclude#11760

Draft
roomote[bot] wants to merge 2 commits intomainfrom
feature/worktree-hardlinks
Draft

feat: use hard links for file copies when processing .worktreeinclude#11760
roomote[bot] wants to merge 2 commits intomainfrom
feature/worktree-hardlinks

Conversation

@roomote
Copy link
Contributor

@roomote roomote bot commented Feb 26, 2026

Related GitHub Issue

Closes: #11758

Description

This PR attempts to address Issue #11758. Feedback and guidance are welcome.

When creating worktrees with .worktreeinclude patterns, the system now supports using hard links instead of full file copies. Hard links point to the same underlying data on disk, which means:

  • Faster worktree creation -- no data duplication needed
  • Reduced disk usage -- each worktree shares the same file data
  • Less I/O wear -- no unnecessary read/write cycles

Key implementation details:

  • Added useHardLinks optional parameter to copyWorktreeIncludeFiles in packages/core/src/worktree/worktree-include.ts
  • For individual files: uses fs.link() with automatic fallback to fs.copyFile() if hard linking fails (e.g., cross-device)
  • For directories: recursively walks the source and hard-links each file, creating the directory structure along the way. Falls back to the existing native copy approach if hard-linking fails entirely
  • Per-file fallback: if a single hard link fails, only that file falls back to copy
  • Added a "Use hard links for included files" checkbox in the Create Worktree modal (defaults to checked, only visible when .worktreeinclude exists)
  • Threaded the option through message types and handlers

Test Procedure

  • Added 5 new tests to packages/core/src/worktree/__tests__/worktree-include.spec.ts:
    • Hard-link single files (verifies same inode)
    • Hard-link directory contents recursively (verifies same inode)
    • Fallback to copy when hard link fails
    • Regular copies when useHardLinks is false (verifies different inode)
    • Progress reporting during hard-link operations
  • All 25 tests pass (20 existing + 5 new)
  • Lint and type-check pass across all packages

Pre-Submission Checklist

  • Issue Linked: This PR is linked to an approved GitHub Issue (see "Related GitHub Issue" above).
  • Scope: My changes are focused on the linked issue (one major feature/fix per PR).
  • Self-Review: I have performed a thorough self-review of my code.
  • Testing: New and/or updated tests have been added to cover my changes (if applicable).
  • Documentation Impact: I have considered if my changes require documentation updates (see "Documentation Updates" section below).
  • Contribution Guidelines: I have read and agree to the Contributor Guidelines.

Documentation Updates

  • No documentation updates are required.

Additional Notes

  • The checkbox only appears when a .worktreeinclude file exists in the repository
  • Hard links are safe for read-only dependencies like node_modules and offer significant performance/space benefits
  • No symlinks are used -- hard links work transparently with all tools and do not break when the source is removed

Interactively review PR in Roo Code Cloud

Adds an optional useHardLinks parameter to copyWorktreeIncludeFiles that
creates hard links instead of full copies when the filesystem supports them.
This saves disk space and speeds up worktree creation for large directories
like node_modules.

- Add hardLinkWithFallback method that falls back to copy on failure
- Add hardLinkDirectoryRecursive for recursive directory hard-linking
- Thread useHardLinks option through handler and message types
- Add "Use hard links" checkbox to CreateWorktreeModal (defaults to on)
- Add i18n keys for the new UI elements
- Add tests for hard link behavior including inode verification

Closes #11758
@draxxris
Copy link

@roomote can you add the necessary translations to the locale files?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

2 participants