Stop re-reading
the man page.

1 · Mental model: rsync is a reconciler, not a copier

Every confusing thing about rsync becomes obvious once you accept one fact: rsync does not copy files. It makes a destination match a source, and it works hard to move as few bytes as possible while doing it. Copying is what it does when reconciling happens to require copying.

That distinction is not pedantry. It explains the behavior that trips people up:

• Why it appears to do nothing. Run the same command twice and the second run transfers no files. A copier would copy again. A reconciler sees the destination already matches and stops.
• Why --delete exists and is not the default. A destination with extra files does not match the source. rsync will not remove them unless you say so, because "match" is ambiguous and the destructive reading needs consent.
• Why the trailing slash matters so much. Reconciling means answering "which destination path should hold this source?" The slash is how you answer.
• Why interrupting it is usually safe. Reconciliation is restartable. Run it again and it picks up the remaining difference.

Three processes, not one program

When you type one rsync command, up to three rsync processes cooperate. Knowing their names makes error messages readable, because rsync tags every error with the role that produced it — you have already seen [sender], [receiver], and [generator] in real output.

The two questions rsync asks about every file

Internally, every file passes through two decisions, and almost every flag you will ever use tunes one of them:

The misconception worth killing first

What you will be able to do

By the end of this guide you can, without consulting documentation:

• Perform: mirror a directory locally or over SSH, with or without deletion, and predict the resulting tree before you press Enter.
• Explain: why a file was or was not transferred, from the itemized output alone.
• Build: a hardlinked snapshot backup system with retention, scheduled under launchd or systemd.
• Recognize: which of the two rsyncs on your Mac you are running, and why it matters.
• Debug: permission failures, vanished files, filter rules that do not fire, and interrupted transfers.
• Evaluate: when rsync is the wrong tool, and what to reach for instead.

Sources: rsync(1) manual, 3.4.4 · The rsync algorithm (Tridgell & Mackerras technical report)

2 · Prerequisite floor

rsync assumes you are fluent in the shell's model of paths and files. It does not assume anything else. If the self-assessment below is comfortable, start at §3; if two or more items are shaky, the refreshers are short and they will save you an hour of confusion later.

Hard prerequisites

Soft prerequisites — helpful, learned just in time here

• SSH with key authentication. Needed for §10 onward. If ssh yourhost already works without a password prompt, you are set. If not, §10 includes the setup.
• Hard links. Needed only for §14. Taught there from first principles; no prior exposure assumed.
• cron / launchd / systemd timers. Needed only for §15, which gives complete working unit files for both platforms.

Self-assessment

Answer these before continuing. Each links to where the answer lives if you want to check.

Sources: GNU Bash manual — pathname expansion, quoting, exit status · rsync(1) — USAGE

3 · Install & verify: you probably have two rsyncs

On macOS this is not a formality. The rsync that ships with the system is a different program, written by different people, speaking an older protocol, missing flags this guide relies on. Finding out which one you are running takes ten seconds and prevents a whole category of "that flag doesn't work" confusion.

macOS: the openrsync trap

Ask any Mac what its rsync is:

# On macOS 15.6, verified 2026-08-06
/usr/bin/rsync --version
openrsync: protocol version 29
rsync version 2.6.9 compatible

That is openrsync, an independent reimplementation originating in OpenBSD, shipped by Apple in place of the Samba rsync. It is not rsync 2.6.9; it advertises compatibility with that protocol level. Meanwhile, if you have installed rsync from Homebrew:

/usr/local/bin/rsync --version | head -3
rsync  version 3.4.4  protocol version 32
Copyright (C) 1996-2026 by Andrew Tridgell, Wayne Davison, and others.
Web site: https://rsync.samba.org/

Two programs, same name, protocol 29 versus 32. Which one runs depends entirely on your PATH order. Check with which -a rsync — it lists every match in order, and the first one wins.

What openrsync actually cannot do

Verified by running each flag against openrsync on macOS 15.6:

man "$(brew --prefix rsync)/share/man/man1/rsync.1"

Install the real thing

# macOS — Homebrew
brew install rsync
which -a rsync   # Homebrew's path must come first
rsync --version | head -1
rsync  version 3.4.4  protocol version 32

On Apple Silicon, Homebrew installs under /opt/homebrew; on Intel, under /usr/local. The transcripts in this guide come from an Intel-layout install, so paths read /usr/local/…. Substitute brew --prefix if yours differs.

Ubuntu and WSL

sudo apt update && sudo apt install rsync
rsync --version | head -1

What you get depends on the release, and the spread is wide enough to matter:

WSL: the filesystem boundary is the real issue

Inside WSL, rsync is ordinary Linux rsync and behaves exactly as documented — as long as both sides live in the Linux filesystem. The moment a path crosses into /mnt/c/…, you are on the Windows drive through a translation layer, and three things change:

• Permissions are synthesized. NTFS has no Unix mode bits. Preserving them with -a produces noise at best and permission errors at worst. Use -rlt plus explicit --no-perms --no-owner --no-group, or --chmod to impose a mode you choose.
• Timestamps can be coarse. If the destination filesystem stores mtimes at lower resolution, every run sees a difference and re-copies everything. --modify-window=1 (or -@1) tells rsync to treat timestamps within N seconds as equal (§6). This is the standard fix for FAT/exFAT targets too.
• It is slow. Cross-boundary I/O in WSL goes through a file-server protocol, not a direct filesystem. A tree that syncs in two seconds inside ~ can take a minute under /mnt/c. Keep working sets on the Linux side and sync outward deliberately.

# WSL → Windows drive: don't fight NTFS over ownership
rsync -rlt --no-perms --no-owner --no-group --modify-window=1 \
      --delete ~/project/ /mnt/c/Users/you/project/

Sources: rsync downloads & release history · Ubuntu rsync package versions · openrsync(1)

4 · The trailing slash, settled forever

This is rsync's most famous confusion and it has exactly one rule. The rule is not "remember which way it goes." The rule is that a trailing slash on the source means "the contents of this directory" and its absence means "this directory". Everything else follows.

Proof, from a real run

Same source tree, same destination, one character apart:

# WITHOUT the slash — "copy the directory src"
rsync -av src dst/
sending incremental file list
src/
src/a.txt
src/b.txt
src/docs/
src/docs/note.md

find dst
dst
dst/src           ← src itself landed inside dst
dst/src/a.txt
dst/src/b.txt
dst/src/docs
dst/src/docs/note.md

# WITH the slash — "copy the contents of src"
rsync -av src/ dst/
sending incremental file list
a.txt
b.txt
docs/
docs/note.md

find dst
dst
dst/a.txt         ← contents landed directly in dst
dst/b.txt
dst/docs
dst/docs/note.md

Notice the verbose output already told you before find did. With the slash, paths are printed relative to the source; without it, every path is prefixed with src/. Read the first line of file output and you know which behavior you are getting — that is the habit worth building.

The destination slash does nothing (for directory sources)

Half the internet's advice hedges here. It does not need to. Verified:

rsync -a src/ d1     # no trailing slash on dest
rsync -a src/ d2/    # trailing slash on dest
find d1 d2
d1
d1/f.txt
d2
d2/f.txt          ← identical

rsync -a src/f.txt out     → out is a FILE (a copy of f.txt)
rsync -a src/f.txt out2/   → out2 is a DIRECTORY containing f.txt

Interactive: predict the tree

Toggle the slashes and watch the destination change. Then close your eyes, guess, and check.

src/
├── a.txt
├── b.txt
└── docs/
    └── note.md

Where this bites in real life

Sources: rsync(1) — "a trailing slash on the source"

5 · Anatomy of a command: the eleven flags that matter

rsync 3.4.4 documents over two hundred options. You will use eleven of them regularly and about fifteen more occasionally. The rest exist for mirror operators, distribution builders, and people recovering from filesystems that no longer ship. This section teaches the eleven and, more importantly, how to compose them.

The shape

