Crate parcopy 

parcopy

Parallel, atomic, and safe file/directory copying for Rust.

Core Features

• Parallel copying: Uses rayon for concurrent file operations, optimized for NFS/network storage
• Atomic writes: Uses temp file + rename pattern to ensure no partial files
• TOCTOU safe: Uses persist_noclobber to prevent race conditions
• Symlink aware: Correctly handles symlinks without following them
• Symlink loop detection: Prevents infinite recursion from circular symlinks
• Resumable: Skips already-existing files for interrupted operations
• Permission preserving: Copies file and directory permissions
• Timestamp preserving: Copies file modification and access times
• Incremental copy: Only copy files newer than destination (UpdateNewer)
• Reflink support: Instant copy-on-write on btrfs/XFS/APFS
• Security hardened: Detects and optionally blocks escaping symlinks
• Windows attribute preserving: Copies hidden, system, archive attributes on Windows

Quick Start with Builder API

The easiest way to use parcopy is with the CopyBuilder:

use parcopy::CopyBuilder;

// Simple copy with smart defaults
let stats = CopyBuilder::new("src", "dst").run()?;
println!("Copied {} files ({} bytes)", stats.files_copied, stats.bytes_copied);

Incremental Backup

use parcopy::CopyBuilder;

// Only copy files that have changed
let stats = CopyBuilder::new("project", "backup")
    .update_newer()
    .run()?;

println!("Updated {} files, {} already up-to-date",
    stats.files_copied, stats.files_skipped);

High-Performance Copy

use parcopy::CopyBuilder;

let stats = CopyBuilder::new("data", "backup")
    .parallel(32)      // More threads for NFS
    .overwrite()       // Replace existing
    .no_fsync()        // Skip fsync for speed
    .run()?;

Function API

For more control, use the function API with CopyOptions:

use parcopy::{copy_dir, CopyOptions, OnConflict};
use std::path::Path;

let options = CopyOptions::default()
    .with_parallel(8)                         // Limit parallelism
    .with_on_conflict(OnConflict::Overwrite)  // Overwrite existing
    .with_max_depth(100)                      // Limit recursion depth
    .with_block_escaping_symlinks()           // Block dangerous symlinks
    .without_fsync();                         // Faster but less durable

let stats = copy_dir(Path::new("src"), Path::new("dst"), &options)?;
println!("Copied {} files, skipped {}", stats.files_copied, stats.files_skipped);

Safety Guarantees

Atomic Writes

Files are written to a temporary file in the destination directory, then renamed atomically. This ensures no partial files exist if interrupted.

TOCTOU Protection

Uses persist_noclobber (backed by renameat2(RENAME_NOREPLACE) on Linux) to atomically fail if destination was created between existence check and rename.

Symlink Safety

• Symlinks are never followed during directory traversal
• Symlink loops are detected and reported as Error::SymlinkLoop
• Escaping symlinks (../) are warned or blocked based on configuration

Optional Features

Feature	Description
progress	Progress bar support with indicatif
tracing	Structured logging with tracing crate
serde	Serialize/Deserialize for CopyOptions
full	Enable all optional features

NFS Optimization

This crate is specifically optimized for NFS and network filesystems where many small files cause metadata storms. By parallelizing file operations, we can have multiple NFS RPCs in-flight simultaneously, significantly improving throughput. Default parallelism is 16 concurrent operations.

Structs

CopyBuilder

A builder for configuring and executing copy operations.

CopyOptions

Options for copy operations.

CopyPlan

A reusable copy plan generated by plan_copy.

CopyPolicy

Copy behavior policy (semantic behavior, not runtime tuning).

CopyReport

Structured execution report returned by execute_plan.

CopyStats

Statistics from a copy operation.

ErrorCodeSpec

Human-readable metadata for one stable error code.

ItemReport

Per-item execution report.

PlannedItem

One planned copy item.

RuntimeOptions

Runtime/performance controls for execution.

Enums

CopyEvent

Typed lifecycle events emitted during execution.

Error

Errors that can occur during copy operations.

ErrorCode

Stable semantic error codes for machine-readable integrations.

ItemOutcome

Outcome for one item in CopyReport.

OnConflict

Behavior when destination file already exists.

PlanAction

Planned action for one item.

PlanReason

Reason for a planned action.

PlannedItemKind

Source item kind in a plan.

Traits

EventHandler

Consumer for typed execution events.

Functions

copy_dir

Copy a directory recursively with parallel file operations

copy_file

Copy a single file atomically

create_progress_barprogress

Create a default progress bar for file copying

error_code_specs

Returns stable reference metadata for all known error codes.

execute_plan

Execute a copy plan and return a structured report.

is_no_space_error

Check if an IO error indicates “no space left on device”.

plan_copy

Build a concrete copy plan from source list and destination.

Type Aliases

ProgressCallbackprogress

Callback for progress updates

Result

Result type for parcopy operations.