cp — A Modern File Copy Utility in Rust

Features

Everything you need.

Full GNU cp compatibility with modern kernel optimizations, parallel I/O, and a robust copy engine with automatic fallback.

Zero-Copy Kernel I/O

Uses copy_file_range, sendfile, and FICLONE (reflink) syscalls to avoid unnecessary user-space memory copies.

Parallel Directory Copy

Rayon-powered parallel traversal with openat/mkdirat/readdir raw syscalls. Threshold auto-switches at 64 entries.

Sparse File Detection

Uses SEEK_HOLE/SEEK_DATA to preserve file holes. Supports --sparse=auto|always|never modes.

Full Metadata Preservation

Preserves mode, ownership, timestamps (nanosecond), xattr, ACL, and hard links with correct ordering to avoid permission races.

Reflink / CoW Support

Instant copy-on-write cloning on Btrfs, XFS, and APFS via FICLONE ioctl. Falls back transparently when unsupported.

GNU-Compatible CLI

Drop-in replacement with all standard flags: -a, -R, -p, -f, -n, -u, --backup, --sparse, --reflink, and more.

Progress Bar

Beautiful --progress indicator powered by indicatif. Real-time throughput and ETA display for large transfers.

Backup Modes

Numbered (.~1~), simple (~), or existing-mode backups. Respects VERSION_CONTROL and SIMPLE_BACKUP_SUFFIX environment variables.

Security-Hardened

Same-file detection via inode, symlink loop protection, TOCTOU-safe operations, setuid handling, and path traversal prevention.

Architecture

Copy Pipeline

From CLI arguments to kernel syscalls — every stage optimized for throughput.

Stage 1

CLI Parse

Clap derives CLI flags into
CopyOptions struct

Stage 2

Target Resolution

Resolve sources, dest path,
same-file & self-copy checks

Stage 3

Directory Walk

Fast path: raw openat/readdir
Slow path: walkdir iterator

Stage 4

Copy Engine

Cascading fallback:
reflink → cfr → sendfile → r/w

Stage 5

Metadata Sync

xattr → chown → chmod
→ utimensat → ACL

Copy Engine Fallback Chain

Each method is tried in order — first success wins

FICLONE (reflink)

→

copy_file_range

→

sendfile

→

read / write

Performance

Benchmarks vs GNU cp

Head-to-head comparison on Linux 6.18 — averaged over 3 runs of 5 iterations each. Lower is faster.

Many Small Files 1,000 × 1 KB — recursive copy

GNU

28.6 ms

ours

25.0 ms

1.1x

faster

Recursive Archive 500 × 4 KB with -a (preserve all)

GNU

16.5 ms

ours

13.6 ms

1.2x

faster

Deep Directory Tree 5 levels × 4 dirs × 10 files × 4 KB

GNU

328 ms

ours

280 ms

1.2x

faster

Mixed File Sizes 50×1KB + 30×100KB + 15×1MB + 5×10MB

GNU

44.0 ms

ours

27.8 ms

1.6x

faster

Large File 100 MB single file — copy_file_range

GNU

58.9 ms

ours

57.8 ms

1.0x

on par

Hardlink-Heavy 50 files × 20 links = 1,000 entries -a

GNU

17.1 ms

ours

17.1 ms

1.0x

on par

Symlink-Heavy 100 files + 400 symlinks — recursive

GNU

12.8 ms

ours

11.6 ms

1.1x

faster

Sparse File 100 MB with 50 MB hole — --sparse=auto

GNU

1.4 ms

ours

1.3 ms

1.1x

faster

Parallel Threshold Sweep

Directory sizes from 32 to 256 files — threshold at 64 triggers parallel I/O

1.6 ms

2.3 ms

3.6 ms

128

7.0 ms

256

⚡

Startup Overhead

Cold-start time for a 1-byte file copy (50 runs avg): ~0.9 ms

Quality

Test Suite

168 tests across 12 suites — covering unit, integration, security, and performance benchmarks. All passing on every commit.

security38

unit_copy24

unit_options18

unit_util18

integration12

unit_dir12

unit_backup11

unit_metadata9

unit_engine9

unit_sparse9

unit_parallel8

benchmarks19