Either SRC or DEST may carry a host: prefix, never both. That single constraint defines rsync's whole network model, and §10 unpacks it.

-a is not magic, it is an abbreviation

The archive flag is where most people stop reading, which is a shame, because knowing its expansion tells you exactly what it does not do. From the rsync 3.4.4 manual:

# --archive, -a  →  equivalent to -rlptgoD
-r  --recurse       descend into directories
-l  --links         copy symlinks as symlinks
-p  --perms         preserve permissions
-t  --times         preserve modification times
-g  --group         preserve group
-o  --owner         preserve owner   (silently ignored without privilege — §12)
-D  --devices --specials   preserve device and special files

Note also: openrsync documents -a as -Dgloprt. Same seven letters, different order, and it is a different program's promise. One more reason to read the right man page (§3).

The working set

The universal starting pattern

# Say this to yourself, then edit down. It is safe by construction:
rsync -avhn --delete SRC/ DEST/     # look
rsync -avh  --delete SRC/ DEST/     # leap (drop the n)

Type the dry run, read it, then press ↑ and delete one character. That two-step is the single highest-value habit in this guide, and it costs about four seconds.

Interactive: compose a command

Toggle flags and read what the command actually means. The expansion line shows what -a unfolds into, so you can see when a flag you added is already implied.

Sources: rsync(1) — OPTIONS SUMMARY

6 · The quick check and the delta algorithm

Two mechanisms decide everything rsync does. The quick check decides whether a file is transferred. The delta-transfer algorithm decides how much of it crosses the wire. They are independent, they are both defaults, and both have a switch.

Mechanism 1: the quick check

Before transferring anything, the generator compares each source file against its destination counterpart. The default test — the "quick check" — is:

It is a very good heuristic. It is also falsifiable, and here is the falsification, run for real:

# Two files, same length, different content, identical timestamps
printf 'same size!\n' > src/f.txt   # synced to dst
printf 'SAME SIZE!\n' > src/f.txt   # edited: 10 bytes → 10 bytes
touch -t 202608061200 src/f.txt dst/f.txt

rsync -avi src/ dst/
sent 75 bytes  received 12 bytes  174.00 bytes/sec   ← nothing transferred!

rsync -avic src/ dst/          # -c is --checksum
>fc........ f.txt
sent 149 bytes  received 35 bytes  368.00 bytes/sec
cat dst/f.txt
SAME SIZE!

The c in >fc........ is rsync telling you the checksum differed — a code you can only see because --checksum made it look. §7 decodes the rest of that string.

Tuning the quick check

# -u in action: destination file is newer, so it survives
rsync -avi -u up/src/ up/dst/
sent 77 bytes  received 12 bytes
cat up/dst/f.txt
NEWER ON DEST          ← preserved

# without -u, the source wins unconditionally
rsync -avi up/src/ up/dst/
>f.st...... f.txt
cat up/dst/f.txt
old                    ← clobbered

Two neighbours worth knowing: --existing and --ignore-existing

These do not tune the comparison — they restrict which files are eligible at all. They are exact opposites and their names are unhelpfully similar, so learn them as a pair. Source has have.txt (also at the destination) and new.txt (not):

# --existing: update only what is already there. Never create.
rsync -ain --existing src/ dst/
.d..t...... ./
>f.st...... have.txt        ← new.txt is not created

# --ignore-existing: create only what is missing. Never update.
rsync -ain --ignore-existing src/ dst/
>f+++++++++ new.txt          ← have.txt is left alone

--existing is for pushing a config change to machines that already opted in. --ignore-existing is for topping up a destination whose copies you must not disturb — filling gaps in a media library, or seeding without overwriting local edits.

Mechanism 2: the delta-transfer algorithm

Once rsync decides a file needs updating, it does not necessarily send the file. This is the algorithm rsync is named for, and the reason it exists.

Proof, both directions

A 10 MB file, copied, then 50 bytes overwritten in the middle. Over a remote transport:

# first copy — everything is literal
Literal data: 10,485,760 bytes
Matched data: 0 bytes
Total bytes sent: 10,488,443
speedup is 1.00

# after changing 50 bytes — delta kicks in
Literal data: 1,152 bytes
Matched data: 10,484,608 bytes
Total bytes sent: 14,263
Total bytes received: 19,505
speedup is 310.52

The same change on a purely local copy sends everything:

# local src → local dst, default behavior
Literal data: 10,485,760 bytes
Matched data: 0 bytes
speedup is 1.00

# same local copy with --no-whole-file
Literal data: 1,152 bytes
Matched data: 10,484,608 bytes
speedup is 310.54

The simplified model versus the complete one

Earlier this guide said "the delta algorithm sends only changed blocks." The complete model adds three qualifications you now have the context for:

• Block size is chosen from the file size (or forced with -B). Very large files get larger blocks, so tiny scattered edits can still transmit more than you expect.
• The receiver must have an old copy to describe. A brand-new file has no basis, so it is always fully literal — unless you supply one with --fuzzy, --link-dest, or --compare-dest (§14).
• The speedup figure counts file bytes versus wire bytes, including protocol overhead. It is a useful ratio, not a benchmark.

Sources: The rsync algorithm — technical report · rsync(1) — --checksum, --whole-file, --size-only

7 · Reading rsync's output

rsync's default verbose output tells you what it touched. The itemized output tells you why. Learning the eleven-character change string converts rsync from a black box into an instrument, and it takes about ten minutes.

The default: -v

rsync -av src/ dst/
sending incremental file list
a.txt
b.txt
docs/
docs/note.md

sent 304 bytes  received 85 bytes  778.00 bytes/sec
total size is 16  speedup is 0.04

Three things worth naming. "sending incremental file list" means rsync is streaming the file list as it walks, not building it all up front — that is why big trees start transferring immediately. Directories appear with a trailing slash when they are created or their attributes change. speedup below 1.00 is normal for tiny transfers; protocol overhead dominates.

The instrument: -i

Every changed item gets an eleven-character code:

rsync -avi src/ dst/
.d..t...... ./
>f.st...... a.txt
.f...p..... b.txt
>f+++++++++ c.txt
cd+++++++++ docs/
cL+++++++++ link.lnk -> target.txt
*deleting   b.txt

Read it positionally. Positions 1–2 are what and how; positions 3–11 are which attributes changed.

The full position table

--dry-run and its one honest limitation

-n makes every decision and performs none of them. Combined with -i it is the best tool in the box:

rsync -ain --delete src/ dst/
*deleting   b.txt
>f.st...... a.txt

Progress, for humans

