Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
fix: use per-file COW on macOS to avoid freezing shell (#640)
Maximilian Roos77ef8d22fd1f
diff --git a/.claude-plugin/skills/worktrunk/reference/step.md b/.claude-plugin/skills/worktrunk/reference/step.mdindex 5bf5c04d5..85405096f 100644--- a/.claude-plugin/skills/worktrunk/reference/step.md+++ b/.claude-plugin/skills/worktrunk/reference/step.md@@ -260,8 +260,7 @@ Only gitignored files are copied — tracked files are never touched. If `.workt### Features-- Uses copy-on-write (reflink) when available for fast, space-efficient copies-- On macOS, uses atomic directory cloning (`clonefile`) for 5x faster copies+- Uses copy-on-write (reflink) when available for space-efficient copies- Handles nested `.gitignore` files, global excludes, and `.git/info/exclude`- Skips existing files (safe to re-run)- Skips symlinks and `.git` entries@@ -272,12 +271,12 @@ Reflink copies share disk blocks until modified — no data is actually copied.| Command | Time ||---------|------|-| `cp -R ../main/target .` | 2m |-| `cp -Rc ../main/target .` | 20s |-| `wt step copy-ignored` (Linux) | 20s |-| `wt step copy-ignored` (macOS) | 4s |+| `cp -R` (full copy) | 2m |+| `cp -Rc` / `wt step copy-ignored` | 20s |-On Linux (Btrfs, XFS), performance matches `cp -Rc` — both use file-by-file reflink. On macOS (APFS), the `clonefile()` syscall clones entire directory trees atomically, avoiding per-file overhead.+Uses per-file reflink (like `cp -Rc`) — copy time scales with file count.++If the files are needed before any commands run in the worktree, put `wt step copy-ignored` in the `post-create` hook. Otherwise use the `post-start` hook so the copy runs in the background.### Language-specific notesdiff --git a/benches/cow_copy.rs b/benches/cow_copy.rsindex 380d615b7..af53461db 100644--- a/benches/cow_copy.rs+++ b/benches/cow_copy.rs@@ -1,8 +1,7 @@// Benchmarks for `wt step copy-ignored` COW directory copying//// Tests copy performance with realistic Rust target/ directory structures.-// On macOS, this uses atomic `clonefile()` syscall; on other platforms,-// file-by-file reflink.+// Uses file-by-file reflink copying on all platforms.//// Run:// cargo bench --bench cow_copy@@ -70,17 +69,10 @@ fn create_target_dir(file_count: usize) -> TempDir {/// Copy directory using the same approach as `wt step copy-ignored`.///-/// On macOS: atomic clonefile() then remove .git entries-/// On other platforms: file-by-file reflink+/// Uses file-by-file reflink on all platforms. We intentionally avoid atomic+/// directory cloning on macOS (via clonefile()) because it saturates disk I/O+/// and freezes interactive processes. See step_commands.rs for details.fn copy_dir_cow(src: &Path, dest: &Path) -> std::io::Result<()> {- #[cfg(target_os = "macos")]- {- if reflink_copy::reflink(src, dest).is_ok() {- return Ok(());- }- }-- // Fallback: file-by-filecopy_dir_recursive(src, dest)}diff --git a/docs/content/step.md b/docs/content/step.mdindex 62348f5ba..168e42025 100644--- a/docs/content/step.md+++ b/docs/content/step.md@@ -279,8 +279,7 @@ Only gitignored files are copied — tracked files are never touched. If `.workt### Features-- Uses copy-on-write (reflink) when available for fast, space-efficient copies-- On macOS, uses atomic directory cloning (`clonefile`) for 5x faster copies+- Uses copy-on-write (reflink) when available for space-efficient copies- Handles nested `.gitignore` files, global excludes, and `.git/info/exclude`- Skips existing files (safe to re-run)- Skips symlinks and `.git` entries@@ -291,12 +290,12 @@ Reflink copies share disk blocks until modified — no data is actually copied.| Command | Time ||---------|------|-| `cp -R ../main/target .` | 2m |-| `cp -Rc ../main/target .` | 20s |-| `wt step copy-ignored` (Linux) | 20s |-| `wt step copy-ignored` (macOS) | 4s |+| `cp -R` (full copy) | 2m |+| `cp -Rc` / `wt step copy-ignored` | 20s |-On Linux (Btrfs, XFS), performance matches `cp -Rc` — both use file-by-file reflink. On macOS (APFS), the `clonefile()` syscall clones entire directory trees atomically, avoiding per-file overhead.+Uses per-file reflink (like `cp -Rc`) — copy time scales with file count.++If the files are needed before any commands run in the worktree, put `wt step copy-ignored` in the `post-create` hook. Otherwise use the `post-start` hook so the copy runs in the background.### Language-specific notesdiff --git a/src/cli/step.rs b/src/cli/step.rsindex b9f539d35..c2320289b 100644--- a/src/cli/step.rs+++ b/src/cli/step.rs@@ -195,8 +195,7 @@ Only gitignored files are copied — tracked files are never touched. If `.workt## Features-- Uses copy-on-write (reflink) when available for fast, space-efficient copies-- On macOS, uses atomic directory cloning (`clonefile`) for 5x faster copies+- Uses copy-on-write (reflink) when available for space-efficient copies- Handles nested `.gitignore` files, global excludes, and `.git/info/exclude`- Skips existing files (safe to re-run)- Skips symlinks and `.git` entries@@ -207,12 +206,12 @@ Reflink copies share disk blocks until modified — no data is actually copied.| Command | Time ||---------|------|-| `cp -R ../main/target .` | 2m |-| `cp -Rc ../main/target .` | 20s |-| `wt step copy-ignored` (Linux) | 20s |-| `wt step copy-ignored` (macOS) | 4s |+| `cp -R` (full copy) | 2m |+| `cp -Rc` / `wt step copy-ignored` | 20s |-On Linux (Btrfs, XFS), performance matches `cp -Rc` — both use file-by-file reflink. On macOS (APFS), the `clonefile()` syscall clones entire directory trees atomically, avoiding per-file overhead.+Uses per-file reflink (like `cp -Rc`) — copy time scales with file count.++If the files are needed before any commands run in the worktree, put `wt step copy-ignored` in the `post-create` hook. Otherwise use the `post-start` hook so the copy runs in the background.## Language-specific notesdiff --git a/src/commands/step_commands.rs b/src/commands/step_commands.rsindex 100a708f5..fc7ccb347 100644--- a/src/commands/step_commands.rs+++ b/src/commands/step_commands.rs@@ -608,30 +608,30 @@ fn list_ignored_entries(/// Copy a directory recursively using reflink (COW).///-/// On macOS/APFS, attempts atomic directory clone first via `clonefile()` syscall,-/// which is O(1) regardless of file count. Falls back to file-by-file copying on-/// other platforms or when atomic clone fails.+/// Uses file-by-file copying with per-file reflink on all platforms. This spreads+/// I/O operations over time rather than issuing them in a single burst.+///+/// ## Why not use atomic directory cloning on macOS?+///+/// macOS/APFS supports `clonefile()` on directories, which clones an entire tree+/// atomically. However, Apple's documentation explicitly discourages this:+///+/// > "Directories can be cloned just as easily as regular files. However, when+/// > cloning a directory hierarchy [...] the kernel must create a separate inode+/// > for each item in the tree (even though no data is being duplicated). For+/// > large hierarchies, this can require significant disk I/O, which defeats the+/// > purpose of cloning a file rather than simply copying it."+/// > — Apple Developer Documentation: Cloning Files and Directories+/// > <https://developer.apple.com/documentation/foundation/file_system/cloning_files_and_directories>+///+/// In practice, atomic `clonefile()` on a Rust `target/` directory (~236K files)+/// saturates disk I/O at ~45K ops/sec, blocking interactive processes like shell+/// startup for several seconds. The per-file approach spreads operations over+/// time, keeping the system responsive even though total copy time is longer.+///+/// Apple recommends `copyfile()` with `COPYFILE_CLONE` for directories, which+/// internally walks the tree and clones per-file — equivalent to what we do here.fn copy_dir_recursive(src: &Path, dest: &Path) -> anyhow::Result<()> {- // On macOS, try atomic directory clone first (single syscall for entire tree)- // This is dramatically faster for large directories like target/ with 100k+ files- #[cfg(target_os = "macos")]- {- use std::io::ErrorKind;-- // reflink::reflink() on macOS uses clonefile() which supports directories- match reflink_copy::reflink(src, dest) {- Ok(()) => return Ok(()),- Err(e) if e.kind() == ErrorKind::AlreadyExists => {- // Destination exists - fall through to file-by-file for idempotent merging- }- Err(e) => {- // clonefile failed (cross-device, not APFS, etc.) - fall through- log::debug!("Atomic directory clone failed, using file-by-file fallback: {e}");- }- }- }-- // Fallback: file-by-file copying (works on all platforms)copy_dir_recursive_fallback(src, dest)}