✓

168 tests + 19 benchmarks — all passing

Security Tests (38)

TOCTOU race conditions, symlink escape, path traversal, setuid handling, hardlink bombs, circular symlinks, umask leaks, and permission escalation checks.

Integration Tests (12)

Byte-for-byte comparison against GNU cp: single file, recursive, metadata preservation, error messages, exit codes, and verbose output format.

Benchmarks (19)

Large files, many small files, mixed sizes, deep trees, symlinks, hardlinks, sparse files, parallel threshold sweep, and startup overhead measurement.

Usage

CLI Reference

Drop-in replacement for GNU cp. All standard POSIX and GNU flags supported.

Terminal
 1# Basic copy
 2cp source.txt dest.txt
 3
 4# Recursive copy preserving everything
 5cp -a my_project/ backup/
 6
 7# Copy with progress bar
 8cp --progress large_file.iso /mnt/usb/
 9
10# CoW reflink (instant on Btrfs/XFS)
11cp --reflink=auto vm_disk.qcow2 snapshot.qcow2
12
13# Sparse-aware copy
14cp --sparse=always database.img /backup/
15
16# Debug mode (shows copy method used)
17cp --debug file.dat /dst/

Flag	Description
-a, --archive	Same as `-dR --preserve=all`
-R, -r, --recursive	Copy directories recursively
-p	Preserve mode, ownership, timestamps
-f, --force	Remove destination before copy if needed
-n, --no-clobber	Do not overwrite existing files
-u, --update	Copy only when source is newer
-v, --verbose	Explain what is being done
-l, --link	Hard link files instead of copying
-s, --symbolic-link	Create symlinks instead of copying
-L, --dereference	Always follow symlinks in source
-P, --no-dereference	Never follow symlinks in source
--preserve=ATTR	Preserve: mode, ownership, timestamps, links, xattr, all
--no-preserve=ATTR	Don't preserve specified attributes
--sparse=WHEN	Control sparse file creation: auto, always, never
--reflink=WHEN	Control CoW cloning: auto, always, never
--backup[=CONTROL]	Make backup: numbered, existing, simple, none
-S, --suffix	Override backup suffix (default: ~)
-x, --one-file-system	Stay on the same filesystem
-t, --target-directory	Copy all sources into directory
-T, --no-target-directory	Treat destination as normal file
--parents	Replicate source path structure under dest
--attributes-only	Copy metadata only, no file data
--remove-destination	Remove each existing destination before copy
--debug	Show copy method used (implies -v)
--progress	Show progress bar during copy

Source

Project Structure

Clean module separation — each concern isolated in its own file.

Project Layout
 src/
   main.rs        # Entry point, CLI dispatch              125 lines
   cli.rs         # Clap-derived CLI definitions            201 lines
   options.rs     # CopyOptions resolution from CLI flags   236 lines
   dir.rs         # Recursive directory copy (fast + slow) 1030 lines
   copy.rs        # Single file copy logic                  335 lines
   engine.rs      # Copy engine (reflink/cfr/sendfile/rw)   199 lines
   metadata.rs    # Permission, xattr, ACL, timestamps      237 lines
   sparse.rs      # Sparse file hole detection + copy       192 lines
   error.rs       # Error types (thiserror)                 145 lines
   util.rs        # Path utilities, target resolution        120 lines
   backup.rs      # Backup file creation                     77 lines
   progress.rs    # Progress bar (indicatif)                  24 lines
 
 tests/
   common/mod.rs # Shared test harness (Env fixture)       194 lines
   12 test files # 168 tests + 19 benchmarks              3560 lines

A Modern cp Reimagined in Rust

Everything you need.

Zero-Copy Kernel I/O

Parallel Directory Copy

Sparse File Detection

Full Metadata Preservation

Reflink / CoW Support

GNU-Compatible CLI

Progress Bar

Backup Modes

Security-Hardened

Copy Pipeline

Copy Engine Fallback Chain

Benchmarks vs GNU cp

Parallel Threshold Sweep

Startup Overhead

Test Suite

Security Tests (38)

Integration Tests (12)

Benchmarks (19)

CLI Reference

Project Structure

A Modern cp
Reimagined in Rust