rsync -ah --info=progress2 src/ dst/
          2.10M 100%  246.43MB/s    0:00:00 (xfr#3, to-chk=0/4)

xfr#3 is the third file actually transferred; to-chk=0/4 means zero of four remaining file-list entries left to examine. When to-chk stalls at a high number, rsync is still walking the tree, not stuck.

Sources: rsync(1) — --itemize-changes, --info, --dry-run

8 · Filter rules: the part everyone re-reads

Filter rules are rsync's second real language, and they are re-read every time because they have three behaviors that violate intuition: first match wins, directories are pruned before their contents are examined, and a pattern's anchoring changes with a single leading slash. Learn those three and the rest is syntax.

Rule 1: first match wins

rsync evaluates rules in the order given and stops at the first one that matches. Not most-specific-wins. Not last-wins. First. Verified:

# WRONG order — the exclude fires first, include never runs
rsync -ain --exclude='*.log' --include='debug.log' proj/ out/
(no line for debug.log — it was excluded)

# RIGHT order — the include is reached first and wins
rsync -ain --include='debug.log' --exclude='*.log' proj/ out/
>f+++++++++ docs/debug.log

Rule 2: directories are pruned, not searched

If a rule excludes a directory, rsync never descends into it — so a later include for something inside it can never fire. This is why the "include only .md files" idiom needs the seemingly redundant --include='*/':

rsync -ain --include='*/' --include='*.md' --exclude='*' proj/ out/
cd+++++++++ ./
cd+++++++++ .git/
cd+++++++++ build/
cd+++++++++ docs/
>f+++++++++ docs/readme.md
cd+++++++++ node_modules/
cd+++++++++ node_modules/pkg/
cd+++++++++ src/

Read it: --include='*/' keeps every directory so rsync can walk in; --include='*.md' keeps the files you want; --exclude='*' drops everything else. It works — but look at all those empty directories. Add -m (--prune-empty-dirs):

rsync -ainm --include='*/' --include='*.md' --exclude='*' proj/ out/
cd+++++++++ ./
cd+++++++++ docs/
>f+++++++++ docs/readme.md

This four-part incantation — -m, include dirs, include what you want, exclude the rest — is worth memorizing verbatim. It is the answer to "copy only the X files from this tree."

Rule 3: anchoring

The leading slash is relative to the transfer root, not your filesystem root and not your working directory. In rsync -a ~/proj/ backup:/srv/, the rule /build means ~/proj/build.

Where rules can live

--exclude-from, the practical default

cat excludes.txt
node_modules/
build/
*.log
.git/

rsync -ain --exclude-from=excludes.txt proj/ out/
cd+++++++++ ./
cd+++++++++ docs/
>f+++++++++ docs/readme.md
cd+++++++++ src/
>f+++++++++ src/main.c

Per-directory merge files

Drop a .rsync-filter into any directory and its rules govern that subtree:

cat proj/docs/.rsync-filter
- *.log

rsync -ain --filter='dir-merge /.rsync-filter' proj/ out/   # fresh out/
created directory out
cd+++++++++ ./
>f+++++++++ app.log             ← root .log survives: rule is scoped to docs/
cd+++++++++ docs/
>f+++++++++ docs/.rsync-filter  ← the rule file itself gets copied
>f+++++++++ docs/readme.md      ← docs/debug.log was excluded
cd+++++++++ src/
>f+++++++++ src/main.c

Doubling the shorthand — -FF instead of -F — also excludes the filter files themselves from transfer:

rsync -ain -FF proj/ out/   # fresh out/
created directory out
cd+++++++++ ./
>f+++++++++ app.log             ← root .log still survives
cd+++++++++ docs/
>f+++++++++ docs/readme.md      ← no .rsync-filter, no debug.log
cd+++++++++ src/
>f+++++++++ src/main.c

Debugging rules that will not fire

Three moves, in order:

1. -ain and read the file list. If a file appears, no rule excluded it. If it is missing, some rule did.
2. Ask rsync to explain itself: --debug=FILTER2 prints each rule as parsed and names every path it hides and why. This is the fastest path from "why is this still copying" to an answer. (Level 1 is nearly silent; use FILTER2.)
3. Check for shell expansion. Run echo in front of your command. If --exclude=*.log came back as --exclude=app.log, your quoting is the bug, not your rule.

Sources: rsync(1) — FILTER RULES, INCLUDE/EXCLUDE PATTERN RULES, MERGE-FILE FILTER RULES

9 · Deleting safely

The wrong question is "is --delete dangerous?" The right question is "what exactly does rsync consider extraneous?" Answer that and --delete becomes ordinary. Guess at it and you will eventually remove something you wanted. One fear you can drop now: --delete only ever touches the receiving side. Your source is never at risk — unless you explicitly ask with --remove-source-files, covered below.

What --delete means

It means: on the receiving side, remove files that are not in the sending side's file list. The emphasis matters. "Not in the file list" is not the same as "not in the source directory", because filter rules and --exclude shape the file list before deletion ever looks at it.

rm src/b.txt
rsync -avi --delete --dry-run src/ dst/
sending incremental file list
*deleting   b.txt

sent 211 bytes  received 30 bytes  482.00 bytes/sec
total size is 33  speedup is 0.14 (DRY RUN)

The five deletion timings

The guard rail: --max-delete

A source that failed to mount looks exactly like a source where you deleted everything. --max-delete=N is the cheap insurance:

rsync -avi --delete --max-delete=2 src/ dst/
*deleting   f3.txt
*deleting   f2.txt
Deletions stopped due to --max-delete limit (1 skipped)

sent 95 bytes  received 39 bytes  268.00 bytes/sec
rsync error: the --max-delete limit stopped deletions (code 25) at main.c(1356) [sender=3.4.4]
echo $?
25

Note the behavior precisely: it deletes up to the limit, then stops and exits 25. It does not roll back the deletions it already made. Treat exit 25 in a scheduled job as "investigate now" — that is exactly the signal you wanted.

Safety nets that keep the old bytes

--backup turns overwrite-and-delete into move-aside. With --backup-dir, the displaced files land in a parallel tree rather than littering the destination with ~ suffixes:

rsync -avi --backup --backup-dir=../attic --suffix='' src/ dst/
sending incremental file list
>f..t...... f.txt

cat attic/f.txt
original          ← the pre-overwrite content, preserved

--backup-dir is relative to the destination, so ../attic means a sibling of dst. Combine with a dated directory for a poor man's version history:

rsync -a --delete --backup --backup-dir="../attic/$(date +%F)" src/ dst/

rsync -av --remove-source-files src/ dst/
find src
src
src/d            ← directories remain, files are gone

Deletion and filters interact — badly, if you are careless

An excluded file is not in the file list, so from --delete's point of view it is extraneous at the destination and gets removed. That is usually wrong: you excluded node_modules from the transfer, not from existence. Three flags resolve the ambiguity:

Verified, with a destination that holds app.log (matching the exclude) and junk.txt (not matching):

rsync -avi --delete --exclude='*.log' src/ dst/
*deleting   junk.txt
>f+++++++++ keep.txt
ls dst/
app.log  keep.txt        ← the excluded file survived

rsync -avi --delete --delete-excluded --exclude='*.log' src/ dst/
*deleting   app.log
ls dst/
keep.txt                 ← now it is gone

The practical rule: if you want the destination to keep something rsync never sends — a .env, an uploads directory, a build cache — say so explicitly with a protect rule rather than relying on exclusion semantics you would have to re-derive next year.

# Deploy: replace the code, never touch runtime state
rsync -av --delete-after \
      --filter='P /uploads/' --filter='P /.env' \
      --exclude='.git/' ./build/ web:/srv/app/

Sources: rsync(1) — --delete*, --max-delete, --backup-dir, --remove-source-files

10 · Remote over SSH: what actually happens

rsync has no network code for the SSH case. It runs ssh host rsync --server … and talks to that process over the pipe. Once you have seen the command it constructs, remote rsync stops being a separate topic and becomes local rsync with a longer pipe.

The syntax

# push: local → remote
rsync -avh ~/site/ web.example.com:/srv/site/

# pull: remote → local
rsync -avh web.example.com:/srv/site/ ~/site/

# with a user, and a path relative to that user's home
rsync -avh ~/notes/ deploy@web.example.com:notes/

Exactly one side may carry a host: prefix. rsync cannot copy remote-to-remote directly; it would need to be on one of the machines. (You can fake it by running rsync on one of the hosts over SSH, but that is you orchestrating, not rsync.)

What rsync sends to the far side

Substitute a logging script for ssh with -e and rsync will show you its hand. These transcripts come from exactly that — a stand-in remote shell that prints its arguments and then runs the command locally. The argv is genuine; the transport is a pipe rather than a network:

# push
rsync -av -e ./logrsh src/ fakehost:/tmp/dst/
REMOTE-SHELL ARGV: fakehost rsync --server -vlogDtpre.iLsfxCIvu . /tmp/dst/

# pull — note --sender appears
rsync -av -e ./logrsh fakehost:/tmp/src/ dst/
REMOTE-SHELL ARGV: fakehost rsync --server --sender -vlogDtpre.iLsfxCIvu . /tmp/src/

# add -z --partial and watch the flags follow
REMOTE-SHELL ARGV: fakehost rsync --server -vlogDtprze.iLsfxCIvu --partial . /tmp/dst2/

Three things become obvious at once:

• rsync must exist on the remote, in the remote login shell's PATH. That is the entire dependency. No daemon, no port, no configuration.
• Your flags are forwarded. -z became z in -vlogDtprze…; --partial was passed through verbatim. A flag the remote does not understand fails there, giving exit code 4.
• The trailing e.iLsfxCIvu is a capability string — the client telling the server which protocol features it supports. Apple's openrsync sends separate flags instead (--server -g -l -o -p -D -r -t -v --dirs), which is one visible sign you are talking to a different implementation.

Setting up key authentication

rsync over SSH with a password prompt is unusable in scripts and irritating interactively. Fix it once:

# create a key if you don't have one
ssh-keygen -t ed25519 -C "rsync $(hostname)"

# install it on the remote (Ubuntu/WSL ships ssh-copy-id; macOS does not)
ssh-copy-id user@host
# macOS equivalent:
ssh user@host 'mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys' < ~/.ssh/id_ed25519.pub

# verify: this must print OK with no prompt
ssh -o BatchMode=yes user@host 'echo OK; command -v rsync'

That second command is the real test. If it prints OK and a path to rsync, every rsync command in this section will work. If it prints Permission denied (publickey), fix SSH before blaming rsync.

Configuring the transport with -e

Host web
    HostName web.example.com
    User deploy
    Port 2222
    IdentityFile ~/.ssh/deploy_ed25519
    ControlMaster auto
    ControlPath ~/.ssh/cm-%r@%h:%p
    ControlPersist 60

Remote paths go through a shell — plan accordingly

Because the remote side runs your command through a login shell, wildcards on the remote are expanded there:

rsync -av 'host:/srv/logs/*.txt' ./
receiving incremental file list
a.txt
c.txt

Quote it locally (so your shell leaves it alone) and the remote shell expands it. That is a feature until it is not: an unmatched glob produces a confusing error, and spaces need care. Since 3.2.4, rsync escapes spaces and other specials for you by default (--old-args reverts to the raw behavior) — on an older client like Ubuntu 20.04's 3.1.3, you must double-quote remote paths yourself:

# rsync 3.4.4 escapes the space itself
REMOTE-SHELL ARGV: fakehost rsync --server -vlogDtpre.iLsfxCIvu . /tmp/dst/a\ b/

# with -s (--secluded-args) the paths leave the command line entirely
rsync -avs -e ./logrsh "my docs/" "fakehost:/tmp/dst/c d/"
REMOTE-SHELL ARGV: fakehost rsync --server -svlogDtpre.iLsfxCIvu   ← no paths at all

-s sends filenames over the protocol instead of the command line, so the remote shell cannot mangle them. Use it when paths contain shell metacharacters — and remember that it also disables remote wildcard expansion, because there is no longer a command line for the shell to expand.

case $- in *i*) ;; *) return;; esac   # put this near the top of ~/.bashrc

