rsync starters, one move per page
Twenty-eight steps for people who copy with cp and sync by luck: the one command shape and its three transports, the quick check that skips unchanged files, the famous delta algorithm that sends only differences, the trailing slash and what it really copies, -a archive and its -rlptgoD, the small watching flags -v -h -P, compression for slow links, the dry run habit, --delete as a mirror with its guards, --backup as the net, -i itemized changes and exit codes 0, 1, 23 and 24, exclude pattern grammar, -u update, --link-dest snapshots that share storage, resumable partial transfers, and the whole tool on one page, one move per page.
A diagram, the classic trap, and one thing to go try this week. That's a page.
rsync starters, one move per page
Twenty-eight steps for people who copy with cp and sync by luck: the one command shape and its three transports, the quick check that skips unchanged files, the famous delta algorithm that sends only differences, the trailing slash and what it really copies, -a archive and its -rlptgoD, the small watching flags -v -h -P, compression for slow links, the dry run habit, --delete as a mirror with its guards, --backup as the net, -i itemized changes and exit codes 0, 1, 23 and 24, exclude pattern grammar, -u update, --link-dest snapshots that share storage, resumable partial transfers, and the whole tool on one page, one move per page.
Set in Space Grotesk, Inter and JetBrains Mono (SIL Open Font License).
rsync behaviour checked against the rsync(1) and rsyncd.conf(5) man pages (download.samba.org/pub/rsync), fetched and read during this build. Flags, defaults, limits and edge cases are named as those documents name them. Teaching conventions (one move a page) are named as conventions. This book quotes no verbatim passages and is an independent guide not affiliated with or endorsed by the rsync project or the Samba team.
General information only. Not professional advice; verify against your own rsync and the current documentation.
Your purchase is for personal use only. You do not have redistribution rights: please do not share, resell, or republish this book or its pages.
© 2026 Steve Hodgkiss. All rights reserved. Personal use only; no redistribution rights.
Edition 1.0 · stevehodgkiss.net
Contents
Per the rsync(1) man page, a trailing slash on the source changes this behavior to avoid creating an additional directory level at the destination: think of a trailing slash on a source as meaning copy the contents of this directory as opposed to copy the directory by name. rsync -av /src/foo /dest and rsync -av /src/foo/ /dest/foo copy the files the same way.
Copy, then sync
Let's say you copy a folder to a drive every Friday. cp does the whole thing again, every time.
rsync copies too, but it's a sync: the second run looks first and moves only what changed. The man page's own first example is a plain copy with archive mode, and it behaves like an improved copy command when both paths are local. Same command Friday, and almost nothing transfers.
Copy once, then keep it true. That's the whole habit.
Replace one weekly cp with rsync -av this week. Time both runs, the second should be near instant.
Per the rsync(1) man page: A trailing slash on the source changes this behavior to avoid creating an additional directory level at the destination. You can think of a trailing / on a source as meaning copy the contents of this directory as opposed to copy the directory by name. rsync -av /src/foo /dest and rsync -av /src/foo/ /dest/foo copy the files the same way, including setting the attributes of /dest/foo.
The trailing slash
Let's say you run rsync again and get src/src/src. The slash did that.
The man page says it best: a trailing slash on the source means copy the contents of this directory. Without it, you copy the directory by name, an extra level created at the destination. It's on the source that this matters, and rsync -av /src/foo /dest is exactly the same copy as rsync -av /src/foo/ /dest/foo.
Slash for contents, no slash for the folder. Decide before you press enter.
Make two scratch folders this week and run rsync -avn both ways, with and without the slash. Read the file list before trusting it.
Safety
The flags that can hurt, and their brakes: the dry run rehearsal, --delete's mirror and its guards, and --backup's net under it.
- 01-n, the dry run
- 02--delete, the mirror
Per the rsync(1) man page: --dry-run, -n makes rsync perform a trial run that doesn't make any changes, and produces mostly the same output as a real run. It is most commonly used in combination with --verbose and/or --itemize-changes to see what an rsync command is going to do before one actually runs it.
-n, the dry run
Let's say the command could delete things. Find out before it does.
-n is a trial run: same output as the real thing, zero changes made. The man page pairs it with -v or -i so you see the full list of what would happen. It's free, it's fast, and the man page says the same about --delete: dry run first. Every destructive flag earns a rehearsal.
One keystroke, and the mistake never happens.
Before your next real sync this week, run it with -n first. Read the whole list.
Per the rsync(1) man page: --delete deletes extraneous files from the receiving side, those that don't exist on the sending side, but only for the directories that are being synchronized, and you must have asked rsync to send the whole directory rather than a wildcard like dir/*, which the shell expands into individual files. The option has no effect unless either --recursive or --dirs is enabled. If the sending side detects any I/O errors, deletion of files at the destination is automatically disabled.
--delete, the mirror
Let's say you deleted half a folder and want the backup to match. --delete is that flag.
It removes extraneous files on the receiving side, anything the source no longer has, but only the destination obeys: the source is never touched. Two guards the man page builds in: it needs the whole directory, not a shell-expanded wildcard like dir/*, and if the sender hits I/O errors, deletion stops automatically, so a flaky disk can't masquerade as mass deletion.
A mirror is a promise: what's gone stays gone. Count the cost first.
Dry run a --delete this week with -avn and read every deleting line before you commit to it.