rsync: Usage, Options & Common CI Errors
rsync copies only the differences, making repeat transfers fast.
rsync is the workhorse for deploys and cache restores. The two things that bite people are the trailing-slash semantics on the source path and the destructive --delete flag.
What it does
rsync copies files between locations, transferring only changed blocks. Over SSH it is the efficient alternative to scp; locally it is a fast, mirror-capable copy.
Common usage
rsync -avz ./dist/ user@host:/var/www/ # trailing / = copy contents
rsync -av ./dist user@host:/var/www/ # no / = copy the dir itself
rsync -az --delete ./build/ host:/srv/ # mirror, removes extras
rsync -av --exclude='node_modules' ./ host:/app/
rsync -e "ssh -i key.pem" -avz src/ host:/dst/Options
| Flag | What it does |
|---|---|
| -a / --archive | Recurse + preserve perms, times, symlinks |
| -v | Verbose |
| -z | Compress during transfer |
| --delete | Remove files in dest not in source (mirror) |
| --exclude=PATTERN | Skip matching paths |
| -n / --dry-run | Show what would change |
Common errors in CI
A trailing slash on the source (src/) copies its contents; without it (src) the directory itself is nested under the dest - a frequent "wrong layout" bug. Exit 23 = partial transfer (some files vanished or were unreadable); exit 12 = error in the rsync protocol stream (often an SSH/auth failure on the remote). --delete is destructive - always --dry-run first. "rsync: command not found" on the remote means rsync is not installed there.