Errors you will actually see

# remote rsync missing or wrong path
bash: /nonexistent/rsync: No such file or directory
rsync: connection unexpectedly closed (0 bytes received so far) [sender]
rsync error: remote command could not be run (code 126) at io.c(232) [sender=3.4.4]

Two neighbouring exit codes cover this failure: 127, remote command not found, and 126, remote command found but could not be run. Which one you get depends on how the remote shell reports the failure — do not memorize the split; treat either as "the far side has no runnable rsync where I pointed". Check ssh host 'command -v rsync' and reach for --rsync-path= if the binary lives somewhere unusual — Homebrew on the far side is a common cause.

Bandwidth and metered links

# cap at ~2 MB/s so you can keep using the connection
rsync -avh --bwlimit=2000 --info=progress2 big/ host:/srv/big/

--bwlimit is in KiB/s by default; suffixes work (--bwlimit=2m). Pair with --partial so an interrupted transfer does not start over — §13 shows exactly what that buys.

Sources: rsync(1) — USAGE, CONNECTING TO AN RSYNC SERVER, --rsh, --rsync-path, --secluded-args · ssh_config(5) — ControlMaster, ProxyJump

11 · The rsync daemon

The daemon is rsync's other transport: a long-running server on TCP 873 that publishes named modules instead of filesystem paths. You reach it with a double colon or an rsync:// URL. It exists for cases SSH handles badly — anonymous public mirrors, high-volume transfers where SSH encryption is the bottleneck, appliances with no shell — and it is worth knowing precisely because those cases are narrow.

Two syntaxes, one protocol

# both of these mean "module pub on that host"
rsync rsync://localhost:8873/pub/
rsync --port=8873 localhost::pub/

The double colon is the tell. host:path is SSH; host::module is the daemon. Confusing the two produces a bewildering error, so read your own commands for that second colon.

A working configuration

This is a real, verified rsyncd.conf — running on a high port so it needs no privileges:

port = 8873
pid file  = /path/to/lab/rsyncd.pid
log file  = /path/to/lab/rsyncd.log
lock file = /path/to/lab/rsyncd.lock
use chroot = no
max connections = 4

[pub]
    path = /path/to/lab/share
    comment = read-only public mirror
    read only = yes
    list = yes

[drop]
    path = /path/to/lab/upload
    comment = authenticated write target
    read only = no
    auth users = labuser
    secrets file = /path/to/lab/rsyncd.secrets

The secrets file is user:password, one pair per line. rsyncd.conf(5) requires that it "normally not be readable by other" — chmod 600 satisfies that, and a rejected file means no logins are possible for the module. There is no default path; you must name one. Start the daemon:

rsync --daemon --config=./rsyncd.conf --no-detach

Using it

# what modules exist?
rsync rsync://localhost:8873/
pub            	read-only public mirror
drop           	authenticated write target

# what is in one?
rsync rsync://localhost:8873/pub/
drwxr-xr-x            128 2026/08/06 12:44:54 .
-rw-r--r--              5 2026/08/06 12:44:54 data.csv
-rw-r--r--             12 2026/08/06 12:44:54 readme.txt

# pull it
rsync -avi rsync://localhost:8873/pub/ ./pull/
receiving incremental file list
.d..t...... ./
>f+++++++++ data.csv
>f+++++++++ readme.txt

A bare module list is something SSH transport cannot do — there is no "what may I access?" query over SSH. That discoverability is the daemon's genuine advantage.

Authentication and refusals

# writing to a read-only module
rsync -a share/ rsync://localhost:8873/pub/
ERROR: module is read only
rsync error: syntax or usage error (code 1) at main.c(1168) [Receiver=3.4.4]

# writing to an auth module with no credentials
rsync -a share/ rsync://localhost:8873/drop/
Password: @ERROR: auth failed on module drop
rsync error: error starting client-server protocol (code 5) at main.c(1874) [sender=3.4.4]

# with credentials
RSYNC_PASSWORD=labpass123 rsync -avi share/ rsync://labuser@localhost:8873/drop/
sending incremental file list
<f+++++++++ data.csv
<f+++++++++ readme.txt

Note the itemize direction flipped to < — bytes going out to the remote rather than arriving. Same decoder (§7), position 1.

The middle path: daemon over SSH

You can get module semantics with SSH's security by having rsync launch a single-use daemon over an SSH connection, so nothing listens on a port:

rsync -av --rsh=ssh host::module/ ./local/

Three details the manual is emphatic about, and each of them will bite you:

• --rsh must be on the command line. Setting RSYNC_RSH in the environment does not enable this mode.
• The config comes from the remote user's home directory, not /etc/rsyncd.conf. The daemon is spawned fresh by that user.
• user@host::module does not mean what you think. Here user@ is the rsync module username, not the SSH username. To set the SSH user you pass it to ssh: --rsh='ssh -l deploy'.

Because the daemon is started by an ordinary user, chroot and uid-changing are unavailable — you trade those for encryption and SSH authentication. This is still how you give someone access to exactly one directory without giving them a usable shell.

