Rsync Command Reference

9 October 2025 · Updated 9 October 2025

commandsrsyncfile-transfersynchronizationbackup

Rsync transfers only the differences between a source and a destination, which is what makes it good for backups and large transfers over slow or intermittent links. This is the set of flags and patterns I actually use.

Basic Syntax

rsync [options] source destination

Key Features

Incremental transfers: Only copies changed files
Compression: Reduces bandwidth usage
Preservation: Maintains permissions, timestamps, ownership
Resume capability: Can continue interrupted transfers
Deletion handling: Sync deletions from source to destination

Essential Options

Option	Description
`-a`	Archive mode (recursive, preserves everything)
`-v`	Verbose output
`-z`	Compress during transfer
`-h`	Human-readable output
`-P`	Show progress and allow resume
`--delete`	Delete files in destination not in source
`-n` or `--dry-run`	Preview without making changes
`-r`	Recursive
`-u`	Skip newer files at destination
`--exclude`	Exclude files/directories
`--include`	Include specific patterns
`-e`	Specify remote shell (e.g., ssh)

Common Flag Combinations

# Most common: archive, verbose, compress, progress
rsync -avzP source/ destination/

# Archive with delete (perfect sync)
rsync -avz --delete source/ destination/

# Dry run to preview changes
rsync -avzn source/ destination/

# Human-readable with stats
rsync -avzh --stats source/ destination/

Local to Local

Basic Sync

# Sync directory contents
rsync -av /source/directory/ /destination/directory/

# Note: Trailing slash matters!
# /source/    -> copies contents into destination
# /source     -> copies directory itself into destination

Backup with Deletion

# Make destination an exact mirror
rsync -av --delete /source/ /backup/

Exclude Patterns

# Exclude specific files/directories
rsync -av --exclude='*.tmp' --exclude='cache/' /source/ /dest/

# Exclude from file
rsync -av --exclude-from='exclude.txt' /source/ /dest/

Remote Transfers (SSH)

Linux to Linux

# Upload to remote server
rsync -avzP /local/directory/ user@remote:/remote/directory/

# Download from remote server
rsync -avzP user@remote:/remote/directory/ /local/directory/

# Custom SSH port
rsync -avzP -e "ssh -p 2222" /local/ user@remote:/remote/

# Specific SSH key
rsync -avzP -e "ssh -i ~/.ssh/id_rsa" /local/ user@remote:/remote/

Windows to Linux (via WSL or Cygwin)

# From WSL or Git Bash
rsync -avzP /mnt/c/Users/username/Documents/ user@remote:/backups/

# Or using Windows paths (Git Bash)
rsync -avzP /c/Users/username/Documents/ user@remote:/backups/

Linux to Windows (Windows with Rsync)

# Windows must have rsync (via WSL, Cygwin, or cwRsync)
rsync -avzP /local/data/ user@windows-host:/c/Backups/

Advanced Use Cases

Bandwidth Limiting

# Limit to 1MB/s (1000 KB/s)
rsync -avzP --bwlimit=1000 /source/ user@remote:/dest/

Backup with Date Suffix

#!/bin/bash
DATE=$(date +%Y%m%d)
rsync -avzP /source/ user@remote:/backups/backup_$DATE/

Incremental Backups with Hard Links

# First backup
rsync -avzP /source/ /backup/latest/

# Subsequent backups (links unchanged files)
rsync -avzP --link-dest=/backup/latest/ /source/ /backup/$(date +%Y%m%d)/

Sync Only Newer Files

# Don't overwrite newer files at destination
rsync -avzu /source/ /destination/

Mirror with Specific Exclusions

rsync -avz --delete \
  --exclude='node_modules/' \
  --exclude='.git/' \
  --exclude='*.log' \
  /project/ user@remote:/var/www/project/

Copy with Specific Permissions

# Set specific permissions on destination
rsync -avz --chmod=D755,F644 /source/ /destination/

Resume Partial Transfers

# -P enables both --partial and --progress
rsync -avzP /large/files/ user@remote:/destination/

Dry Run (Preview Changes)

Always test with dry-run first:

