rsync Commands

Basic Copy

-a (archive) is the flag you almost always want: recursive, keeps permissions, times, owner, group, symlinks, and devices. The rsync command builder assembles one of these interactively.

rsync -a with no -v prints nothing on success, which is what you want in cron.

Over SSH

Remote paths are user@host:/path. rsync must be installed at both ends. It runs over SSH by default, so keys, ~/.ssh/config aliases, and agent forwarding all apply; see the SSH cheat sheet.

Copy between two remote servers: rsync cannot take two remote paths in one command. Log into one and push to the other, or forward your agent so the first server can authenticate to the second.

ssh -A user@server1 'rsync -avz /var/www/ user@server2:/var/www/'

A connection that fails with exit code 255 is an SSH problem, not an rsync one. See Connection refused and Permission denied (publickey).

Flags Explained

Paste any command into the rsync flag explainer to decode it.

-avz is the standard remote copy, -avh the standard local one, and -avzP when the link might drop.

Dry Run

Run every new rsync command with -n first, and always before --delete.

In itemized output, >f is a file being sent, cd a directory being created, *deleting a deletion, and the dots after the type mark which attributes changed (s size, t time, p permissions, o owner).

Exclude and Include

Patterns match relative to the top of the transfer. A trailing / matches directories only, a leading / anchors the pattern to the transfer root, and * does not cross a / (** does).

Include and exclude rules are checked in order and the first match wins, which is why --include comes before --exclude '*'. An exclude that "does not work" is almost always anchored wrong: --exclude 'src/node_modules' does not match when the transfer root is src/, but --exclude '/node_modules' does.

Delete and Mirror

--delete makes the destination match the source exactly, including removing files. Combined with a wrong path or a missing trailing slash it can empty a directory, so dry run first.

--delete only deletes inside directories that are part of the transfer. rsync -av --delete src dest/ (no trailing slash) syncs dest/src/ and never touches the rest of dest.

Progress and Resume

For a transfer that takes hours, start it inside tmux or screen so a dropped SSH session does not kill it; see the tmux cheat sheet. If the SSH session itself keeps dropping, see Broken pipe.

Permissions and Ownership

Preserving owner means rsync on the receiving end runs as root, either because you are root or via --rsync-path="sudo rsync". Otherwise files are owned by the connecting user and rsync prints nothing about it.

Trailing Slash

The one rsync rule people get wrong. A trailing slash on the source means "the contents of", no slash means "the directory itself". The destination's slash makes no difference.

Think of src/ as src/* including hidden files, and src as "put a copy of this directory in there".

Common Recipes

Back up a home directory to an external drive:

rsync -avh --delete --exclude '.cache/' --exclude 'node_modules/' ~/ /Volumes/Backup/home/

Mirror a website from a server, keeping a rotating set of dated snapshots that share unchanged files via hard links:

rsync -avz --delete --link-dest=/backup/www/latest user@host:/var/www/ /backup/www/$(date +%F)/
ln -sfn /backup/www/$(date +%F) /backup/www/latest

Deploy a build, excluding what should not ship, then reload:

rsync -avz --delete --exclude '.git' --exclude '.env' --exclude 'node_modules' \
  ./dist/ deploy@host:/var/www/app/ && ssh deploy@host 'sudo systemctl reload nginx'

Copy only files changed in the last day:

find src -type f -mtime -1 -printf '%P\n' | rsync -av --files-from=- src/ dest/

Sync two directories both ways (run once in each direction; rsync is one-way, --update keeps the newer copy):

rsync -avu a/ b/ && rsync -avu b/ a/

Move a whole server's data directory to a new host over a slow link, resumable:

rsync -avzP --bwlimit=20m -e "ssh -p 2222" /srv/data/ root@newhost:/srv/data/

Clone a disk or root filesystem to another mounted volume, staying off /proc, /sys, and other mounts:

sudo rsync -aAXHvx --numeric-ids --exclude={'/dev/*','/proc/*','/sys/*','/tmp/*','/run/*','/mnt/*','/media/*','/lost+found'} / /mnt/newdisk/

rsync vs scp

OpenSSH's scp has used the SFTP protocol under the hood since 9.0, which fixed its security problems but did not add any of the above.

Exit Codes

rsync reports its result in the exit code (echo $? right after it runs), which is what a cron job or a script should check.

Gotchas

• --delete with the wrong trailing slash or a mistyped destination removes real files. -n first, every time.
• rsync must exist on the remote host. bash: rsync: command not found from the far end and exit code 12 or 127 mean apt install rsync there, not here.
• A .bashrc on the remote that prints something (a banner, a echo, an unguarded neofetch) corrupts the protocol stream and gives protocol version mismatch or code 12. Guard it with [[ $- != *i* ]] && return at the top.
• macOS ships an old rsync 2.6.9, and macOS 15 replaced it with openrsync, which lacks flags such as --info=progress2. brew install rsync gives you 3.x; on Windows, rsync comes with WSL, Cygwin, or MSYS2, not with Git Bash by default.
• -z slows down a LAN copy and does nothing for files that are already compressed (images, video, archives). Use it over the internet, drop it locally.
• Copying to a drive formatted exFAT, FAT32, or NTFS from Linux recopies everything each run because the filesystem cannot store the same times and permissions. Add --no-perms --no-owner --no-group --modify-window=1 or --size-only.
• unexpected remote arg means the remote path is missing its colon (user@host/path instead of user@host:/path) or you gave two remote paths in one command.
• Changing only a file's permissions or owner does not change its size or time, so a plain -av run does not resend it but does update the attributes. Content edits that keep the same size and time (rare, but touch -r and some build tools do it) need -c to be noticed.