Sources: rsyncd.conf(5) · rsync NEWS — 3.4.0 and 3.4.3 security releases

12 · Metadata, symlinks, and crossing platforms

-a preserves seven things and omits five — and one of the omissions means that if you back up a Mac home directory without -X, you are silently losing Finder tags, download provenance, and every other scrap of metadata that lives in extended attributes. No error will tell you. This section is the complete model that §5 deliberately simplified: what each omission costs, on which filesystem, and which flag buys it back.

What -a leaves behind

Extended attributes on macOS: verified

This is not theoretical. A file with Finder metadata, synced with plain -a:

xattr -l src/f.txt
com.apple.metadata:kTestKey: hello
com.apple.provenance:
user.custom: v1

rsync -a src/ dst/ && xattr -l dst/f.txt
com.apple.provenance:          ← everything else silently dropped

rsync -aX src/ dst2/ && xattr -l dst2/f.txt
com.apple.metadata:kTestKey: hello
com.apple.provenance:
user.custom: v1                 ← preserved

ACLs on macOS: a real trap with a real workaround

A file carrying an ACL that denies deletion breaks rsync's normal write path, because rsync writes to a temporary file and then renames it over the target — and the ACL forbids exactly that. Reproduced on macOS 15.6 (the chmod +a syntax is macOS-only; on Linux the equivalent experiment uses setfacl, though POSIX ACLs cannot express a deny-delete rule, so this specific trap is a Mac one):

chmod +a "everyone deny delete" src/f.txt
rsync -aA src/ dst/
rsync: [receiver] rename "…/dst/.f.txt.x9NXJX" -> "f.txt": Permission denied (13)
rsync error: some files/attrs were not transferred (see previous errors) (code 23) at main.c(1356) [sender=3.4.4]

Plain -a on the same file succeeds — because without -A the ACL is never applied to the temp file, so the rename is permitted. And the fix that keeps the ACL:

rsync -aA --inplace src/ dst/ && ls -le dst/f.txt
-rw-r--r--@ 1 you  staff  12 Aug  6 12:46 f.txt
 0: group:everyone deny delete

--inplace writes directly to the destination file instead of writing-then-renaming, sidestepping the ACL entirely. Understand the trade before you adopt it: §13 explains what --inplace costs you in crash safety.

Symlinks: five behaviors, pick deliberately

# -a: symlinks stay symlinks, including ones that escape the tree
cL+++++++++ inside.lnk -> real.txt
cL+++++++++ outside.lnk -> /etc/hosts
cL+++++++++ sub/escape.lnk -> ../../../etc/passwd

# --safe-links: the escaping links are dropped without comment
cL+++++++++ inside.lnk -> real.txt       ← only the safe one survives

# -L: links are replaced by their contents; a broken link is an error
symlink has no referent: "…/sub/escape.lnk"
>f+++++++++ inside.lnk
>f+++++++++ outside.lnk
rsync error: some files/attrs were not transferred (code 23)

Hard links: -H costs something and buys something

# src contains real.txt and hard.txt sharing one inode
rsync -a  src/ out4/   # without -H
rsync -aH src/ out5/   # with -H
without -H: 1 links / with -H: 2 links
du -sh out4 out5
8.0K	out4
4.0K	out5

Without -H, hard-linked files become independent copies — the tree still works, it just doubles in size. rsync must hold the full inode map in memory to detect links, so -H on a multi-million-file tree is a memory conversation. For snapshot backups (§14) it becomes essential, because those trees are made of hard links.

Sparse files

# a 64 MB file that occupies zero blocks
src apparent=67108864 blocks=0
rsync -a  src/ dst/    → no -S:   blocks=131072   ← fully materialized
rsync -aS src/ dst2/   → with -S: blocks=0        ← holes preserved

Without -S, a sparse 64 MB file becomes a real 64 MB file. With VM images this turns a 20 GB backup into 500 GB. Combining -S with --inplace is accepted (since 3.1.3) but may silently produce non-sparse files, depending on kernel and filesystem — verify with ls -ls if the combination matters to you.

Permissions: the surprise about the destination directory itself

before: src=755 dst=700
rsync -a src/ dst/
after:  src=755 dst=755   ← dst's own mode was rewritten

--chmod is the tool for imposing permissions rather than copying them. D prefixes apply to directories, F to files:

rsync -a --chmod=D755,F644 src/ dst/   # source file was 777
stat -f '%N %Lp' dst/f.txt
dst/f.txt 644

Ownership: the promise -a cannot keep

rsync -a --chown=root:wheel src/ dst/ ; echo "exit=$?"
exit=0
ls -l dst/f.txt
-rw-r--r--  1 you       staff  3 Aug  7 10:30 f.txt   ← not root:wheel; no warning either

Four flags govern what happens to ownership when the two sides disagree about users:

Cross-platform reality

Two path tools worth knowing

-R / --relative preserves the full source path inside the destination, and a /./ pivot chooses where the preserved portion starts:

rsync -aR a/b/c/f.txt dst/
dst/a/b/c/f.txt                ← whole path recreated

rsync -aR a/./b/c/f.txt dst2/
dst2/b/c/f.txt                 ← path preserved from the ./ onward

--files-from=FILE takes an explicit list, one path per line, relative to the source root. It implies -R and -d, and -a stops implying -r — add -r back explicitly if a listed directory's contents should come along. Paths land exactly where the list says:

cat list.txt
x/one.txt
y/two.txt
rsync -a --files-from=list.txt src/ dst/ && find dst -type f
dst/x/one.txt
dst/y/two.txt

This is how you drive rsync from the output of find, git ls-files, or a manifest. Add --from0 when the list is NUL-separated, which is the safe way to handle filenames with newlines.

Creating the destination path: --mkpath

rsync creates the final destination directory but not its missing parents. Verified:

rsync -a src/ deep/nested/dst/
rsync: [Receiver] mkdir "…/deep/nested/dst" failed: No such file or directory (2)
rsync error: error in file IO (code 11) at main.c(800) [Receiver=3.4.4]

rsync -a --mkpath src/ deep/nested/dst/
find deep -maxdepth 3 -type d
deep
deep/nested
deep/nested/dst

Before --mkpath existed (added in 3.2.3) the idiom was mkdir -p first, which still works and is more portable if either side might be older. Note that --mkpath and --dry-run together had a bug for file-to-file copies that 3.4.4 fixed — one more reason the version you run matters.

Sources: rsync(1) — --archive, --xattrs, --acls, --hard-links, --sparse, --safe-links, --relative, --files-from, --iconv

13 · Speed, interruption, and resuming

rsync is fast by default and there are exactly four levers worth pulling. Pulling them without measuring usually makes things slower, so each one below comes with the condition under which it helps.

Lever 1: compression — narrower than you think

# 5 MB of highly compressible data, over a remote transport
rsync -a --stats -z --zc=zstd src/ host:dst/
Total bytes sent: 366
speedup is 12,468.83

rsync -a --stats src/ host:dst2/
Total bytes sent: 5,001,339
speedup is 1.00

That is a spectacular ratio on synthetic data and a misleading one. Real guidance:

• Use -z when the link is slower than the CPU. Home upload links, cellular, VPNs. On a LAN or a local disk, compression is a net loss.
• Choose the algorithm. rsync 3.2+ supports zstd, lz4, zlibx, zlib. --zc=zstd is the best general choice; --zc=lz4 when CPU is the constraint. Check availability with rsync --version | grep -A1 'Compress list'. If the far side is older, the negotiation falls back.
• Skip already-compressed files. --skip-compress=gz/jpg/mp4/zst/xz/png/webm avoids burning CPU on data that will not shrink. A sensible default list is compiled in; override when your data is unusual.

Lever 2: --partial — the difference is stark

Interrupt a large transfer with Ctrl+C and look at the destination. Without --partial:

rsync error: received SIGINT, SIGTERM, or SIGHUP (code 20) at rsync.c(716) [sender=3.4.4]
ls -la dst/
total 0                       ← the partial file was discarded

