==================================================================
RSYNC
THE COMPLETE REFERENCE GUIDE
==================================================================
Author : Tushar Sonawane - Nakshatra Systems
Date : 09 September 2026
============================================================
TABLE OF CONTENTS
------------------------------------------------------------------
1. What Is rsync?
2. Version Check
3. Basic Syntax
4. The Trailing-Slash Rule (Important)
5. Core Sync Cases
6. Using rsync Over SSH
7. rsync Daemon Mode
8. Preview Changes Before Running (Dry Run)
9. Verbose Output & Progress
10. Archive Mode (-a) In Depth
11. Compression for Slow Links
12. Excluding and Including Files
13. Mirroring: Deleting Extraneous Files
14. Limiting Bandwidth
15. Resuming Interrupted Transfers
16. Backing Up Overwritten Files
17. Space-Efficient Incremental Backups (--link-dest)
18. Checksum-Based Comparison
19. Filtering by File Size
20. Only Copy Newer Files
21. Copying Specific Files
22. Move Semantics: Delete Source After Transfer
23. Preserving Extra Metadata
24. Staying Within One Filesystem
25. Options Quick Reference
26. Common Recipes at a Glance
27. Troubleshooting Tips
==================================================================
==================================================================
1. WHAT IS RSYNC?
==================================================================
rsync ("remote sync") is a fast, versatile file-copying and
synchronization tool for Unix-like systems. Its core advantage
is the rsync algorithm: it transfers only the differences (deltas)
between the source and destination, rather than copying every file
in full. This makes it ideal for backups, mirroring, deployments,
and keeping large directory trees in sync over slow or metered
links.
Key strengths:
- Copies only changed portions of files (delta transfer)
- Works locally or over SSH/rsync daemon for remote transfers
- Preserves permissions, ownership, timestamps, and symlinks
- Supports exclude/include filtering, compression, and
bandwidth limiting
- Can resume interrupted transfers and perform incremental
backups
==================================================================
2. INSTALLATION
==================================================================
rsync --version
==================================================================
3. BASIC SYNTAX
==================================================================
rsync [OPTIONS] SOURCE DESTINATION
SOURCE and DESTINATION can each be a local path, or a remote
path in the form user@host:/path (SSH transport) or
rsync://host/module or host::module (rsync daemon protocol).
==================================================================
4. THE TRAILING-SLASH RULE (IMPORTANT!)
==================================================================
The single most common source of rsync confusion is whether the
SOURCE path ends with a slash.
--- 4.1 Source WITHOUT trailing slash -----------------------------
Copies the source directory itself into the destination,
creating a nested folder.
Example:
rsync -av /usr/local/sbin /home/user/backup/
What it does:
Result: /home/user/backup/sbin/...
(the 'sbin' folder is created inside backup/)
--- 4.2 Source WITH trailing slash ---------------------------------
Copies the CONTENTS of the source directory into the
destination, without creating a nested folder.
Example:
rsync -av /home/user/docs/ /home/user/backup/
What it does:
Result: /home/user/backup/...
(contents of docs/ land directly inside backup/)
Rule of thumb: "a trailing slash means copy what's inside,
not the folder itself."
==================================================================
5. CORE SYNC CASES
==================================================================
--- 5.1 Local to Local Copy -----------------------------------------
Sync or copy files between two directories on the same machine.
Example:
rsync -av /source/folder/ /destination/folder/
What it does:
-a = archive mode (recursive, preserves permissions/times/
symlinks)
-v = verbose, prints each file transferred
--- 5.2 Local to Remote (Push / Upload) -----------------------------
Send files from your local machine to a remote server over SSH.
Example:
rsync -av /local/folder/ user@remote_host:/remote/folder/
What it does:
Prompts for the SSH password (or uses your SSH key) and
pushes files to the remote path.
--- 5.3 Remote to Local (Pull / Download) ---------------------------
Fetch files from a remote server down to your local machine.
Example:
rsync -av user@remote_host:/remote/folder/ /local/folder/
What it does:
Same as above, but source and destination are swapped --
remote is now the SOURCE.
--- 5.4 Remote to Remote --------------------------------------------
Sync directly between two remote hosts.
Example:
rsync -av user1@host1:/path/to/source/ \
user2@host2:/path/to/destination/
What it does:
Useful for server-to-server migrations without staging
files locally.
==================================================================
6. USING RSYNC OVER SSH
==================================================================
--- 6.1 Specifying a Custom SSH Port --------------------------------
When the remote SSH server listens on a non-default port.
Example:
rsync -av -e "ssh -p 2222" /local/folder/ \
user@remote_host:/remote/folder/
What it does:
-e defines the remote shell command; here it tells rsync to
run ssh -p 2222.
--- 6.2 Using a Specific SSH Private Key -----------------------------
When authenticating with a non-default identity file.
Example:
rsync -av -e "ssh -i ~/.ssh/id_rsa_deploy" /local/folder/ \
user@remote_host:/remote/folder/
What it does:
Passes -i to ssh so it uses the specified key instead of
the default.
--- 6.3 Combining Custom Port and Key --------------------------------
Both options can be combined in the same -e string.
Example:
rsync -av -e "ssh -p 2222 -i ~/.ssh/id_rsa_deploy" \
/local/ user@host:/remote/
==================================================================
7. RSYNC DAEMON MODE
==================================================================
Instead of SSH, rsync can talk to a dedicated rsync daemon
(rsyncd) listening on TCP port 873. This is common for public
mirrors and high-throughput internal transfers, and does not
require an OS user account or SSH.
--- 7.1 Pulling From a Public rsync Daemon ---------------------------
Example:
rsync -av rsync://rsync.example.com/module_name/ \
/local/destination/
--- 7.2 Alternate Daemon Syntax (double-colon) -----------------------
The host::module notation is equivalent to the rsync:// URL
form.
Example:
rsync -av rsync.example.com::module_name/ /local/destination/
==================================================================
8. PREVIEW CHANGES BEFORE RUNNING (DRY RUN)
==================================================================
--- 8.1 Dry Run -------------------------------------------------------
Shows exactly what rsync WOULD do, without copying, deleting, or
modifying anything. Always run this before a destructive sync
(especially with --delete).
Example:
rsync -avn /source/ /destination/
What it does:
-n (or --dry-run) simulates the transfer and lists affected
files only
--- 8.2 Dry Run with Itemized Change Summary -------------------------
Shows a compact per-file code describing exactly what would
change (new file, size change, permission change, etc.).
Example:
rsync -avn --itemize-changes /source/ /destination/
What it does:
e.g. '>f+++++++++' = a new file would be sent
'.f...p....' = only permissions would change
==================================================================
9. VERBOSE OUTPUT & PROGRESS
==================================================================
--- 9.1 Verbose Mode ---------------------------------------------------
Example:
rsync -av /source/ /destination/
--- 9.2 Progress Bar for Large Transfers --------------------------------
Shows a live per-file progress bar and keeps partially-copied
files if interrupted.
Example:
rsync -avP /source/ /destination/
What it does:
-P = --partial --progress combined
--- 9.3 Human-Readable Sizes with Summary Stats -------------------------
Example:
rsync -avh --stats /source/ /destination/
==================================================================
10. ARCHIVE MODE (-a) IN DEPTH
==================================================================
Archive mode is the standard flag for backups because it
preserves the metadata that matters most:
rsync -a /source/ /destination/
# equivalent to: rsync -rlptgoD /source/ /destination/
-r recursive into subdirectories
-l copy symlinks as symlinks (not their targets)
-p preserve permission bits
-t preserve modification timestamps
-g preserve group ownership
-o preserve owner (root only)
-D preserve device and special files
==================================================================
11. COMPRESSION FOR SLOW LINKS
==================================================================
--- 11.1 Compress Data In Transit -----------------------------------
Compresses file data during the transfer to save bandwidth --
useful over slow WAN/SSH links, less useful on a fast LAN.
Example:
rsync -avz /local/folder/ user@remote_host:/remote/folder/
What it does:
-z enables compression; CPU trade-off for reduced network
usage
==================================================================
12. EXCLUDING AND INCLUDING FILES
==================================================================
--- 12.1 Exclude a Single Pattern -------------------------------------
Example:
rsync -av --exclude '*.log' /source/ /destination/
--- 12.2 Exclude Multiple Patterns ------------------------------------
Repeat --exclude for each pattern.
Example:
rsync -av --exclude '*.log' --exclude 'tmp/' \
--exclude '.git/' /source/ /destination/
--- 12.3 Exclude Using a Pattern File ----------------------------------
Store patterns in a file, one per line, and reference it.
Example:
rsync -av --exclude-from='exclude-list.txt' \
/source/ /destination/
# exclude-list.txt contents:
*.log
*.tmp
node_modules/
.git/
--- 12.4 Include Overrides Within an Exclude Pattern -------------------
Include specific files, then exclude everything else -- order
matters, rsync applies rules top-to-bottom.
Example:
rsync -av --include '*.txt' --exclude '*' \
/source/ /destination/
What it does:
Only .txt files are copied; every other file is excluded by
the trailing --exclude '*'
==================================================================
13. MIRRORING: DELETING EXTRANEOUS FILES
==================================================================
--- 13.1 True Mirror with --delete -------------------------------------
By default rsync never deletes files. --delete removes files
from the destination that no longer exist in the source, making
destination an exact mirror.
Example:
rsync -av --delete /source/ /destination/
What it does:
Use with -n first to preview what would be deleted -- this
is destructive
--- 13.2 Delete Excluded Files Too --------------------------------------
By default, excluded files are left alone on the destination
even with --delete. This forces their removal as well.
Example:
rsync -av --delete --delete-excluded --exclude '*.tmp' \
/source/ /destination/
==================================================================
14. LIMITING BANDWIDTH
==================================================================
--- 14.1 Throttle Transfer Speed -----------------------------------------
Caps transfer speed to avoid saturating a shared network link.
Example:
rsync -av --bwlimit=2000 /local/ user@remote_host:/remote/
What it does:
--bwlimit is in KB/s, so 2000 = ~2 MB/s
==================================================================
15. RESUMING INTERRUPTED TRANSFERS
==================================================================
--- 15.1 Keep Partial Files on Interruption -------------------------------
If the connection drops mid-transfer, keeps the incomplete file
instead of deleting it.
Example:
rsync -av --partial /source/ /destination/
--- 15.2 Resume Large Interrupted Files -----------------------------------
Appends to an existing partial file instead of restarting it
from byte zero -- ideal for very large files over unstable
connections.
Example:
rsync -av --partial --append /source/bigfile.iso \
/destination/
What it does:
--append assumes the existing partial data is correct and
only transfers what's missing
==================================================================
16. BACKING UP OVERWRITTEN FILES
==================================================================
--- 16.1 Simple Backup on Overwrite -----------------------------------------
Before overwriting or deleting a destination file, renames the
old version with a ~ suffix instead of discarding it.
Example:
rsync -av --backup /source/ /destination/
--- 16.2 Backup Into a Separate Directory -----------------------------------
Sends replaced/deleted files into a dedicated backup folder
rather than leaving ~ files scattered in place.
Example:
rsync -av --backup --backup-dir=/backups/$(date +%F) \
/source/ /destination/
==================================================================
17. SPACE-EFFICIENT INCREMENTAL BACKUPS (--link-dest)
==================================================================
--link-dest enables classic "Time Machine"-style incremental
backups: each backup folder looks like a full snapshot, but
files unchanged since the last backup are hard-linked (not
duplicated), saving huge amounts of disk space.
Example:
rsync -av --link-dest=/backups/2026-07-13 /source/ \
/backups/2026-07-14
What it does:
- Copies only files that changed since the 2026-07-13
snapshot
- Hard-links unchanged files from 2026-07-13 into the new
2026-07-14 folder
- Each dated folder can be browsed independently as a full
backup, at a fraction of the disk cost
==================================================================
18. CHECKSUM-BASED COMPARISON
==================================================================
--- 18.1 Force Checksum Comparison -----------------------------------------
By default rsync decides whether a file changed using size +
modification time (fast). --checksum instead hashes file
contents, catching changes that don't alter size/mtime (slower,
more thorough).
Example:
rsync -avc /source/ /destination/
==================================================================
19. FILTERING BY FILE SIZE
==================================================================
--- 19.1 Skip Large Files -----------------------------------------------
Example:
rsync -av --max-size=100M /source/ /destination/
--- 19.2 Skip Tiny Files -------------------------------------------------
Excludes files below a given size -- useful for skipping empty
placeholder files.
Example:
rsync -av --min-size=1K /source/ /destination/
==================================================================
20. ONLY COPY NEWER FILES
==================================================================
--- 20.1 Skip Files Newer on the Destination -----------------------------
Prevents rsync from overwriting a destination file that's newer
than the source's -- protects against accidentally clobbering
local edits.
Example:
rsync -avu /source/ /destination/
What it does:
-u = --update
==================================================================
21. COPYING SPECIFIC FILES
==================================================================
--- 21.1 Copy a Single File ------------------------------------------------
SOURCE can be a file instead of a directory.
Example:
rsync -av /source/report.pdf user@remote_host:/remote/folder/
--- 21.2 Copy Only Files Matching a List ------------------------------------
Use --files-from to sync an explicit list of relative paths from
a base directory.
Example:
rsync -av --files-from='list.txt' /source/ /destination/
# list.txt contents (paths relative to /source/):
docs/readme.md
images/logo.png
==================================================================
22. MOVE SEMANTICS: DELETE SOURCE AFTER TRANSFER
==================================================================
--- 22.1 Move Files (Remove From Source Once Copied) ------------------------
Removes each source file once it has been successfully
transferred -- effectively a network-aware "move".
Example:
rsync -av --remove-source-files /source/ /destination/
Note:
This does not remove now-empty source directories; combine
with a separate cleanup (e.g. find -empty -delete) if
needed.
==================================================================
23. PRESERVING EXTRA METADATA
==================================================================
--- 23.1 Preserve Hard Links -------------------------------------------------
Recreates hard links between files at the destination instead of
turning them into separate copies.
Example:
rsync -avH /source/ /destination/
--- 23.2 Preserve ACLs and Extended Attributes -------------------------------
Carries POSIX ACLs and filesystem extended attributes (e.g.
SELinux contexts) across.
Example:
rsync -avAX /source/ /destination/
What it does:
-A = --acls, -X = --xattrs
==================================================================
24. STAYING WITHIN ONE FILESYSTEM
==================================================================
--- 24.1 Don't Cross Mount Points ---------------------------------------------
Skips other filesystems mounted inside the source tree (e.g. an
external drive mounted under /source/media).
Example:
rsync -avx /source/ /destination/
What it does:
-x = --one-file-system
==================================================================
25. OPTIONS QUICK REFERENCE
==================================================================
FLAG MEANING EQUALS
------------------------------------------------------------------
-a Archive mode: recursive + preserves -rlptgoD
symlinks, permissions, times, group, owner,
devices
-r Recurse into directories --
-l Copy symlinks as symlinks --
-p Preserve permissions --
-t Preserve modification times --
-g Preserve group --
-o Preserve owner (root only) --
-D Preserve device and special files --
-v Verbose output --
-vv / -vvv Increasing verbosity --
-z Compress data during transfer --
-h Human-readable numbers --
-n Dry run -- show what would happen --dry-run
-P Show progress + keep partial files --partial
--progress
-u Skip files newer on receiver --update
-c Use checksum, not time/size, to decide --checksum
changes
-e Specify remote shell (e.g. ssh) --
-q Quiet mode --
-b Make backups of replaced files --
-x Do not cross filesystem boundaries --one-file-
-system
--delete Delete files on receiver not present on --
sender
--exclude Exclude files matching pattern --
--include Include files matching pattern --
--exclude-from Read exclude patterns from a file --
--include-from Read include patterns from a file --
--bwlimit Limit transfer bandwidth (KB/s) --
--max-size Skip files larger than SIZE --
--min-size Skip files smaller than SIZE --
--link-dest Hardlink to files unchanged from DIR --
(incremental backups)
--backup-dir Store backups in a separate directory --
--partial Keep partially transferred files --
--append Continue/resume an interrupted transfer --
--itemize-changes Show a per-file change summary (like -i) --
--dry-run Same as -n --
--stats Show a transfer summary at the end --
==================================================================
26. COMMON RECIPES AT A GLANCE
==================================================================
GOAL COMMAND
------------------------------------------------------------------
Basic local backup rsync -av /src/ /dst/
Push to server rsync -avz -e ssh /src/ \
user@host:/dst/
Pull from server rsync -avz -e ssh \
user@host:/src/ /dst/
Exact mirror (deletes extras) rsync -av --delete /src/ /dst/
Dry run before mirroring rsync -avn --delete /src/ /dst/
Resumable large-file copy rsync -avP --partial --append \
/src/big.iso /dst/
Incremental snapshot backup rsync -av --link-dest=../prev \
/src/ ./new/
Exclude patterns from file rsync -av \
--exclude-from=ex.txt \
/src/ /dst/
Throttled transfer rsync -av --bwlimit=1000 \
/src/ /dst/
Custom SSH port rsync -av -e 'ssh -p 2222' \
/src/ user@host:/dst/
==================================================================
27. TROUBLESHOOTING TIPS
==================================================================
- "Permission denied": check destination directory permissions
or use sudo/rsync daemon with correct module permissions.
- Files re-copied every run despite no changes: clocks out of
sync between hosts, or use --checksum instead of relying on
mtime.
- Trailing slash confusion: re-read Section 4 -- this causes
the majority of "wrong folder nesting" reports.
- Slow over WAN: add -z for compression and consider
--bwlimit to avoid saturating the link.
- Interrupted large transfer: re-run the same command with
--partial --append (or -P) to resume rather than restart.
- Always test destructive operations (--delete) with
--dry-run (-n) first.
==================================================================