Command builder

rsync command generator

Copy, sync, mirror or back up without re-learning the flags. The two traps everyone hits, the trailing slash and --delete, are spelled out as you go, and every command comes with a --dry-run preview, so you see what rsync will copy or delete before it does.

Recipe:
Common options
Mirror (delete extra files)

Makes the destination an exact copy of the source. Step 1 below lists every file it would delete before anything happens.

Excludes

Patterns to skip e.g. node_modules, *.log, .git

Transfer tuning
SSH (port & key)

Only used for Upload/Download. A non-default port or key adds -e 'ssh …'.

Run it safely, in this order

  1. Preview: nothing is copied or deleted

     
  2. Run it for real

     

The preview lists every file rsync would copy and, with --delete, every file it would delete. If the list looks wrong, fix the paths and preview again.

Common rsync commands

The tasks people look up most, each with the command to copy. Swap in your own paths and server; the recipe buttons above fill in several of them for you.

All of these on one printable page: rsync cheat sheet (PDF, A4).

Copy a folder to a server over SSH

The trailing / on ./site/ copies what's inside the folder into /var/www/site/. -z compresses on the way, which helps over slow connections.

rsync -avzh ./site/ deploy@example.com:/var/www/site/

Download a folder from a server

The same command the other way round: the server path comes first. Run it again later and only new or changed files come down.

rsync -avzh deploy@example.com:/var/www/site/ ./site-backup/

Copy the folder itself, not just what's inside

Without a trailing slash, rsync creates photos/ inside the destination. With one (photos/), the files would land directly in /mnt/backup/.

rsync -avh photos /mnt/backup/

Mirror a folder exactly (delete extra files)

--delete removes whatever is in the destination but not in the source. This is the preview: read every deleting line, then run it again without --dry-run.

rsync -avh --dry-run --delete ./site/ /mnt/mirror/site/

Exclude folders and files

A pattern without a leading / matches at any depth, so node_modules skips every folder of that name. Quote wildcards like '*.log': unquoted, zsh refuses to run the command.

rsync -avh --exclude=node_modules --exclude=.git --exclude='*.log' \
  ./project/ /mnt/backup/project/

Use a different SSH port or key

-e sets the SSH command rsync connects with. A Host entry in ~/.ssh/config does the same once, for rsync, ssh and scp alike.

rsync -avh -e 'ssh -p 2222 -i ~/.ssh/deploy_key' ./site/ \
  deploy@example.com:/var/www/site/

Resume a big transfer and show progress

-P keeps partly sent files and shows progress, so an interrupted copy picks up where it stopped when you run the same command again.

rsync -avhP ./videos/ deploy@example.com:/srv/videos/

Limit the bandwidth

Keeps a big upload from filling your connection. The rate is in kilobytes per second unless you add a unit: 2m is about 2 MB/s.

rsync -avh --bwlimit=2m ./exports/ deploy@example.com:/srv/exports/

Copy only files whose content changed

By default rsync compares size and modification time. -c compares checksums instead: slower, but it catches a change that kept both.

rsync -avhc ./site/ /mnt/backup/site/

Back up a system folder with its owners

--numeric-ids keeps the user and group ID numbers instead of matching them by name. That matters when you restore from another system, such as a rescue USB stick. Run it as root, or owners aren't kept at all.

rsync -avh --numeric-ids /home/ /mnt/backup/home/

The two footguns

The trailing slash on the source
This is the one that bites everyone. rsync -a src/ dest/ copies the contents of src into dest. rsync -a src dest/ (no slash) copies the folder itself, giving you dest/src/…. The destination's trailing slash doesn't matter, only the source's. The live hint above tells you which one you're about to run.
--delete: a one-way mirror
Without it, rsync only adds and updates; files you removed from the source stay in the destination. --delete makes the destination an exact mirror by removing anything not in the source. That's also how people erase a backup by giving the paths the wrong way round. Always run the preview (step 1) first.

The flags, briefly

-a (archive)
The sensible default: recurse into directories and preserve permissions, timestamps, symlinks and ownership. It's shorthand for -rlptgoD. Almost every rsync command starts here.
-z (compress)
Compresses data in transit. Worth it over slow networks, pointless for local copies or already-compressed files (video, archives, images).
-P (progress + partial)
Shows progress as it goes and keeps partially transferred files, so an interrupted big transfer can resume where it stopped.
-u / -c
-u skips files that are newer at the destination. -c decides what to send by checksum instead of the faster default (size + modification time): slower, but it catches same-size, same-time changes.

Questions about rsync

What does the trailing slash on the source do?

It decides whether rsync copies the folder or only what's inside it. rsync -a photos/ /mnt/backup/ puts the files straight into /mnt/backup/; rsync -a photos /mnt/backup/ creates /mnt/backup/photos/. Only the source's slash matters. The hint under the paths above says which one you're about to run.

How do I test an rsync command without changing anything?

Add --dry-run (short: -n) together with -v. rsync goes through the whole comparison and lists every file it would copy, and with --delete every file it would delete, but writes nothing. Without -v a dry run prints nothing at all, which looks like "nothing to do", so step 1 above always has it. Add -i (--itemize-changes) to see why each file would change.

Does rsync delete files at the destination?

Not unless you ask it to. By default rsync only adds and updates: files you removed from the source stay in the destination. --delete deletes everything in the destination that isn't in the source, and rsync's own manual calls it dangerous if used incorrectly and says to try a dry run first. Note that rsync does overwrite files that differ, even when the destination's copy is newer; -u skips those.

How do I exclude a folder?

--exclude=node_modules skips every file or folder with that name, at any depth. Start a pattern with / to match only at the top of the source (--exclude=/cache), and end it with / to match folders only (--exclude=tmp/). For a long list, put one pattern per line in a file and pass --exclude-from=excludes.txt.

How do I use rsync with a different SSH port or key?

Hand rsync the SSH command with -e 'ssh -p 2222 -i ~/.ssh/deploy_key', placed before the paths. The SSH section of the builder writes it for you. If you connect to that server often, a Host block with Port and IdentityFile in ~/.ssh/config saves typing it at all.

Why does rsync copy every file again?

rsync skips a file when its size and modification time match. If the times don't, every file looks changed. Two usual causes: an earlier copy was made without -a (or -t), so the destination files got new times; or the destination is a FAT drive, which stores times in 2-second steps. For FAT, add --modify-window=1.

Can I undo rsync --delete?

No. rsync deletes files directly: they don't go to a trash, and rsync keeps no record. The way back is a backup of the destination. With rsync 3 (on Linux, or from Homebrew on a Mac) you can build one in: --backup with --backup-dir=/mnt/deleted, a folder outside the destination, moves every file it deletes or overwrites into that folder instead. The rsync that ships with macOS (openrsync) is different: when we tried it, setting --backup-dir made it skip the deletions altogether.

Does rsync work on Windows and macOS?

On Windows, run it inside WSL; Git Bash doesn't include rsync. Recent macOS versions ship openrsync, which reports itself as compatible with rsync 2.6.9 and covers the options in this tool. For newer rsync 3 features, install rsync from Homebrew. ~ is left unquoted in the commands so your home folder still expands.

Related tools

Sources & references