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 throughstd::fs::copy, which reachesclonefileon APFS andcopy_file_rangeon 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.
§Symlinks
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. - Path
Error - Downcast target for structured error context.
- Progress
- A progress snapshot passed to the callback of
copy_tree_with_progressandmove_tree_with_progress. - Summary
- Counts returned by a completed copy or move.
Enums§
- Op
- The operation step a
PathErrorhappened in. - Overwrite
- What to do when a destination entry already exists.
Functions§
- copy_
tree - Recursively copy the directory tree at
srctodst. - copy_
tree_ with_ progress copy_treewith a progress callback.- move_
tree - Move the directory tree at
srctodstwithout ever endangeringsrc. - move_
tree_ with_ progress move_treewith a progress callback.- remove_
tree - Recursively remove the tree at
path. - tree_
size - Total size in bytes of the tree at
path.