rclone sync: Mirror a Directory to a Remote
rclone sync makes the destination identical to the source, which means it deletes files present at the destination but not at the source.
sync is the destructive sibling of copy: it removes stale destination files so the two sides match. That makes it ideal for static-site deploys where old assets should be purged, and dangerous if you point it the wrong way.
What it does
rclone sync copies new and changed files from source to destination and then deletes any destination files that are not in the source. The end state is that destination equals source. Always run with --dry-run first to see the deletions.
Common usage
# deploy a static site, purging removed pages
rclone sync ./public s3remote:www-bucket --transfers 32 --checkers 32
# preview before committing to deletions
rclone sync ./public s3remote:www-bucket --dry-runOptions
| Flag | What it does |
|---|---|
| --dry-run | Show adds and deletes without changing anything |
| --transfers N | Parallel transfers (default 4) |
| --checkers N | Parallel comparison workers (default 8) |
| --delete-excluded | Also delete destination files matched by --exclude |
| --track-renames | Detect renames and move server-side instead of re-uploading |
| --backup-dir <path> | Move deleted/overwritten files here instead of removing them |
In CI
Because sync deletes, double-check the argument order: rclone sync SOURCE DEST, never the reverse, or you can wipe local build output. Use --backup-dir to keep a copy of anything it would delete. For invalidating a CDN after the sync, run the CDN command separately; rclone only touches the bucket.
Common errors in CI
"directory not found" on the source means the build folder is missing. "Failed to sync: AccessDenied" means the role lacks s3:DeleteObject (sync needs delete permission, copy does not). "corrupted on transfer: sizes differ" points at a truncated upload, often a flaky network on a large object. Reduce --transfers or add --retries 5.