With --partial:

ls -la dst/
-rw-r--r--  1 you  staff  6094848 Dec 31  1969 huge.bin

Six megabytes survived, and note the timestamp: 1969. rsync deliberately leaves the partial file with an ancient mtime so the quick check cannot mistake it for complete. On the next run it becomes the delta basis and only the remainder transfers.

rsync -avh --partial-dir=.rsync-partial --info=progress2 big/ host:/srv/big/

Lever 3: --inplace — a real trade, not a free win

Use it for a VM image on a full disk. Do not use it for a document tree, a website, or anything feeding a snapshot backup.

Lever 4: fewer round trips

• SSH connection reuse. ControlMaster in ~/.ssh/config (§10) removes a full handshake per invocation. For a script that runs rsync in a loop, this is often the largest single win.
• One rsync, not many. Ten thousand small files in one invocation beats a shell loop calling rsync per file by orders of magnitude — the file list is streamed and the connection is shared.
• --bwlimit is a throttle, not a tuner. It exists to leave bandwidth for other work, not to go faster (units in §10).
• --stop-after=MINS / --stop-at=y-m-dTh:m. Bound a transfer to a maintenance window; combine with --partial-dir so the next window resumes. Confirm support with rsync --version | grep stop-at.

Reading --info=progress2 output — including why to-chk grows early in a big transfer — is covered in §7; nothing about it changes at scale.

Sources: rsync(1) — --compress, --compress-choice, --partial-dir, --inplace, --bwlimit, --stop-after

14 · Snapshot backups with --link-dest

This is rsync's best trick and the reason many people never buy backup software. With one extra flag you get a directory per backup — each one a complete, browsable, restorable copy of the whole tree — while unchanged files cost zero additional bytes. Time Machine's core idea, in a command you can read.

The mechanism: hard links

A hard link is a second name for the same inode. Two names, one set of blocks on disk, one reference count. Delete one name and the data survives while the other name exists. rsync's --link-dest=DIR says: when a file is unchanged from the copy in DIR, do not transfer it — hard-link to it instead.

Proof from a real run

# snapshot 1: full copy of a tree containing a 1 MB blob
rsync -a --delete src/ backups/2026-08-06_1200/

# edit one small file, then snapshot 2 linked against snapshot 1
rsync -a --delete --link-dest=../2026-08-06_1200 src/ backups/2026-08-06_1300/

