Version: 3.x
Purpose: Fast, versatile file-copying tool — local and remote, incremental delta transfer
Key feature: Only transfers changed portions of files (delta-transfer algorithm)
Config: No config file — all behavior controlled via CLI flags
Syntax
rsync [OPTIONS] SOURCE... DEST
rsync [OPTIONS] SOURCE... [USER@]HOST:DEST # push
rsync [OPTIONS] [USER@]HOST:SOURCE... DEST # pull
rsync [OPTIONS] SOURCE... rsync://[USER@]HOST/MOD # daemon push
rsync [OPTIONS] rsync://[USER@]HOST/MOD DEST # daemon pull
Trailing slash rule:
rsync src/ dest/ — copies contents of src into destrsync src dest/ — copies the directory itself into dest (creates dest/src/)
Core Options
| Short | Long | Description |
|---|
-a | --archive | Archive mode = -rlptgoD (recurse, links, perms, times, group, owner, devices) |
-r | --recursive | Recurse into directories |
-v | --verbose | Increase verbosity (stack: -vv, -vvv) |
-q | --quiet | Suppress non-error messages |
-h | --human-readable | Human-readable sizes |
-n | --dry-run | Show what would be done without doing it |
-i | --itemize-changes | Output change summary per file |
| --list-only | List files instead of transferring |
Transfer Behavior
| Short | Long | Description |
|---|
-c | --checksum | Skip based on checksum, not mod-time & size |
-u | --update | Skip files newer on receiver |
| --inplace | Update files in-place (no temp file) |
| --append | Append data to shorter files |
-W | --whole-file | Disable delta-transfer (copy whole files) |
-b | --backup | Make backups of overwritten files |
| --backup-dir=DIR | Store backups in DIR |
| --suffix=SUFFIX | Backup suffix (default: ~) |
| --remove-source-files | Delete source files after transfer |
| --ignore-existing | Skip files that exist on receiver |
| --max-size=SIZE | Don’t transfer files larger than SIZE |
| --min-size=SIZE | Don’t transfer files smaller than SIZE |
| --delay-updates | Put updated files into place at end |
-m | --prune-empty-dirs | Prune empty directory chains |
-R | --relative | Use relative pathnames |
Delete Options
| Long | Description |
|---|
--delete | Delete extraneous files from dest |
--delete-before | Delete on receiver before transfer |
--delete-during | Delete during transfer (default) |
--delete-after | Delete on receiver after transfer |
--delete-excluded | Also delete excluded files on receiver |
--force | Force deletion of non-empty directories |
--max-delete=NUM | Don’t delete more than NUM files |
Safety tip: Always use -n --delete first to preview deletions.
Preservation Options
| Short | Long | Description |
|---|
-p | --perms | Preserve permissions (in -a) |
-o | --owner | Preserve owner (root only, in -a) |
-g | --group | Preserve group (in -a) |
-t | --times | Preserve modification times (in -a) |
-U | --atimes | Preserve access times |
-N | --crtimes | Preserve creation times |
-l | --links | Copy symlinks as symlinks (in -a) |
-L | --copy-links | Transform symlinks into referent file |
-H | --hard-links | Preserve hard links |
-D | | --devices --specials (in -a) |
-A | --acls | Preserve ACLs (implies -p) |
-X | --xattrs | Preserve extended attributes |
| --chmod=CHMOD | Affect file/dir permissions |
-E | --executability | Preserve executability |
-S | --sparse | Efficiently handle sparse files |
| --numeric-ids | Don’t map uid/gid to names |
| --fake-super | Store privileged attrs using xattrs |
Filter & Exclude
| Short | Long | Description |
|---|
| --exclude=PATTERN | Exclude matching files |
| --include=PATTERN | Include matching files |
| --exclude-from=FILE | Read excludes from FILE |
| --include-from=FILE | Read includes from FILE |
-f | --filter=RULE | Add a filter rule |
-C | --cvs-exclude | Auto-ignore CVS-style files |
| --files-from=FILE | Read source file list from FILE |
-0 | --from0 | Null-terminated input |
Pattern Syntax
| Pattern | Matches |
|---|
*.log | Any file ending in .log |
/foo | foo in the transfer root only |
foo/ | Only directories named foo |
foo/** | Everything inside foo/ |
**/bar | Any bar at any depth |
Filter Rule Prefixes
| Prefix | Meaning |
|---|
• | Exclude |
• | Include |
. | Merge file |
: | Dir-merge file (per-directory rules) |
H | Hide (sending side) |
P | Protect (from deletion on receiver) |
Compression
| Short | Long | Description |
|---|
-z | --compress | Compress during transfer |
| --compress-level=NUM | Level 0–9 |
| --compress-choice=STR | zlib · lz4 · zstd · none |
| --skip-compress=LIST | Skip for listed suffixes |
Network & Remote Shell
| Short | Long | Description |
|---|
-e | --rsh=COMMAND | Specify remote shell (default: ssh) |
| --rsync-path=PROGRAM | Path to rsync on remote |
| --port=PORT | Specify port |
| --bwlimit=RATE | Limit bandwidth (K, M, G suffixes) |
| --timeout=SECONDS | I/O timeout |
| --contimeout=SECONDS | Connection timeout |
| Short | Long | Description |
|---|
-P | | --partial --progress |
| --partial | Keep partially transferred files |
| --partial-dir=DIR | Put partials in DIR |
| --progress | Show per-file progress |
| --info=progress2 | Single total progress bar |
| --stats | Print transfer statistics |
-T | --temp-dir=DIR | Create temp files in DIR |
Itemize Output (-i)
11-character string: YXcstpoguax
| Pos | Char | Meaning |
|---|
| 0 | Y | < sent · > received · c local change · . not updated |
| 1 | X | f file · d dir · L symlink · D device |
| 2 | c | Checksum differs |
| 3 | s | Size differs |
| 4 | t | Mtime differs |
| 5 | p | Permissions differ |
| 6 | o | Owner differs |
| 7 | g | Group differs |
| 9 | a | ACL differs |
| 10 | x | Xattr differs |
. = no change, + = newly created.
Daemon Mode
rsync --daemon --config=/etc/rsyncd.conf
rsyncd.conf Key Options
[module_name]
path = /data/share
read only = yes
auth users = user1, user2
secrets file = /etc/rsyncd.secrets
hosts allow = 192.168.1.0/24
hosts deny = *
max connections = 10
use chroot = yes
fake super = yes
transfer logging = yes
log file = /var/log/rsyncd.log
refuse options = delete
Common Recipes
# Basic copy (archive + verbose + progress)
rsync -avhP src/ dest/
# Mirror with delete (exact copy)
rsync -avh --delete src/ dest/
# Dry run first (always!)
rsync -avhn --delete src/ dest/
# Remote backup over SSH
rsync -avhP --delete -e 'ssh -p 22' /data/ user@backup:/data/
# Custom SSH key
rsync -avhP -e 'ssh -i ~/.ssh/mykey' src/ user@host:dest/
# Bandwidth-limited transfer
rsync -avhP --bwlimit=50M src/ user@remote:dest/
# Resume interrupted transfer
rsync -avhP --partial src/ dest/
# Exclude patterns
rsync -avh --exclude='*.log' --exclude='.cache/' --exclude='node_modules/' src/ dest/
# Include only certain files
rsync -avh --include='*.jpg' --include='*/' --exclude='*' src/ dest/
# Preserve everything (ACLs, xattrs, hard links, sparse)
rsync -avhHAXS --numeric-ids src/ dest/
# Full system backup (as root)
rsync -avhHAXS --numeric-ids --delete \\
--exclude={"/dev/*","/proc/*","/sys/*","/tmp/*","/run/*","/mnt/*"} \\
/ /mnt/backup/
# Sync to NAS
rsync -avhP --delete -e 'ssh -i ~/.ssh/nas_key' \\
/home/user/data/ nas:/volume1/backup/data/
# Show total progress (single progress bar)
rsync -avh --info=progress2 src/ dest/
# Verify existing copy with checksums
rsync -avhcn src/ dest/
# Speed up on LAN (skip compression, whole files)
rsync -avhW --no-compress src/ dest/
# Cron job (quiet, log to file)
rsync -ah --delete --log-file=/var/log/rsync-backup.log src/ dest/
rsync vs. Alternatives
| Feature | rsync | Robocopy | rclone | FreeFileSync |
|---|
| Delta transfer | Yes | No | Partial | No |
| Remote (SSH) | Yes | No (SMB) | Yes (cloud) | No |
| Cloud storage | No | No | Yes | Yes |
| Preserve Unix perms | Yes | N/A | Partial | No |
| Bandwidth limit | Yes | Yes | Yes | No |
| Resumable | Yes (-P) | Yes (/Z) | Yes | Yes |
| Platform | Linux/macOS/WSL | Windows | Cross-platform | Cross-platform |
Exit Codes
| Code | Meaning |
|---|
0 | Success |
1 | Syntax/usage error |
2 | Protocol incompatibility |
3 | Errors selecting files |
10 | Socket I/O error |
11 | File I/O error |
12 | Protocol data stream error |
20 | Received SIGUSR1/SIGINT |
23 | Partial transfer due to error |
24 | Partial transfer — vanished source files |
25 | --max-delete limit reached |
30 | Timeout |
Source: man rsync(1) · man rsyncd.conf(5) · rsync.samba.org