Crate clonetree

Crate clonetree 

Source
Expand description

A library for efficiently cloning directory trees with copy-on-write support.

This crate provides functionality to clone entire directory structures while leveraging filesystem-level copy-on-write (CoW) capabilities when available through reflinks. This can result in significant space savings and improved performance compared to traditional file copying.

§Features

  • Copy-on-Write Support: Automatically uses reflinks when available on supported filesystems (Btrfs, XFS, APFS, etc.)
  • Symlink Preservation: Symbolic links are recreated with their original targets
  • Empty Directory Preservation: Empty directories in the source tree are preserved
  • Glob Filtering: Include or exclude files using glob patterns
  • Efficient Traversal: Built on the ignore crate for fast directory walking
  • Type-Safe Errors: Comprehensive error handling with descriptive error types

§Example

use clonetree::{clone_tree, Options};

// Clone a directory tree
let options = Options::new();
clone_tree("/source/path", "/destination/path", &options)?;

// Clone with glob filters
let options = Options::new()
    .glob("**/*.rs")      // Include only Rust files
    .glob("!target/**");  // Exclude target directory
clone_tree("/source", "/dest", &options)?;

§Validation

The clone_tree function enforces the following constraints:

  • Source path must exist and be a directory
  • Destination path must not exist

These constraints are validated before any filesystem operations begin. If you need to replace an existing destination, remove it first with std::fs::remove_dir_all.

Symbolic links in the source tree are preserved as symbolic links in the destination. The link targets are copied verbatim (not resolved), so relative symlinks maintain their relative paths.

  • FullTraversal strategy: Symlinks are recreated using platform-native symlink creation (symlink(2) on Unix, CreateSymbolicLink on Windows).
  • SingleCall strategy (macOS only): The kernel’s clonefile(2) preserves symlinks automatically as part of the atomic directory clone.

§Concurrency Considerations

The validation checks (source exists, destination does not exist) and the actual clone operation are not atomic. This creates a time-of-check to time-of-use (TOCTOU) race window where:

  • Another process could create the destination after validation but before cloning
  • Another process could modify or delete the source during traversal

Strategy-specific behavior:

  • SingleCall strategy (macOS): The clonefile(2) syscall is atomic—if the destination is created by another process first, cloning will fail with an I/O error rather than corrupting data.

  • FullTraversal strategy: Not atomic. Concurrent destination creation may result in partial writes or merged directory contents. Source modifications during traversal may cause some files to be skipped or fail to copy.

For concurrent scenarios, callers should implement their own synchronization (e.g., file locks, exclusive access to the destination parent directory).

Structs§

Options
Builder-style options that control cloning behaviour.

Enums§

CloneStrategy
Strategy used when cloning a directory tree.
Error
Errors that can occur while cloning directory trees.

Functions§

clone_tree
Clone a directory tree from src to dest using the provided options. Validates inputs up-front and selects the appropriate cloning strategy.

Type Aliases§

Result
Convenience result type for clonetree operations.