| title | Linux Command Tutorial: rsync | ||||
|---|---|---|---|---|---|
| date | 2026-09-12 00:00:00 +0000 | ||||
| categories |
|
||||
| tags |
|
||||
| draft | false | ||||
| slug | linux-rsync-tutorial | ||||
| description | Authoritative reference tutorial for rsync (rsync), detailing delta-transfer algorithm file synchronization, archive mode preservation, remote SSH transport, exclusions, and bandwidth limiting. | ||||
| upstream_suite | rsync | ||||
| upstream_version | rsync 3.5.0 | ||||
| posix_standard | None | ||||
| research_date | 2026-09-12 |
The Linux Command Tutorial series provides rigorous, upstream-verified references for essential system commands across Linux distributions and UNIX-like environments. Each article focuses on a single executable, combining exhaustive option documentation, verified real-world examples, security boundaries, and best practices directly derived from official source documentation and POSIX standards.
Upstream: rsync (rsync 3.5.0) | POSIX: None (De-facto Standard) | Safety Tier: unprivileged-filesystem-write | Scope: remote-file-synchronization
rsync (Remote Sync) is a fast, versatile utility for synchronizing files and directory trees locally or across networks. It utilizes a rolling-checksum delta-transfer algorithm that computes differences between source and destination files, transmitting only changed byte blocks over network connections.
- Upstream Project & Provenance: Created by Andrew Tridgell and Paul Mackerras, maintained by Wayne Davison and the Samba team under the rsync project (
rsync). - Portability & Standards Baseline: De-facto universal Unix file synchronization utility; not standardized in IEEE Std 1003.1-2024 (POSIX.1-2024).
- Target Research Implementation: Audited against rsync 3.5.0 (
rsync(1)). - Applicability & Lifecycle: The standard utility for server backups, site mirroring, continuous integration deployments, and disaster recovery.
# Local to local synchronization
rsync [OPTION...] SRC... [DEST]
# Remote synchronization over SSH (Push)
rsync [OPTION...] SRC... [USER@]HOST:DEST
# Remote synchronization over SSH (Pull)
rsync [OPTION...] [USER@]HOST:SRC... [DEST]A fundamental syntactic rule governs source directory handling in rsync:
- Source with Trailing Slash (
/src/dir/): Copies the contents ofdir/directly into destination without creating an extra subdirectory. - Source without Trailing Slash (
/src/dir): Copies the directory itself, creating/dest/dir/.
# Copies files inside data into /backup/ (e.g. /backup/file1.txt)
rsync -a /var/data/ /backup/
# Copies data directory into /backup/ (e.g. /backup/data/file1.txt)
rsync -a /var/data /backup/When synchronizing across remote hosts, rsync spawns a client process locally and a remote server process via SSH. The receiver breaks destination files into fixed-size blocks, computes weak rolling checksums and strong MD4/MD5 hashes, and sends them to the sender. The sender matches hashes and transmits only the modified byte blocks.
| Option | Long Option | Description | Default |
|---|---|---|---|
-a |
--archive |
Archive mode: equivalent to -rlptgoD (recurse, preserve symlinks, perms, times, owner, group, devices). |
Non-recursive |
-v |
--verbose |
Increase verbosity, printing transferred filenames. | Concise |
-q |
--quiet |
Suppress non-error output messages. | Normal |
-z |
--compress |
Compress file data blocks during network transmission. | Uncompressed |
-h |
--human-readable |
Format byte counts and transfer rates with readable units (K, M, G). |
Integer bytes |
-n |
--dry-run |
Perform a trial run without modifying destination filesystems. | Active execution |
-P |
Equivalent to --partial --progress (resumes partial files and displays transfer progress). |
Off | |
-c |
--checksum |
Skip files based on cryptographic checksums rather than mod-time and size. | Quick check (mtime+size) |
--delete |
--delete |
Delete extraneous files from destination not present in source (mirroring). | Retains destination files |
--delete-after |
--delete-after |
Delete extraneous files after transfers conclude rather than during. | Immediate deletion |
-e CMD |
--rsh=CMD |
Specify remote shell command (e.g. -e "ssh -p 2222"). |
ssh |
--bwlimit=RATE |
--bwlimit=RATE |
Limit socket I/O bandwidth (e.g. 10m, 500k). |
Unlimited |
--link-dest=DIR |
--link-dest=DIR |
Create hard links to unchanged files in reference directory for instant snapshots. | Off |
-S |
--sparse |
Handle sparse files efficiently, preserving storage holes on destination. | Dense allocation |
| Option | Long Option | Description |
|---|---|---|
--exclude=PAT |
--exclude=PAT |
Exclude files and directories matching glob pattern PAT. |
--exclude-from=F |
--exclude-from=F |
Read exclusion glob patterns line-by-line from file F. |
--include=PAT |
--include=PAT |
Explicitly include files matching PAT before general exclusions. |
| Operation | Command Pattern | Copyable One-Liner | Notes |
|---|---|---|---|
| Local archive backup | rsync -avh [src]/ [dest]/ |
rsync -avh /home/user/docs/ /mnt/backup/docs/ |
Preserves permissions, times, and symlinks |
| Safe dry-run test | rsync -avhn --delete [src]/ [dest]/ |
rsync -avhn --delete /data/ /backup/data/ |
Previews changes and deletions without writes |
| Sync over SSH | rsync -avzP -e ssh [src]/ [user]@[host]:[dest]/ |
rsync -avzP -e ssh /var/www/ deploy@server:/var/www/ |
Compressed transfer with progress and resume |
| Strict mirroring | rsync -av --delete [src]/ [dest]/ |
rsync -av --delete /data/ /mirror/ |
Deletes extraneous destination files |
| Deduplicated snapshot | rsync -a --link-dest=[prior] [src]/ [dest]/ |
rsync -a --delete --link-dest=/backup/yesterday/ /data/ /backup/today/ |
Hardlinks unchanged files across snapshots |
| Throttled sync | rsync -av --bwlimit=[rate] [src]/ [dest]/ |
rsync -avzP --bwlimit=5M /data/ remote:/storage/ |
Caps network socket bandwidth usage |
| Atomic updates | rsync -av --delay-updates [src]/ [dest]/ |
rsync -av --delay-updates /var/www/v2/ /var/www/live/ |
Stages files and renames in final pass |
Synchronize a local directory with archive preservation and human-readable transfer logs:
rsync -avh /home/user/documents/ /mnt/backup/documents/Output:
sending incremental file list
./
financial_report_2026.pdf
notes.txt
projects/
projects/architecture_spec.md
sent 4.82M bytes received 84 bytes 9.64M bytes/sec
total size is 4.81M speedup is 1.00Always test backup or synchronization commands with -n (--dry-run) before modifying production storage:
rsync -avhn --delete /home/user/documents/ /mnt/backup/documents/Output:
sending incremental file list
deleting obsolete_draft.docx
financial_report_2026.pdf
sent 284 bytes received 18 bytes 604.00 bytes/sec
total size is 4.81M speedup is 15.93 (DRY RUN)Synchronize files to a remote server over an encrypted SSH transport with compression and progress tracking:
rsync -avzP -e "ssh -p 22022" /var/www/html/ deploy@server.example.com:/var/www/html/Output:
sending incremental file list
index.html
4.12K 100% 3.93MB/s 0:00:00 (xfr#1, to-chk=24/25)
assets/app.js
184.92K 100% 12.45MB/s 0:00:00 (xfr#2, to-chk=12/25)
sent 48.12K bytes received 1.45K bytes 33.05K bytes/sec
total size is 894.12K speedup is 18.04Ensure the destination directory matches the source precisely by removing extraneous destination files:
rsync -av --delete /data/production/ /data/mirror/Implement automated, deduplicated hourly backups without consuming extra disk space for unchanged files:
# Reference yesterday's backup directory; unchanged files become hard links
rsync -a --delete \
--link-dest=/backups/2026-09-11/ \
/home/user/data/ \
/backups/2026-09-12/Mechanism: If a file in /home/user/data/ has the exact same mtime and size as /backups/2026-09-11/file, rsync creates a hard link in /backups/2026-09-12/file pointing to the existing inode, consuming zero additional disk blocks.
Prevent backup transfers from saturating WAN or VPN uplinks by capping transfer rates:
# Limit transfer rate to 5 Megabytes per second
rsync -avzP --bwlimit=5M /data/heavy_backups/ remote:/storage/Exclude version control files, caches, and build artifacts using exclusion rules:
rsync -av \
--exclude='.git/' \
--exclude='node_modules/' \
--exclude='*.tmp' \
--exclude='*.log' \
/workspace/project/ /opt/deploy/project/Or load patterns from a dedicated .rsync-ignore file:
rsync -av --exclude-from='.rsync-ignore' /src/ /dest/Prevent client services from reading partially written files during a large sync operation:
rsync -av --delay-updates /var/www/v2/ /var/www/live/Mechanism: rsync stages all new and modified files into temporary files (.~tmp~) during transfer, renaming them atomically into their final destinations in a rapid closing phase.
By default, rsync relies on "quick check" (file modification time and size equality). For high-security environments or storage corruption validation, force full cryptographic hashing across all files:
rsync -avc /critical/data/ /backup/critical/| Exit Code | Meaning |
|---|---|
0 |
Success: synchronization completed without errors. |
1 |
Syntax or usage error. |
2 |
Protocol incompatibility. |
3 |
Errors selecting input/output files or directories. |
5 |
Error starting client-server protocol. |
10 |
Error in socket I/O (network dropped or connection timed out). |
11 |
Error in file I/O (disk full, permission denied, or read error). |
12 |
Error in rsync protocol data stream. |
23 |
Partial transfer due to error. |
24 |
Partial transfer due to vanished source files. |
| Variable | Description |
|---|---|
RSYNC_RSH |
Default remote shell command (superseded by -e). |
RSYNC_PASSWORD |
Password used for authenticating against standalone rsync daemons. |
When running in standalone server mode (rsync --daemon), configuration is managed via /etc/rsyncd.conf.
Caution
Destructive Impact of --delete: The --delete flag permanently removes files from destination directories. A mistyped source path or empty directory can wipe out the entire destination directory. Always test commands with -n (--dry-run) before executing with --delete.
Note
Archive mode (-a) attempts to preserve owner (-o) and group (-g) IDs. Preserving numeric UIDs and GIDs requires root privileges on the destination host. Unprivileged users running rsync -a will experience permission warnings unless --no-owner --no-group is specified.
rsync is ubiquitous across modern Linux, BSD, and macOS systems. Version 3.x utilizes a streamlined protocol that maintains backward compatibility with legacy 2.x rsync servers.
Important
Double-Check Trailing Slashes on Source Paths: A trailing slash on the source directory (/src/dir/) copies the contents into destination, whereas omitting the slash (/src/dir) copies the directory itself as a subdirectory (/dest/dir/).
Upstream Rationale: Omitting a trailing slash on source directories copies the parent directory container (e.g. /dest/source/), while appending a trailing slash copies the child items directly (e.g. /dest/). Always explicitly check trailing slashes on source paths prior to execution.
Upstream Rationale: rsync(1) documentation highlights that deleted files cannot be recovered once removed from the destination tree. Running rsync -avhn --delete provides complete visibility of scheduled deletions before physical disk writes occur.
Tip
Leverage --link-dest for Zero-Cost Hourly Snapshots: Traditional backups duplicate unchanged files across directories, wasting disk space. --link-dest creates hard links to identical files from a prior snapshot, consuming zero additional disk blocks.
Upstream Rationale: Traditional full backups duplicate identical files across storage arrays, wasting disk space and I/O bandwidth. --link-dest utilizes Linux filesystem hard links to create instant, read-accessible, deduplicated differential backups.
rsync(1)— Linux man page, rsync project: https://download.samba.org/pub/rsync/rsync.1- rsync Project Official Website: https://rsync.samba.org/
- rsync Source Repository: https://github.com/WayneD/rsync