rsync copies files and directories so that the destination matches the source. It compares size and modification time and transfers only what differs, and for changed files over the network — only the changed chunks. That's why a repeat run is almost instant. It works locally and between machines over SSH; rsync must also be installed on the remote side.
Syntax
rsync [options] source… destination
rsync [options] source… user@host:/path # to a remote machine over SSH
rsync [options] user@host:/path destination # from a remote machine
rsync [options] source # no destination — just a file list
Trailing slash on the source
| Command | Result |
|---|
rsync -a src dst/ | you get dst/src/… — the directory itself is copied |
rsync -a src/ dst/ | you get dst/… — the directory's contents are copied |
For a source directory, a trailing slash on the destination changes nothing. For a single file it matters: rsync -a file dst creates a file dst, while rsync -a file dst/ creates a directory dst with the file inside.
What to preserve
| Option | What it does |
|---|
-a | archive mode = -rlptgoD: recursive, links, permissions, times, group, owner, devices |
-r | recursion only — no permissions, times or owners |
-H | preserve hard links (not part of -a) |
-A / -X | preserve ACLs / extended attributes |
-L | copy files instead of symbolic links |
-k | replace links to directories with the directories themselves |
--safe-links | skip links pointing outside the copied tree |
-x | don't cross file system boundaries |
--chown=user:group | set the owner at the destination |
--chmod=D750,F640 | set permissions: D — for directories, F — for files; u+x, go-w also work |
--numeric-ids | transfer UID/GID as numbers without mapping names |
--no-perms, --no-owner, --no-group | drop a single item from -a |
Which files to take
| Option | What it does |
|---|
--exclude='pattern' | don't copy matching files and directories |
--include='pattern' | copy even if a matching --exclude follows |
--exclude-from=file / --include-from=file | patterns from a file, one per line |
-F | take rules from .rsync-filter files in the source directories |
-C | skip what's usually not needed: .git, .svn, *.o, core and the like |
--files-from=list | copy only the paths listed in a file (relative to the source) |
-R | keep the full source path at the destination (src/a/b → dst/src/a/b) |
-m | don't create empty directories (handy with --include/--exclude) |
--max-size=100M / --min-size=1k | skip files larger / smaller than given |
--existing | update only files that already exist at the destination |
--ignore-existing | don't touch files that already exist at the destination |
-u | don't overwrite files that are newer at the destination |
How to compare
| Option | What it does |
|---|
| (default) | a file is the same if size and modification time match |
-c | compare by checksum — slow but reliable |
--size-only | compare size only |
-I | transfer even files with the same size and time |
--modify-window=1 | treat times as equal if they differ by up to 1 second (FAT, network file systems) |
-W | transfer whole files without looking for changed chunks (faster locally) |
Deletion and backups
| Option | What it does |
|---|
--delete | delete files at the destination that aren't in the source |
--delete-after | delete after the transfer, not before |
--delete-excluded | also delete excluded files at the destination |
--max-delete=N | don't delete more than N files (protection against mistakes, code 25) |
--remove-source-files | remove transferred files from the source (a move; directories stay) |
-b | keep replaced and deleted files with a ~ suffix |
--backup-dir=dir | keep them in a separate directory |
--suffix=.bak | a custom suffix for backups |
--link-dest=dir | make unchanged files hard links to files in a directory — space-efficient daily snapshots |
Transfer and network
| Option | What it does |
|---|
-n (--dry-run) | change nothing, only show what would be done |
-z | compress data during transfer over the network |
-e 'ssh -p 2222 -i ~/.ssh/key' | how to connect to the remote machine |
--rsync-path='sudo rsync' | which command to run on the remote side |
--bwlimit=10m | limit the speed |
-P | --partial --progress: keep partially transferred files and show progress |
--partial | don't delete a partially transferred file — resume on the next run |
--inplace | write directly into the destination file, without a temporary copy |
--timeout=60 | abort if no data is exchanged for 60 seconds |
--mkpath | create missing directories in the destination path |
Output
| Option | What it does |
|---|
-v | print transferred files and a summary |
-i | print, for each file, what exactly changed (format below) |
-h | human-readable sizes |
--progress / --info=progress2 | per-file progress / overall progress |
--stats | detailed statistics at the end |
--log-file=file | write a log to a file |
-q | quiet except for errors |
An -i line looks like >f.st...... path. The first character is what happens: > received, < sent, c created (directory, link), . attributes only, *deleting — deleted. The second is the type: f file, d directory, L link. Then letters in place of the dots show what differed: s size, t time, p permissions, o owner, g group. +++++++++ — a new file.
Exit codes
| Code | Meaning |
|---|
0 | success |
23 | some files weren't transferred (no access, no source) |
24 | some files vanished during the copy |
25 | --max-delete kicked in |
12, 255 | connection dropped / SSH error |
Examples
# mirror a directory: contents of /srv/app into /srv/backup/app
rsync -a /srv/app/ /srv/backup/app/
# first look at what will change and what will be deleted
rsync -avn --delete /srv/app/ /srv/backup/app/
# an exact mirror, deleting extras
rsync -a --delete /srv/app/ /srv/backup/app/
# without logs, dependencies and .git
rsync -a --exclude='*.log' --exclude='node_modules/' --exclude='.git/' ~/project/ /srv/app/
# only .conf, keeping the directory structure and without empty directories
rsync -am --include='*/' --include='*.conf' --exclude='*' /etc/ /srv/backup/etc-conf/
# deploy to a server over SSH with compression and progress
rsync -azh --progress ~/project/ deploy@example.com:/srv/app/
# non-standard SSH port and your own key
rsync -az -e 'ssh -p 2222 -i ~/.ssh/deploy' ~/project/ deploy@example.com:/srv/app/
# pull logs from a server to your machine
rsync -az deploy@example.com:/var/log/nginx/ ./nginx-logs/
# deploy with the right owner and permissions
rsync -a --chown=www-data:www-data --chmod=D755,F644 ./public/ /srv/app/public/
# a big file over an unstable network — with resume
rsync -P backup.tar.gz deploy@example.com:/srv/backup/
# daily snapshot: unchanged files are hard links to yesterday's
rsync -a --delete --link-dest=/srv/snap/yesterday /srv/app/ /srv/snap/today/
# show, for each file, what exactly differs
rsync -ai /srv/app/ /srv/backup/app/
Pitfalls
- A trailing slash on the source changes the result.
src and src/ are different commands: without the slash an extra src/ level appears inside the destination. Especially dangerous together with --delete.
--delete deletes without asking. If you mix up source and destination or point at the wrong directory, data is lost. Always run with -n first, and add --max-delete in scripts.
--delete doesn't touch excluded files. A file matched by --exclude stays at the destination. To delete it too, you need --delete-excluded.
- Exclude patterns.
--exclude=sub excludes sub at any level, --exclude=/sub — only at the source root. A trailing slash (node_modules/) — directories only.
- The order of
--include and --exclude matters: the first matching rule wins. To take only *.conf, you need --include='*/' (otherwise rsync won't descend into subdirectories), then --include='*.conf', and finally --exclude='*'.
- The destination is created only one level deep.
rsync -a src/ /no/such/path/ fails with "mkdir failed" if the parent directories don't exist. Create them beforehand or add --mkpath.
- Without a destination
rsync copies nothing, it prints a file list like ls -l. A forgotten argument is easy to miss.
- Same size and time — "the file hasn't changed". A file with different content but the same size and modification time is skipped by
rsync. To compare by content you need -c.
- Owners are preserved only by root. A regular user gets all files owned by themselves.
-a doesn't preserve hard links — you need -H for those.
rsync is needed on the remote machine too. Without it the SSH connection drops with the error "connection unexpectedly closed".
See also
ssh · tar · cp · find · cron · chown · ln