rsync Command Builder

rsync in depth: the algorithm, the flags, and the traps

rsync (short for "remote sync") was written in 1996 by Andrew Tridgell — the same Australian hacker who created Samba and whose reverse-engineering of the BitKeeper protocol eventually led to the birth of Git. What sets rsync apart from scp, ftp, or a plain cp -r is its rolling-checksum delta algorithm: the receiver splits its existing copy of each file into fixed-size blocks, computes a weak rolling checksum plus a strong MD5/MD4 hash for each block, and the sender uses those checksums to transmit only the bytes that actually changed. On a 10 GB virtual machine image where you edited 200 KB, rsync moves roughly 200 KB. scp moves 10 GB.

The basic invocation is rsync [options] source destination. Either side can be local, a remote SSH path (user@host:/path), or an rsync daemon module (host::module/path). This generator emits a command from the options you tick — the sections below explain what each flag does, the most useful idioms, and the gotchas that have ruined production data.

The essential flags

• -a (archive) — shorthand for -rlptgoD: recursive, copy symlinks as symlinks, preserve permissions, timestamps, group, owner, devices and special files. This is what you almost always want for backups.
• -v / -vv / -vvv — increasing verbosity. Useful while developing a command, noisy in cron jobs.
• -z — compress data in transit. Worth it over slow links; counterproductive on a LAN where the CPU cost exceeds the bandwidth saved.
• -h — human-readable sizes (KB, MB, GB) in progress and summary output.
• -P — equivalent to --partial --progress. Keeps half-transferred files so an interrupted run can resume, and prints a per-file progress bar.
• -n / --dry-run — go through the motions without writing anything. Always run a dry-run before --delete.
• --delete — remove files from the destination that no longer exist in the source. Makes the destination a true mirror — and erases anything you forget to exclude.
• --exclude='pattern', --exclude-from=file, --include='pattern' — filter rules. Patterns follow shell glob syntax; lines in an exclude-from file are processed in order.
• -x / --one-file-system — do not cross mount points. Critical when backing up / so you do not recurse into /proc, /sys, or NFS mounts.
• --bwlimit=KBPS — cap the transfer rate. Use it to leave bandwidth for the rest of the team.
• --link-dest=DIR — hard-link unchanged files from a previous snapshot. Combined with a date-stamped directory this gives you Time Machine-style incremental backups for almost no extra disk space.

The trailing slash trap

No single character has caused more surprised faces than the trailing / on the source path. Compare:

rsync -a src/ dst/   # copies the CONTENTS of src into dst
rsync -a src  dst/   # creates dst/src/ and copies into it

A trailing slash on the source means "the contents of"; no slash means "this directory as a node". The trailing slash on the destination is harmless either way. Get this wrong and you either end up with a nested dst/src/src/ over time or, worse, overwrite a different directory.

Recipes that come up again and again

# Mirror a project to a remote server, deleting removed files
rsync -azP --delete --exclude='.DS_Store' --exclude='node_modules/' \
      src/ user@server:/var/www/site/

# Time Machine-style snapshot using hard links
rsync -a --link-dest=/backups/2026-05-26 /home/ /backups/2026-05-27/

# Resume a half-finished download over a flaky connection
rsync -azP --partial-dir=.rsync-partial user@host:big.iso .

# Throttle and run quietly inside cron
rsync -a --bwlimit=2000 --delete src/ dst/ >> /var/log/sync.log 2>&1

rsync vs the alternatives

• scp — encrypts and copies, but always moves the entire file. Deprecated in OpenSSH 9; use scp -O for the legacy protocol or switch to sftp / rsync.
• git — content-addressed, tracks history; rsync is file-level and history-less. Use git for source code, rsync for binaries, media, and full filesystem trees.
• zfs send / btrfs send — block-level, atomic snapshots between machines running the same filesystem. Faster than rsync but require ZFS/btrfs on both ends.
• rclone — rsync's spiritual cousin for cloud object storage (S3, GCS, B2, Dropbox, OneDrive, ...). Same dry-run / delete / bwlimit idioms.
• unison — true bidirectional sync with conflict detection, where rsync is one-way.

Operational gotchas

• --delete is irreversible. Always run -n --delete first and read the file list before removing the dry-run flag.
• UID / GID mismatch. When source and destination are different machines, -o and -g map by name. If user IDs are not aligned, ownership on the destination may shift; force numeric mapping with --numeric-ids.
• SSH config. For non-default ports or keys, use -e 'ssh -p 2222 -i ~/.ssh/backup_key' or set the host in ~/.ssh/config and let rsync inherit it.
• Sparse files. Add -S / --sparse when copying VM disk images so empty regions stay empty on the destination.
• Large directories. rsync builds the full file list in memory before transferring; for trees of tens of millions of files use --no-inc-recursive or split the job.

FAQ

Can rsync sync in both directions? Not natively — rsync is one-way per invocation. For true bidirectional sync with conflict resolution, use Unison or run two complementary rsync commands inside a wrapper that handles deletes carefully.

Will rsync resume an interrupted transfer? Yes, with --partial (or -P) the partial file is kept and the next run picks up where the previous one stopped, thanks to the same checksum algorithm.

Does rsync work on Windows? Yes — via Cygwin, MSYS2, or WSL2. Native alternatives include robocopy (built in) and FreeFileSync. For mixed POSIX/Windows file modes, drop -p and -o.

How do I exclude a folder but keep one file inside it? Use the order-sensitive include/exclude rules: --include='dir/' --include='dir/keep.txt' --exclude='dir/*'. rsync matches the first rule that applies.

Why is rsync slower than I expected? Common causes: -z on a fast LAN, the checksum stage on millions of small files, --checksum forcing full-file hashes, or an SSH cipher mismatch. Profile with --stats and try -e 'ssh -c [email protected]' for the cheapest modern cipher.