cp2
Copy and sync files locally or between machines — ultra fast, verifiable, private, and very easy to set up.
cp2 is a modern cp/rsync-style tool in one pure-Rust binary for Linux,
macOS, and Windows. It sends only the bytes that actually changed,
verifies what it writes, and watches folders in realtime; a same-platform
remote needs nothing installed — the first sync automatically deploys cp2 there
(if libc is compatible).
- Install: one binary, or
cargo install cp2 - First sync:
cp2 ./photos user@server:backup - Watch mode (sync in realtime):
cp2 -W ./photos user@server:backup
Status: cp2 started as a personal tool to copy and sync files between a Windows laptop, a Linux workstation, and a Mac. It is under active development — it works pretty well for everyday use, but bugs may remain, and its developers and contributors cannot guarantee the safety of your data. Back up what matters, and run a dry run (
cp2 -n) before your first real sync.
Contents
- Install
- Quick start
- Why cp2?
- Common tasks
- Paths, globs, and file lists
- Defaults
- Key options
- Performance
- How it works
- Contributing
- Acknowledgments
- License
Install
On your machine
The recommended way — just note it needs the Rust toolchain on your PC:
or grab a prebuilt binary for your platform from the GitHub releases
page — download, extract, run.
There is nothing else to install: on Unix cp2 rides the ssh client you
already have, and on Windows a pure-Rust SSH client is built in.
On a remote (once, for different platforms)
A same-platform remote needs nothing — cp2 deploys itself there on the first sync. A different platform needs cp2 installed on the remote once, any of these three ways:
-
Install with cargo (Recommend) — log in and run
cargo install cp2 --locked(it builds for the remote's own libc, so it also fixes an older-glibc remote): -
Download the prebuilt tarball — grab the release tarball for the remote's platform from the GitHub releases page, extract it, rename the binary to
cp2, and copy it to~/.cargo/bin/. -
Build from source — on the remote:
&&
The binary is plain cp2 on Linux and macOS — only Windows appends
.exe — and the install folder is ~/.cargo/bin on Unix,
%USERPROFILE%\.cargo\bin on Windows (cp2.exe). That is also exactly
where cargo install puts it and where the client probes by default, so
any of the three methods lands the binary in the right place.
The remote build must match your client's build — the sync handshake
enforces it, and the error names what to reinstall. After that,
cp2 ./data user@remote:backup syncs like any same-platform remote.
Quick start
# Your first sync: push a folder to a server (same-platform remotes auto-deploy)
# Local copy — the same engine, no ssh
# Restore: pull it back down
# Watch the folder and sync every change for the next 24 hours
Your existing SSH credentials are used as-is (key, agent, or password); everything on the remote runs as your account.
The remote must run an SSH server (sshd) — on Linux and macOS it usually
already does; on Windows it is the optional OpenSSH Server feature:
enable it once and allow its port through the firewall (the release
archive's cp2-setup.exe does exactly that with a GUI). cp2's auto-deploy
installs the cp2 binary on the remote, not the SSH server itself.
Why cp2?
- Sends only what changed — FastCDC chunking + BLAKE3: a one-byte edit in a 50 GB file transfers kilobytes, not gigabytes, and large files stream in bounded memory — size never becomes a RAM problem.
- Verification you can trust —
--verifyproves the destination bytes match the source;--remove-source-filesfrees the source disk only after the copy is hash-verified and fsynced. - rsync semantics, minus the setup —
-a,--delete,--backup, excludes,--no-*opt-outs, exit code 23. If you know rsync, you already know cp2. - Realtime watch —
-Wmonitors a folder and syncs changes as they happen (event-driven push, server-driven pull), with an optional duration cap. - Cross-platform and scriptable — any combination of Linux, macOS, and
Windows;
-i/--stats/--list-onlygive clean, parseable output.
Why not just rsync?
rsync is battle-tested and ubiquitous — cp2 doesn't argue with that, just the rough edges:
| rsync | cp2 | |
|---|---|---|
| server setup | manual install, PATH config, or a daemon | auto-deploy on same-platform remotes |
| delta | fixed blocks + rolling checksums | content-defined chunks (FastCDC) + BLAKE3 |
| integrity | none built in | --verify; hash-guarded --remove-source-files |
| watch | not built in | built-in -W |
| password prompts | once per session | once per run |
| Windows | via WSL/Cygwin | native |
Common tasks
Backup and restore
Preview before you sync
Safely move data off a machine
Source files are deleted only after the destination is hash-verified and fsynced — made for clearing an instrument's storage.
Sync only what matches
Watch a folder continuously
Scripting and auditing
# cd+++++++++ sub new directory
# .f.......... a.txt already in sync
# >f.s....... a.txt updated
# *deleting stale.txt removed (with --delete)
Jump hosts and passwords
Paths, globs, and file lists
Remote paths
A leading / after the colon (user@host:/abs/path) is an absolute
server path; anything else (user@host:backup, user@host:softwares/cp2)
is relative to the serve root (your account home); no path means the home
itself. Path traversal (..) is rejected.
Glob sources
A quoted glob in a local source is expanded by cp2, and every match syncs as a top-level entry of one run:
A quoted glob expands on either side: a local source is expanded by cp2
before the sync, a remote source (user@host:data/*.iso) by the server
during the pull. A path that literally exists is never treated as a
pattern; and the wildcard matches dotfiles like rsync's (use --exclude
to drop .git, target, ...). --watch needs a single directory
source, not a glob.
File lists
--files-from FILE syncs exactly the absolute paths listed in FILE,
mirroring each one's root-relative structure under the destination — a
curated backup manifest that reaches across directories:
# /data/a.txt → backup/data/a.txt
# /games/b.exe → backup/games/b.exe
One absolute path per line — Unix and Windows line endings both work, blank
lines are skipped, and paths may contain spaces. Entries may be files or
directories (directories recurse), and each file syncs exactly once. The
list is read on the machine you run cp2 on: for a push the entries are
local absolute paths (missing entries are warned about and skipped); for a
pull they are absolute paths on the server, scanned and mirrored from
there. With --delete, only destination content under the listed paths is
removed (rsync scope) — files sitting next to them are left alone.
Defaults
cp2's defaults mirror rsync -avP without -z: recursive sync with
mode/mtime preservation, a per-file listing annotated with the file's
position and the run's total, a dnf-style summary row per file
([12/3456] path 100% | rate | size | elapsed), live progress on a
terminal (one in-place row per file, growing 0%→100%), and partial
files kept at the destination when a transfer is interrupted — the next
run delta-resumes against them. Compression is opt-in via -z; the
listing and progress are silenced by -q.
Key options
The full reference — every flag with its rsync equivalent and caveats — is
in the man page (man ./docs/cp2.1) and in cp2 --help. The flags people
reach for:
Essentials
| Flag | What it does |
|---|---|
-a, --archive |
Byte-identical archive: recursion, mode/mtime, symlinks and hard links, plus special files, owner/group, SUID/SGID/Sticky (Unix-like systems) |
-n, --dry-run |
Preview what would transfer; touches nothing |
--delete / --max-delete N |
Remove destination files absent from source / refuse to delete more than N |
-u, --update |
Skip files where the destination is newer |
-c, --checksum |
Compare BLAKE3 hashes instead of size+mtime |
--ignore-existing / --existing |
Skip files that already exist / update only existing files |
-p, --port, --jump-host, --password, --password-file |
SSH connection: custom port, tunneling, credentials |
Safety
| Flag | What it does |
|---|---|
--verify |
Prove the destination bytes match the source (exit 23 on mismatch, nothing deleted) |
--remove-source-files |
Delete source files only after the copy is hash-verified and fsynced |
--fsync |
fsync every received file before it is renamed into place, and the destination directories holding the renames once at the end |
--backup |
Keep replaced destination files as <name>~ |
Speed and bandwidth
| Flag | What it does |
|---|---|
-j, --jobs N |
Parallel transfer + hash workers (auto-tuned from the target storage class) |
-z, --compress |
Compress the stream (lz4) |
--bwlimit SIZE |
Cap transfer bandwidth (e.g. 10M, 100K) |
-S, --sparse |
Write zero runs as holes (VM images, database files) |
Selection and scripting
| Flag | What it does |
|---|---|
--exclude / --include, --exclude-from / --include-from |
Filter what syncs (repeatable; files: one pattern per line) |
--files-from FILE |
Sync exactly the listed paths, mirrored under the destination |
-i, --itemize-changes |
Per-file change lines for scripting and auditing |
--stats |
Post-run statistics block |
--list-only |
List the source without transferring |
-W[=DUR], --watch-delay MS |
Watch continuously; debounce window |
-X, --xattrs, -U, --atimes |
Extended attributes / access times |
--literal-links, --follow-links, --skip-links |
Link policy: keep, follow, or skip symlinks and shortcuts |
--no-recursive, --no-perms, --no-times |
Opt out of the rlpt core piece by piece |
-v, --verbose, -q, --quiet |
Output level (repeat -v for more) |
cp2 --server is the sshd-invoked server mode (like rsync's --server) —
it runs on the remote side and is not for direct use.
Performance
One benchmark run pushing over ssh localhost (Fedora 44, x86_64, NVMe,
2026-08-27). Every cell is three repetitions reported as mean ± sd,
with the page cache warmed before each run, the tool order rotated per
scenario, every run bounded by a 300 s timeout, and both destinations
byte-verified against each tool's edited source (0 differing files). Every
tool runs its default core — cp2 bare, rsync plain -a, scp -r, sy/pxs
defaults — no -c/checksum flag anywhere. From bench/bench.sh compare.
tool large-first large-edit small-first small-idle
cp2 1.76±0.09s 2.05±0.53s 3.16±0.31s 0.59±0.00s
rsync 2.00±0.03s 1.97±0.71s 2.01±0.24s 0.73±0.02s
scp 1.93±0.04s 2.72±1.00s 3.64±0.07s 3.41±0.02s
sy 2.57±0.15s 6.03±0.55s 55.85±1.54s 0.79±0.15s
pxs 6.45±0.05s 0.95±0.00s 2.88±0.01s 1.56±0.01s
fastest cp2 pxs rsync cp2
The full suite — scripts, generated trees, and how to run it over a real
network — is documented in ARCHITECTURE.md.
How it works
A sync compares file manifests, plans create/update/delete, and sends only
the changed bytes — FastCDC content-defined chunks plus BLAKE3, so a 1-byte
edit in a 50 GB file transfers kilobytes. Files are applied in bounded
memory over a single pipelined stream, and the run's sessions multiplex
over one ssh connection. The wire protocol, deployment mechanics, and
security model are documented in ARCHITECTURE.md.
Contributing
Issues and pull requests are welcome — open an issue or a pull request.
- Bug reports: include the exact command,
cp2 --versionoutput, and the platforms involved (local and remote). - Before a PR:
cargo testmust pass andcargo clippy --all-targets -- -D warningsmust be clean. - Larger features get discussed in an issue first.
Acknowledgments
cp2's design, and parts of its code, are informed by the following projects.
None are linked at runtime — adaptations are credited per module in the
source headers, and their retained copyright lines live in
NOTICE.
| Project | License | Contribution |
|---|---|---|
| rsync | GPL-3.0 | CLI semantics (-a, --delete, the --no-* opt-outs), the rsync-over-ssh model — design only, no code |
| copia | MIT | Delta engine: Delta/DeltaOp/apply_patch (adapted, src/delta/) |
| sparsync | MIT | Frame wire protocol; scan/manifest pipeline (adapted) |
| sy | MIT | Planner; transport abstraction (adapted) |
| robosync | MIT | File-tier transfer strategy (adapted, src/sync/strategy.rs) |
| pxs | BSD-3-Clause | Staged-file sink / atomic commit (adapted, src/platform/staging.rs) |
| librsync | MIT/Apache-2.0 | Delta-algorithm background (studied) |
| rusync | BSD-3-Clause | rsync-style CLI/protocol study |
| ripsync | MIT/Apache-2.0 | rsync protocol study |
| zsync-rs | MIT | rsync-compatible delta study |
| msy | MIT | Sync-pipeline study |
| syncz | MIT | Sync-protocol study |
All adaptations are from MIT/BSD-licensed projects, compatible with cp2's MIT license; rsync (GPL) contributed design and interface semantics only.
License
MIT — see LICENSE. Third-party adaptations and their retained copyright lines are attributed in NOTICE.