parcopy

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

A production-grade library for copying files and directories with safety guarantees that go beyond the standard library.

Features

• Parallel copying - Uses rayon for concurrent file operations
• Atomic writes - Uses temp file + rename pattern to ensure no partial files
• TOCTOU safe - Uses persist_noclobber to prevent race conditions
• Incremental copy - Only copy files newer than destination (UpdateNewer)
• Reflink support - Instant copy-on-write on btrfs/XFS/APFS
• Timestamp preserving - Copies file modification and access times
• Permission preserving - Copies file and directory permissions
• Symlink aware - Correctly handles symlinks without following them
• Symlink loop detection - Prevents infinite recursion from circular symlinks
• Security hardened - Detects and optionally blocks escaping symlinks
• Graceful cancellation - Cooperative cancellation with Ctrl+C support

Why parcopy?

Installation

[dependencies]
parcopy = "0.2"

Optional Features

[dependencies]
parcopy = { version = "0.2", features = ["progress", "reflink"] }

Quick Start

Builder API (Recommended)

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

Only copy files that have changed:

use parcopy::CopyBuilder;

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

Optimize for NFS or network filesystems:

use parcopy::CopyBuilder;

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

Security-Hardened Copy

Copy untrusted directories safely:

use parcopy::CopyBuilder;

let stats = CopyBuilder::new("untrusted_upload", "safe_location")
    .block_escaping_symlinks()  // Block symlinks with "../"
    .max_depth(10)              // Limit directory depth
    .run()?;

Cancellable Copy

Support graceful cancellation from signal handlers:

use parcopy::CopyBuilder;
use std::sync::Arc;
use std::sync::atomic::AtomicBool;

let cancel = Arc::new(AtomicBool::new(false));

// Clone for signal handler
let cancel_clone = cancel.clone();
// In your signal handler: cancel_clone.store(true, Ordering::Relaxed);

let result = CopyBuilder::new("src", "dst")
    .cancel_token(cancel)
    .run();

match result {
    Ok(stats) => println!("Copied {} files", stats.files_copied),
    Err(parcopy::Error::Cancelled { files_copied, .. }) => {
        println!("Cancelled after {} files. Re-run to resume.", files_copied);
    }
    Err(e) => eprintln!("Error: {}", e),
}

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)
    .with_on_conflict(OnConflict::Overwrite)
    .with_max_depth(100)
    .without_fsync();

let stats = copy_dir(Path::new("src"), Path::new("dst"), &options)?;

Configuration Options

Conflict Strategies

Copy Statistics

All copy operations return CopyStats:

use parcopy::CopyBuilder;

let stats = CopyBuilder::new("src", "dst").run()?;

println!("Files copied:   {}", stats.files_copied);
println!("Files skipped:  {}", stats.files_skipped);
println!("Symlinks:       {}", stats.symlinks_copied);
println!("Directories:    {}", stats.dirs_created);
println!("Bytes copied:   {}", stats.bytes_copied);
println!("Duration:       {:?}", stats.duration);

Safety Guarantees

Atomic Writes

Files are written to a temporary file in the destination directory, then renamed atomically:

1. No partial files - Interrupted copies leave no garbage
2. All-or-nothing - Other processes see complete files or nothing
3. Power failure safe - With fsync: true, data survives crashes

TOCTOU Protection

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

Symlink Safety

• Symlinks are never followed during directory traversal
• Symlink loops are detected and reported
• Escaping symlinks (../) are warned or blocked

Performance Notes

NFS Optimization

This crate is optimized for NFS and network filesystems where many small files cause metadata storms. By parallelizing operations, multiple NFS RPCs can be in-flight simultaneously.

// For slow NFS, reduce parallelism to avoid overwhelming the server
let stats = CopyBuilder::new("src", "dst")
    .parallel(4)
    .run()?;

Local SSD

For local SSDs, parallelism helps less but doesn't hurt:

// Default parallelism (16) works well for local storage too
let stats = CopyBuilder::new("src", "dst").run()?;

Large Files

For large files, the reflink feature provides instant copy-on-write on supported filesystems (btrfs, XFS, APFS):

[dependencies]
parcopy = { version = "0.2", features = ["reflink"] }

CLI Tool

A CLI tool pcp is available in the cli directory:

# Install
cargo install --path cli

# Usage
pcp -r src/ dst/              # Recursive copy
pcp -c update src/ dst/       # Incremental copy
pcp -j 8 src/ dst/            # 8 parallel threads
pcp --plan src/ dst/          # Plan only (no filesystem mutation)
pcp --output json src/ dst/   # Machine-readable execution output

Canonical CLI Behavior

RFC-0001 defines a canonical CLI behavior model for profiles, plan/execute modes, and output contracts:

• Canonical behavior model: docs/reference/cli-behavior.md
• Migration notes: docs/migrations/2026-02-rfc-0001-cli.md

Graceful Cancellation

Press Ctrl+C during a copy operation:

• First press: Graceful cancel — finishes in-flight files, reports progress
• Second press: Hard abort — immediate exit

Re-run the same command to resume (existing files are skipped by default).

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.