An rsync Crash Course

16 Apr 2019

Whether you’re a beginner Bash scripter or seasoned sysadmin, rsync is an indispensable tool for efficient file transfer and synchronization. It’s easy to use, yet incredibly powerful, and beguiles many a script kiddie and cargo-cult programmer alike, myself included at times. While I do encourage everyone to #ReadTheDocs and open man rsync, it’s less of a page and more of a novella, so let’s take a bird’s-eye view and look at some of the more useful options, and practical examples of their application.

Usage overview

rsync [option(s)] [source(s)] [destination]

Like most commands, rsync has a fairly straight-forward signature: Options follow the executable name, then a list of sources to send, with their destination at the end.

Options

-a, —archive, same as -rlptgoD, recursively sync source directory while preserving all attributes except hard links
-D , same as —devices —specials, syncs system files used to represent connected devices and special files such as shortcuts, and sockets and pipes related to inter-process communication.^[1]
—delete, delete all files in the destination not present in the source
-e, —rsh=COMMAND, specify the remote shell to use
-g, —group, preserve group
-h, —human-readable, —progress
-l, —links, copy symlinks
—safe-links, ignore symlinks that point outside the directory from being copied
-n, --dry-run
-o, —owner, preserve owner
-p, —perms, preserve permissions
-r, —recursive, recurse into directories in source
-t, —times, preserve times
-u, —update, skip files with a newer timestamp at the destination
-v, —verbose, increase output verbosity
-z, —compress, compress file data during the transfer
—include=PATTERN, only sync files matching the given pattern
—exclude=PATTERN, skip files matching the given pattern
—include-from=FILE, read inclusion pattern from given file
—exclude-from=FILE, read exclusion pattern from given file
—files-from=FILE, read list of source-file names from given file

Sync local directories

rsync -avz —delete /src/directory/ /dest/directory

Note that the trailing / on a source directory indicates to copy its contents rather than the directory itself.

Sync remote directories

rsync -avz -e ssh /src/directory/ user@host:/dest/directory

macOS

When sending the contents of a volume from its root on macOS, save yourself some cycles and remember to exclude a few volume-specific hidden directories.^[2]

... —-exclude={ '.fseventsd', '.Spotlight-V100', '.Trashes' }

Permissions and owners and timestamps, oh my!

For most use cases, the --archive flag works perfectly well, but not all. One such case is sending files to a directory with a different owner, for example /var/www on a web server. One probably wouldn’t want to preserve ownership or group of the files being sent in that case, and would want to simply use just -r instead of -a.

Conclusion

rsync is a powerful yet easy to use file transfer and synchronization utility that has a spot in every developer’s tool belt. While it is just as easy to misuse at times, having an understanding of its most common use cases will help guide you through the documentation and navigate those edge cases where --archive isn’t quite the answer.