Skip to content

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.md
index 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 notes
diff --git a/benches/cow_copy.rs b/benches/cow_copy.rs
index 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-file
copy_dir_recursive(src, dest)
}
diff --git a/docs/content/step.md b/docs/content/step.md
index 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 notes
diff --git a/src/cli/step.rs b/src/cli/step.rs
index 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 notes
diff --git a/src/commands/step_commands.rs b/src/commands/step_commands.rs
index 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)
}