← Full reference

rsync

Sync directories locally and over SSH — copies only changes, can delete extras and exclude files

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

CommandResult
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

OptionWhat it does
-aarchive mode = -rlptgoD: recursive, links, permissions, times, group, owner, devices
-rrecursion only — no permissions, times or owners
-Hpreserve hard links (not part of -a)
-A / -Xpreserve ACLs / extended attributes
-Lcopy files instead of symbolic links
-kreplace links to directories with the directories themselves
--safe-linksskip links pointing outside the copied tree
-xdon't cross file system boundaries
--chown=user:groupset the owner at the destination
--chmod=D750,F640set permissions: D — for directories, F — for files; u+x, go-w also work
--numeric-idstransfer UID/GID as numbers without mapping names
--no-perms, --no-owner, --no-groupdrop a single item from -a

Which files to take

OptionWhat 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=filepatterns from a file, one per line
-Ftake rules from .rsync-filter files in the source directories
-Cskip what's usually not needed: .git, .svn, *.o, core and the like
--files-from=listcopy only the paths listed in a file (relative to the source)
-Rkeep the full source path at the destination (src/a/b → dst/src/a/b)
-mdon't create empty directories (handy with --include/--exclude)
--max-size=100M / --min-size=1kskip files larger / smaller than given
--existingupdate only files that already exist at the destination
--ignore-existingdon't touch files that already exist at the destination
-udon't overwrite files that are newer at the destination

How to compare

OptionWhat it does
(default)a file is the same if size and modification time match
-ccompare by checksum — slow but reliable
--size-onlycompare size only
-Itransfer even files with the same size and time
--modify-window=1treat times as equal if they differ by up to 1 second (FAT, network file systems)
-Wtransfer whole files without looking for changed chunks (faster locally)

Deletion and backups

OptionWhat it does
--deletedelete files at the destination that aren't in the source
--delete-afterdelete after the transfer, not before
--delete-excludedalso delete excluded files at the destination
--max-delete=Ndon't delete more than N files (protection against mistakes, code 25)
--remove-source-filesremove transferred files from the source (a move; directories stay)
-bkeep replaced and deleted files with a ~ suffix
--backup-dir=dirkeep them in a separate directory
--suffix=.baka custom suffix for backups
--link-dest=dirmake unchanged files hard links to files in a directory — space-efficient daily snapshots

Transfer and network

OptionWhat it does
-n (--dry-run)change nothing, only show what would be done
-zcompress 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=10mlimit the speed
-P--partial --progress: keep partially transferred files and show progress
--partialdon't delete a partially transferred file — resume on the next run
--inplacewrite directly into the destination file, without a temporary copy
--timeout=60abort if no data is exchanged for 60 seconds
--mkpathcreate missing directories in the destination path

Output

OptionWhat it does
-vprint transferred files and a summary
-iprint, for each file, what exactly changed (format below)
-hhuman-readable sizes
--progress / --info=progress2per-file progress / overall progress
--statsdetailed statistics at the end
--log-file=filewrite a log to a file
-qquiet 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

CodeMeaning
0success
23some files weren't transferred (no access, no source)
24some files vanished during the copy
25--max-delete kicked in
12, 255connection 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