[penberg]

The clonefile(2) man page says, under LIMITATIONS:

Cloning directories with these functions is strongly discouraged. Use copyfile(3) to clone directories instead.

The man page doesn't say why, but Apple's DTS does:

• Why is using clonefile for a folder strongly discouraged? (Kevin Elliott, DTS Engineer, accepted answer): cloning a directory pushes the copy into the kernel and "[prevents] all changes to the source hierarchy while the operation is in progress, making the process atomic. That second point is what makes this potentially dangerous as, in the worst case, you could theoretically panic the kernel by stalling all activity on critical locations long enough that the kernel 'gives up' and panics."
• Clarification on clonefile / copyfile support of clone directories?: the warning "only applies to directly using the clonefile function on directories, because it ties up the filesystem in ways that can be detrimental to the overall system health. On the other hand cloning directories recursively with copyfile is perfectly fine, because copyfile internally only calls clonefile on each file separately."

fsfork clones the directory an agent works in, often with target/ or node_modules in it, so it is the case this warns about.

Change

fsfork/darwin.rs clones with copyfile(COPYFILE_CLONE | COPYFILE_RECURSIVE), and makes up for what it does not do as clonefile did:

copyfile	so
copies into to if it exists	the clone is made at .<to>.<pid>.part and moved to to with renamex_np(RENAME_EXCL), so it fails if to exists (fork numbering relies on that), and to is never half made
fails with ENOTSUP on FIFOs and sockets	a status callback makes FIFOs anew and leaves sockets and devices out, as clone_entries already did beside what is ignored
makes symlinks after setting their directory's mtime	directory mtimes are set again once done
falls back to a full copy on another volume	that fails with EXDEV, as clonefile did
follows a symlink given as the source	entries that aren't directories are cloned without COPYFILE_RECURSIVE

A file deleted while the directory is being cloned is left out rather than failing the fork.

README and fsfork(1) say what changed, including that a fork is no longer one moment of the directory.

Trade-offs

• Not atomic: clonefile on a directory gave a point-in-time copy of the whole tree. Now, what is written to the directory while it is forked may be in the fork or not, each file by itself. The fork and its base are still the same, as the fork is cloned from the base.
• Slower: on this repo's target/ (6,838 entries, 386 MB), fsfork --no-ignore takes 2.1 s instead of 0.18 s, as Apple's "~10×" says.
• Leftovers: a fork killed while cloning leaves a hidden .<name>.<pid>.part next to it, which --prune doesn't remove.

Elliott says directory clonefile is fine on a hierarchy the app controls. The base is that (hidden, and nothing writes to it), so cloning the fork from the base with clonefile would win back half the time. I left that out to keep to the man page; say if you want it.

Testing

• cargo test: all pass, with a new test, copies_fifos_links_and_modification_times_deep_in_the_directory, which checks:
  • nested FIFOs, sockets and dangling symlinks
  • directory mtimes, which it fails without the fix
  • that no .part is left behind
• cargo clippy --all-targets: clean.