Skip to main content

Crate dir_tree_ops

Crate dir_tree_ops 

Source
Expand description

Tree operations on directories: copy, move, remove, and size.

Four operations over AsRef<Path> roots, plus progress-reporting variants for copy and move:

  • copy_tree: recursive copy with a streaming, iterative walk and no whole-tree snapshot. Regular files go through std::fs::copy, which reaches clonefile on APFS and copy_file_range on Linux.
  • move_tree: rename first, staged copy fallback when the rename cannot apply. The source stays unchanged until the destination is complete and durable.
  • remove_tree: recursive remove that treats symlinks as leaves.
  • tree_size: byte lengths of regular files plus symlink target lengths. Directories contribute zero, and links are leaves.

§Destination semantics

dst names the resulting root: copy_tree("a/src", "b/dest", ..) makes b/dest a replica of a/src. There is no name-appending, so a first and a second run produce the same shape. The mapping is src/<rel> to dst/<rel>, always, matching rsync -a src/ dst/. The parent of dst must already exist, and a missing parent is NotFound naming the parent. If dst exists as a directory, a copy merges into it with per-entry conflict handling from Options::overwrite.

§Overlap

Every operation resolves both roots before touching anything. dst equal to src, dst inside src, and src inside dst are all rejected with InvalidInput carrying a PathError with op Op::Scan and both paths. Resolution canonicalizes the existing portion of each path, and on Unix also compares (dev, ino) along each path, so a symlink alias or a bind mount of one root counts as the same tree. Inside the walk, an existing destination entry is removed only after its identity is checked against every source entry, and the source is removed only by the last step of a move.

A symlink copies as a symlink. Every entry is classified through symlink_metadata, the target string is reproduced verbatim (relative stays relative, absolute stays absolute), and the walker treats each link as a leaf. A dangling link copies as the same dangling link and is counted in Summary::symlinks. remove_tree deletes a link as a link, so the tree behind it survives.

§Move safety

move_tree runs in ordered phases: a rename attempt before any read of the source, then (only on a cross-device failure or when replacing an existing destination) a staged copy into a hidden sibling of the final destination with files fsynced and directories fsynced on Unix, a finalize rename, and only then removal of the source. A failure in any phase before source removal returns the error with the source unchanged, the destination as it was, and no hidden sibling left behind. A failure during source removal reports Op::RemoveSource. The destination is already complete at that point, so no bytes are lost and the call can be retried.

§Errors

Every operation returns std::io::Result. The io::ErrorKind of the underlying filesystem failure is preserved, and its payload is a PathError carrying the operation step and the path (or paths) involved. Downcast via err.get_ref() to read them. Invalid options return InvalidInput before any filesystem access.

§TOCTOU stance

There are no exists() pre-flight checks: existence is learned from each operation’s own syscall result. Progress copies claim a destination file with create_new. Non-progress copies check the entry just before std::fs::copy, which is required for clone-capable filesystem copying. Source files open with O_NOFOLLOW on Linux, Android, and the BSD family including macOS. On other Unix targets the open is followed by an fstat identity check against the symlink_metadata taken just before, and on Windows the handle is opened on the reparse point itself and rejected if it is a link. Each of those fails closed when an entry is swapped for a link between classification and open. The fast copy path verifies that the no-follow handle has the identity seen by the directory scan. std::fs::copy then reads the source through its own path-following open, so after it returns the path is re-opened no-follow and compared against that handle. On a mismatch, or when the re-open fails, the new destination file is removed and the call fails with InvalidInput. A swap reverted to the original file before the re-check is not detected. Full elimination needs openat-style traversal, which std does not portably expose. Residual and documented: a caller that lets another process replace whole directories on the traversal path can still redirect descent. Trees under shared writable parents need stronger isolation than this API provides.

§Non-goals (v1)

mtime, ownership, and xattr preservation, a follow-links mode, cancellation from the progress callback, single-file helpers, and async. FIFOs, sockets, and device nodes are carried by the rename fast path of a move and report io::ErrorKind::Unsupported naming the path when they have to be copied.

Structs§

Options
Options for copy_tree, move_tree, and their progress variants.
PathError
Downcast target for structured error context.
Progress
A progress snapshot passed to the callback of copy_tree_with_progress and move_tree_with_progress.
Summary
Counts returned by a completed copy or move.

Enums§

Op
The operation step a PathError happened in.
Overwrite
What to do when a destination entry already exists.

Functions§

copy_tree
Recursively copy the directory tree at src to dst.
copy_tree_with_progress
copy_tree with a progress callback.
move_tree
Move the directory tree at src to dst without ever endangering src.
move_tree_with_progress
move_tree with a progress callback.
remove_tree
Recursively remove the tree at path.
tree_size
Total size in bytes of the tree at path.