du -sh backups/*
1.0M	backups/2026-08-06_1200
4.0K	backups/2026-08-06_1300
du -sh backups
1.0M	backups                ← two full snapshots, one snapshot of space

stat -f '%N links=%l inode=%i' backups/*/stable.txt backups/*/report.txt
backups/2026-08-06_1200/stable.txt links=2 inode=445333596
backups/2026-08-06_1300/stable.txt links=2 inode=445333596   ← same inode
backups/2026-08-06_1200/report.txt links=1 inode=445333595
backups/2026-08-06_1300/report.txt links=1 inode=445333602   ← different: it changed

--link-dest has two siblings and a cousin

A complete, working snapshot script

This was run end to end against rsync 3.4.4 on macOS while writing this guide — including the mount guard, the link basis, and retention pruning. It uses no GNU-only tools, so it runs unchanged on Ubuntu/WSL.

#!/usr/bin/env bash
# snapshot-backup.sh — dated hardlinked snapshots with retention.
set -euo pipefail

SRC="${1:?usage: $0 SRC DEST_ROOT}"
DEST_ROOT="${2:?usage: $0 SRC DEST_ROOT}"
KEEP="${KEEP:-30}"
EXCLUDES="${EXCLUDES:-$HOME/.config/rsync/backup-excludes}"
STAMP="$(date +%Y-%m-%dT%H%M%S)"
TARGET="$DEST_ROOT/$STAMP"

# Refuse to run against an unmounted volume — see §9.
[ -e "$DEST_ROOT/.backup-marker" ] || { echo "destination not mounted: $DEST_ROOT" >&2; exit 1; }

# Newest existing snapshot becomes the link basis, if there is one.
# Relative to "$TARGET.incomplete/", so "../NAME" resolves inside DEST_ROOT.
link=()
latest="$(ls -1 "$DEST_ROOT" 2>/dev/null | grep -E '^[0-9]{4}-' | sort | tail -1 || true)"
[ -n "$latest" ] && link=(--link-dest="../$latest")

opts=(-aHAX --delete --delete-excluded --max-delete=500 --partial-dir=.rsync-partial)
[ -r "$EXCLUDES" ] && opts+=(--exclude-from="$EXCLUDES")

rsync "${opts[@]}" "${link[@]}" "$SRC/" "$TARGET.incomplete/"

# A dated directory exists only once the snapshot is complete.
mv "$TARGET.incomplete" "$TARGET"

# Retention: keep the newest $KEEP dated directories, delete the rest.
ls -1 "$DEST_ROOT" | grep -E '^[0-9]{4}-' | sort -r | tail -n +"$((KEEP + 1))" |
while IFS= read -r old; do
    echo "pruning $old"
    rm -rf "${DEST_ROOT:?}/${old:?}"
done

Verified behavior, run five times with KEEP=2:

pruning 2026-08-06T130655
pruning 2026-08-06T130656
pruning 2026-08-06T130703
ls dest
2026-08-06T130704
2026-08-06T130706

A starting backup-excludes file

The script reads ~/.config/rsync/backup-excludes. Here is a defensible starting set for a home directory on either platform — every entry is regenerated data that inflates snapshots without making them more restorable. Lines starting with # are comments; unanchored patterns match at any depth (§8):

# caches — rebuilt on demand, most of a home directory's churn
.cache/
Library/Caches/
node_modules/
.npm/
__pycache__/
.venv/

# trash and per-volume bookkeeping — recreated automatically
.Trash/
.DS_Store
.Spotlight-V100/
.fseventsd/
.TemporaryItems/

Two judgment calls to make deliberately rather than by omission: VM and container disk images (huge, change entirely every run — consider excluding them here and backing them up on their own schedule), and ~/Library beyond Caches on macOS (keep it — application state lives there, and losing it is what makes a restore feel incomplete).

Restoring

# one file, from a specific day
cp backups/2026-08-04T030000/notes.md ~/notes.md

# the whole tree, back to how it was — note --delete makes this exact
rsync -aHAXN --delete backups/2026-08-04T030000/ ~/restored/

# what changed between two snapshots?
rsync -ain --delete backups/2026-08-05T030000/ backups/2026-08-06T030000/

That last command is the quiet superpower: a dry run between two snapshots prints an itemized diff of your entire backup history, with no special tooling.

Limits you should know before trusting it

• Hard links need one filesystem. Snapshots must live on the same volume as each other. You cannot link across a mount point.
• Editing a file in a snapshot corrupts every snapshot. They are the same inode. Treat snapshot trees as read-only; do not use --inplace anywhere near them.
• Deleting a snapshot is safe and only frees blocks whose last reference went away. rm -rf on an old snapshot is the correct retention mechanism.
• Link counts have limits and rm -rf of a large snapshot is metadata-heavy. Hundreds of snapshots of millions of files will feel it.
• This is not off-site. A hardlinked snapshot tree on the same disk survives your mistakes, not the disk's death or a ransomware event that can write to the volume. Pair it with a copy somewhere you cannot casually delete from.
• openrsync supports --link-dest — verified to produce real shared inodes — so this technique still works if you are stuck with Apple's build. You lose -X, so Finder metadata will not be in the backup.

Sources: rsync(1) — --link-dest, --compare-dest, --copy-dest

15 · Scheduling: making it run without you

An interactive rsync command and a scheduled one are different programs with the same name. The scheduled one has no terminal, a minimal environment, no SSH agent, and nobody watching its output. Every difference below is a way that unattended rsync fails while the same command works when you type it.

Exit codes — the complete list

From rsync 3.4.4's manual. Your script needs this table because "non-zero means broken" is too coarse:

# The wrapper every scheduled rsync deserves
set +e
rsync "${opts[@]}" "$SRC/" "$DEST/"
rc=$?
set -e
case $rc in
  0)     echo "backup ok" ;;
  24)    echo "backup ok (some source files vanished mid-run)" ;;
  23)    echo "backup completed with unreadable files — check the log" ;;
  25)    echo "REFUSED: --max-delete tripped. Source may be missing." >&2; exit 25 ;;
  *)     echo "backup FAILED with code $rc" >&2; exit $rc ;;
esac

The four things that break unattended runs

Restricting the key on the remote side

A key that can run any command is a key that can be stolen and used for anything. Restrict it to rsync in ~/.ssh/authorized_keys on the destination host:

command="rsync --server -logDtpre.iLsfxCIvu . /srv/backups/laptop/",restrict ssh-ed25519 AAAA… backup@laptop

The command= forces that exact invocation regardless of what the client asks for, and restrict disables port forwarding, agent forwarding, and PTY allocation. Get the exact --server string by running your real command once with -e 'ssh -v' and reading what rsync sends — the technique from §10. Be aware this pins your flag set: change the rsync options and you must update the forced command.

macOS: launchd

Save as ~/Library/LaunchAgents/com.you.rsync-backup.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>              <string>com.you.rsync-backup</string>
  <key>ProgramArguments</key>
  <array>
    <string>/Users/you/bin/snapshot-backup.sh</string>
    <string>/Users/you/Documents</string>
    <string>/Volumes/Backup/documents</string>
  </array>
  <key>StartCalendarInterval</key>
  <dict>
    <key>Hour</key>   <integer>3</integer>
    <key>Minute</key> <integer>15</integer>
  </dict>
  <key>RunAtLoad</key>          <false/>
  <key>StandardOutPath</key>    <string>/Users/you/Library/Logs/rsync-backup.log</string>
  <key>StandardErrorPath</key>  <string>/Users/you/Library/Logs/rsync-backup.log</string>
  <key>EnvironmentVariables</key>
  <dict>
    <key>PATH</key> <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
  </dict>
</dict>
</plist>

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.you.rsync-backup.plist
launchctl kickstart -p gui/$(id -u)/com.you.rsync-backup   # run it now, once
launchctl print gui/$(id -u)/com.you.rsync-backup | grep -E 'state|last exit'
launchctl bootout gui/$(id -u)/com.you.rsync-backup       # unload

Ubuntu / WSL: systemd timer

~/.config/systemd/user/rsync-backup.service:

[Unit]
Description=Hardlinked rsync snapshot backup
After=network-online.target

[Service]
Type=oneshot
ExecStart=/home/you/bin/snapshot-backup.sh /home/you/work /srv/backups/work
Nice=10
IOSchedulingClass=idle
# rsync exit 24 (vanished files) is not a failure
SuccessExitStatus=24

~/.config/systemd/user/rsync-backup.timer:

[Unit]
Description=Run rsync snapshot backup daily

[Timer]
OnCalendar=*-*-* 03:15:00
Persistent=true
RandomizedDelaySec=600

[Install]
WantedBy=timers.target

systemctl --user daemon-reload
systemctl --user enable --now rsync-backup.timer
systemctl --user list-timers rsync-backup.timer
journalctl --user -u rsync-backup.service -n 50

Persistent=true makes the job run after boot if the scheduled time was missed — essential for a laptop. RandomizedDelaySec spreads load if several machines back up to the same target. Add sudo loginctl enable-linger $USER so user timers run when you are not logged in.

Plain cron, if you prefer it

crontab -e
# m h  dom mon dow  command
PATH=/usr/local/bin:/usr/bin:/bin
15 3 * * *  /usr/bin/flock -n /tmp/rsync-backup.lock /home/you/bin/snapshot-backup.sh /home/you/work /srv/backups/work >> /home/you/logs/backup.log 2>&1

flock -n makes an overlapping run exit immediately rather than piling up. macOS has no flock command; use the portable lock instead:

# Portable mutual exclusion: mkdir is atomic everywhere
LOCK=/tmp/rsync-backup.lock
mkdir "$LOCK" 2>/dev/null || { echo "already running"; exit 0; }
trap 'rmdir "$LOCK"' EXIT

The lock's companion is --timeout=300 on the rsync command itself. Over a flaky link an unattended rsync can hang indefinitely on a dead connection — it will never produce the exit 30 in the table above unless you set a timeout, and a hung job holds the lock, so every later run exits "already running" until someone notices. Five minutes of I/O silence is a reasonable default for a nightly job; add --contimeout=60 for daemon connections, which covers the connection attempt itself.

Logging that is worth reading later

rsync -aHAX --delete --stats \
      --log-file=/var/log/rsync-backup.log \
      --log-file-format='%o %f %l %b' src/ dst/

%o is the operation (send/recv/del), %f the filename, %l the file length, %b the bytes actually transferred. Comparing %l against %b across a log is how you confirm delta transfer is doing its job in production.

Sources: rsync(1) — EXIT VALUES, --log-file-format · systemd.timer(5) · Apple — Creating launchd jobs

16 · Decision matrices

The wrong question is "which tool is best?" Every tool below is best at something. The right question is what property you actually need: exactness, continuity, versioning, or reach.

rsync versus everything else

Three smaller decisions — comparison mode, deletion timing, compression — were each settled where they were taught: §6, §9, and §13. The cheat sheet (§19) compresses all three to one line each.

Sources: Syncthing documentation · rclone documentation · restic documentation

17 · Capstone: a real backup and deploy system

Everything in one exercise. Four phases, each depending on the last, all disposable. Budget 35–45 minutes. If a phase's checkpoint fails, the section it exercises is named — go back to it rather than pushing forward.

Self-assessment rubric

Sources: every step above was taught earlier in this guide; the single upstream reference behind all of it is rsync(1), 3.4.4

18 · Troubleshooting: symptom → cause → fix

Every error message below was produced by a real run while writing this guide, or is quoted from rsync 3.4.4's manual. Find your symptom, not your theory.

Transfers that go to the wrong place

Nothing transfers, or too much does

Permissions and metadata

Remote and network

Interruption and scheduling

Two failures that look like rsync but are not

Sources: rsync(1) — DIAGNOSTICS, EXIT VALUES · rsyncd.conf(5)

19 · Cheat sheet

Recall scaffolding, not a replacement for the sections. Every line links to where it was taught — if a flag here surprises you, that link is the fix, not this page.

The universal starting pattern

# Look, then leap. Press ↑ and delete the n.
rsync -avhn --delete SRC/ DEST/
rsync -avh  --delete SRC/ DEST/

rsync -avh --delete --max-delete=100 \
      ~/work/ /Volumes/Backup/work/

rsync -avhz --partial-dir=.rsync-partial \
      ~/site/ web:/srv/site/

rsync -avh --info=progress2 \
      web:/srv/data/ ~/data/

rsync -avh --delete-after \
      --filter='P /uploads/' --filter='P /.env' \
      ./dist/ web:/srv/app/

rsync -aHAX --delete \
      --link-dest=../$(ls /bk | tail -1) \
      ~/docs/ /bk/$(date +%F)/

rsync -nic src/ dst/
# no output = byte-identical

rsync -avh --remove-source-files src/ dst/
find src -type d -empty -delete

rsync -avhm --include='*/' \
      --include='*.jpg' --include='*.png' \
      --exclude='*' src/ dst/

rsync -rlt --no-perms --no-owner --no-group \
      --modify-window=1 --delete \
      ~/proj/ /mnt/c/Users/you/proj/

rsync -aXN --delete \
      ~/Documents/ /Volumes/Backup/Documents/

rsync -ain --delete /bk/2026-08-05/ /bk/2026-08-06/

rsync -ain --debug=FILTER2 src/ dst/ 2>&1 \
  | grep hiding