# Preview what would be transferred
rsync -avzn --delete /source/ /destination/

# Verbose dry run with item changes
rsync -avzni --delete /source/ /destination/

Useful Patterns

Website Deployment

#!/bin/bash
# deploy.sh - Deploy website to production

rsync -avz --delete \
  --exclude='.git' \
  --exclude='node_modules' \
  --exclude='.env' \
  /local/website/ user@webserver:/var/www/html/

Automated Backup Script

#!/bin/bash
# backup.sh - Daily backup script

SOURCE="/home/user/documents"
DEST="user@backup-server:/backups/$(hostname)"
LOG="/var/log/backup.log"

rsync -avzP --delete \
  --exclude='*.tmp' \
  --exclude='cache/' \
  --log-file="$LOG" \
  "$SOURCE/" "$DEST/"

echo "Backup completed at $(date)" >> "$LOG"

Selective Sync

# Only sync specific file types
rsync -avz --include='*.pdf' --include='*/' --exclude='*' \
  /documents/ /backup/pdfs/

Two-Way Sync (Use with Caution)

# Sync both directions (be careful with --delete)
rsync -avzu /local/ user@remote:/remote/
rsync -avzu user@remote:/remote/ /local/

Common Patterns Explained

Trailing Slash Behavior

# WITH trailing slash: copies CONTENTS
rsync -av /source/ /dest/
# Result: /dest/file1, /dest/file2

# WITHOUT trailing slash: copies DIRECTORY
rsync -av /source /dest/
# Result: /dest/source/file1, /dest/source/file2

Delete Options

Option	Behavior
`--delete`	Delete files in dest not in source
`--delete-before`	Delete before transfer (default)
`--delete-after`	Delete after transfer
`--delete-excluded`	Delete excluded files from dest

Progress and Logging

# Show progress per file
rsync -avP /source/ /dest/

# Show overall stats
rsync -avz --stats /source/ /dest/

# Log to file
rsync -avz --log-file=/var/log/rsync.log /source/ /dest/

# Verbose item changes
rsync -avzi /source/ /dest/

Windows-Specific Notes

Using Rsync on Windows

Options:

WSL (Windows Subsystem for Linux): Native rsync support
Git Bash: Includes rsync (via MinGW)
Cygwin: Full Unix environment with rsync
cwRsync: Native Windows port of rsync

WSL Example

# In WSL, access Windows files via /mnt/
rsync -avzP /mnt/c/Users/username/Documents/ user@remote:/backup/

# From Windows to WSL
rsync -avzP /mnt/c/source/ /home/username/backup/

PowerShell Wrapper

# Use WSL rsync from PowerShell
wsl rsync -avzP /mnt/c/Users/username/Documents/ user@remote:/backup/

Performance Tips

Use compression (-z) for slow networks, skip for fast local networks
Limit bandwidth (–bwlimit) to avoid saturating connection

Use SSH connection reuse for multiple transfers:

# In ~/.ssh/config
Host backupserver
    ControlMaster auto
    ControlPath ~/.ssh/control-%r@%h:%p
    ControlPersist 10m

For many small files, consider archiving first:

tar czf - /source | ssh user@remote "tar xzf - -C /dest"

Error Handling

Common Errors

Permission Denied:

# Use sudo on remote end
rsync -avz /local/ user@remote:/root/backup/ \
  --rsync-path="sudo rsync"

Host Key Verification Failed:

# Add host key first
ssh-keyscan remote >> ~/.ssh/known_hosts

Disk Space Issues:

# Check space before transfer
ssh user@remote "df -h /destination"

Comparison with Other Tools

Feature	Rsync	SCP	SFTP
Incremental transfer	Yes	No	No
Resume capability	Yes	No	Yes
Compression	Yes	Yes	Yes
Bidirectional sync	Partial	No	No
Speed (large files)	Fast	Fast	Medium
Speed (many small files)	Medium	Slow	Slow
Deletion handling	Yes	No	Manual

SCP Command Reference - Quick one-off transfers
SFTP Command Reference - Interactive file transfer
File Transfer Tool Selection - Choose the right tool