Flag reference

Itemize codes at a glance

YXcstpoguax  path
│││││││││││
││└─────────  c  checksum differs (needs -c) / changed symlink value
││ └────────  s  size differs
││  └───────  t  mtime differs (T = set to transfer time)
││   └──────  p  permissions differ
││    └─────  o  owner differs
││     └────  g  group differs
││      └───  u  atime (u) · crtime (n) · both (b) — needs -U / -N
││       └──  a  ACL differs      (needs -A)
││        └─  x  xattrs differ    (needs -X)
│└──────────  X  f file · d dir · L symlink · D device · S special
└───────────  Y  > received · < sent · c created · h hardlinked
               . attrs only · * message (e.g. *deleting)

Sources: rsync(1) — OPTION SUMMARY

Glossary

archive mode

-a, equivalent to -rlptgoD. Recursion plus preservation of symlinks, permissions, times, group, owner, and device/special files. Excludes ACLs, xattrs, atimes, crtimes, and hard-link detection. (§5)

basis file

The existing destination file the delta algorithm describes and builds upon. Without one, a transfer is entirely literal. Supplied implicitly by an existing file, or explicitly via --link-dest, --compare-dest, or --fuzzy. (§6)

block size

The chunk length the delta algorithm divides files into. Scales with file size by default; forced with -B. Determines the granularity of what counts as "unchanged". (§6)

daemon mode

rsync running as a server on TCP 873 (by default), publishing named modules. Addressed with host::module or rsync://host/module. Distinct from SSH transport. (§11)

delta-transfer algorithm

rsync's namesake: the receiver sends checksums describing the blocks it already has; the sender transmits only unmatched literal data plus references. Disabled by default for local-to-local copies. (§6)

dry run

-n. Makes every decision, performs none. Output is a plan, not a transcript — it reports directories it did not create. (§7)

extended attribute (xattr)

Out-of-band metadata attached to a file. On macOS holds Finder tags, Spotlight comments, quarantine flags, and resource forks. Preserved only with -X. (§12)

extraneous file

A file present at the destination but absent from the sender's file list. What --delete removes. Note that filter rules shape the file list first. (§9)

file list

The set of paths rsync intends to reconcile, built by walking the source and applying filter rules. Streamed incrementally in rsync 3.x, which is why large transfers start immediately. (§7)

filter rule

An include, exclude, protect, or hide directive. Evaluated in order; first match wins. Expressed via --exclude, --include, --filter, --exclude-from, or per-directory merge files. (§8)

generator

The rsync role that compares the file list against the destination and decides what to skip, update, create, or delete. Emits block checksums for the sender. (§1)

hard link

A second directory entry pointing at the same inode. Costs no additional data blocks. The basis of --link-dest snapshots and the reason -H exists. (§14)

in-place write

--inplace. Writes updates directly to the destination file rather than to a temporary file that is renamed. Saves space and preserves hard links and ACLs; forfeits atomicity. (§13)

itemized change string

The eleven-character code emitted by -i, e.g. >f.st....... Positions 1–2 give direction and file type; 3–11 name which attributes differ. (§7)

literal data

Bytes that had to be sent because no matching block existed at the destination. Reported by --stats alongside matched data. (§6)

merge file

A per-directory filter file, conventionally .rsync-filter, read when rsync enters that directory. Enabled with -F or --filter='dir-merge …'; -FF also excludes the file itself. (§8)

module

A named, path-mapped share published by an rsync daemon, defined by a [section] in rsyncd.conf. Carries its own permissions and optional authentication. (§11)

openrsync

An independent rsync reimplementation originating in OpenBSD and shipped by Apple as /usr/bin/rsync on current macOS. Speaks protocol 29. Lacks -X, --info=progress2, and modern compression; its -i output uses the older 9-character format. (§3)

partial file

An incomplete transfer preserved by --partial or --partial-dir, deliberately given an ancient mtime so the quick check cannot mistake it for complete. Becomes the basis on the next run. (§13)

protocol version

The wire-format level two rsyncs negotiate. 3.4.4 speaks 32; openrsync speaks 29. Mismatches negotiate down; unsupported options, not protocol, are what actually fail. (§3)

quick check

rsync's default test for whether a file needs transferring: size differs or mtime differs. Contents are not read. Overridden by -c, --size-only, or -I. (§6)

receiver

The rsync role that reassembles files at the destination, writing to a hidden temporary file and renaming it into place. (§1)

rolling checksum

A cheap checksum computable incrementally as a window slides one byte at a time. Lets the sender find matching blocks at arbitrary offsets, so inserted bytes do not defeat matching. (§6)

sender

The rsync role that reads the source tree, builds the file list, and computes deltas. Announced as --sender in the remote invocation when you are pulling. (§1)

snapshot (hardlinked)

A dated directory produced with --link-dest: a complete browsable tree whose unchanged files are hard links to the previous snapshot, so they cost no extra space. (§14)

sparse file

A file whose zero runs are not stored as blocks. Preserved with -S; without it, holes are materialized into real bytes. (§12)

trailing slash

On a source path, means "the contents of this directory" rather than "this directory". Irrelevant on a destination path for directory sources; significant for single-file sources. (§4)

transfer root

The directory that anchored filter patterns are relative to — the source as rsync sees it after applying the trailing-slash rule. /build means "build at the transfer root". (§8)

whole-file mode

-W. Sends files entire, skipping delta computation. Implied for local-to-local copies, where reading both files costs more than writing one. (§6)

Index

Retrieval quiz

Answer out loud before revealing. Retrieval builds durable memory in a way re-reading does not — this is the highest-value ten minutes in the guide. Aim for 16/19 before you consider rsync learned; revisit a day later and again a week later.

Sources

Checked with rsync 3.4.4, protocol version 32 (Homebrew) and openrsync, protocol version 29 (Apple, /usr/bin/rsync) on macOS 15.6 · 2026-08-07. Every transcript in this guide was captured from a real run in a temporary directory; where a mechanism could not be reproduced locally it is labelled as such. Remote-shell transcripts were produced with a logging stand-in for ssh, so the --server argv is genuine while the transport is a local pipe. External links require network access; the guide itself works offline.

• rsync(1) manual page — the authoritative reference for every flag in this guide. Best used for: exact option semantics, FILTER RULES, and EXIT VALUES. Read this one, not the openrsync page macOS gives you.
• rsyncd.conf(5) — daemon configuration. Best used for: module parameters, auth users, secrets file rules, chroot and strict modes.
• The rsync algorithm — Tridgell & Mackerras technical report — the original 1996 paper. Best used for: understanding rolling checksums and why block matching survives insertions. Short, readable, and still accurate.
• rsync home page — Best used for: confirming the current stable version and reading release announcements. 3.4.4 was released 2026-06-08.
• rsync NEWS file — Best used for: what changed between your version and current, and which CVEs a release fixed. 3.4.0 fixed six; 3.4.3 fixed six more.
• openrsync(1) — Best used for: knowing what Apple's /usr/bin/rsync actually supports, when you cannot install Homebrew rsync.
• Ubuntu rsync package versions — Best used for: confirming which rsync your Ubuntu or WSL release ships before you rely on a version-gated flag.
• CVE-2024-12084 (NVD) — Best used for: the concrete reason to run a patched rsync if you ever connect to a server you do not control. Heap buffer overflow in checksum parsing, fixed in 3.4.0.
• CVE-2026-29518 (NVD) — Best used for: understanding why use chroot = no is a real risk in daemon mode. TOCTOU symlink race, fixed in 3.4.3.
• systemd.timer(5) — Best used for: OnCalendar syntax, Persistent=true semantics for laptops, and randomized delays.
• Apple — Creating launchd jobs — Best used for: plist keys and the modern launchctl bootstrap / bootout verbs. Archived but still the clearest description of the model.
• ssh_config(5) — Best used for: ControlMaster connection reuse and ProxyJump, both of which belong in your config rather than in -e strings.