Lorixen.
EN

Deploying a website with rsync without deleting the wrong files

Short answer: rsync copies only what changed, making it a fast way to deploy a site, and two details decide whether it's safe: first, a trailing slash on the source (build/ versus build) changes whether you copy the folder's contents or the folder itself. Second, --delete removes files on the server that aren't in your build, which is great for stale files and disastrous for uploads, user content and server-only config unless you exclude them. Run the command with --dry-run first, exclude what lives only on the server and set --max-delete as a safety limit.

A safe starting command

rsync -av --delete --dry-run \
  --exclude 'uploads/' --exclude '.env' --exclude 'cache/' \
  build/ deploy@server:/var/www/site/

Read the dry-run output, then remove --dry-run and run it for real. Each part matters, so here's what it does.

The trailing slash

The rsync manual explains that a trailing slash on the source avoids creating an extra directory level at the destination. Think of build/ as "the contents of build" and build as "the folder called build".

  • rsync -av build/ server:/var/www/site/ puts index.html at /var/www/site/index.html.
  • rsync -av build server:/var/www/site/ puts it at /var/www/site/build/index.html.

Get this wrong with --delete and rsync may decide everything in the site folder is extra.

What --delete really does

The manual describes --delete as deleting extraneous files on the receiving side, meaning files that don't exist on the sending side, but only for the directories being synchronised. Two consequences:

  • It's what you want for stale files. Renamed scripts, old images and removed pages disappear instead of lingering on the server, where they can still be reached and indexed.
  • It's dangerous for server-only content. Customer uploads, generated thumbnails, log files and .env config exist only on the server. Without exclusions, they're "extraneous" and get deleted.

Also note from the manual: --delete only works when you sync a whole directory. If you use a shell wildcard like build/*, rsync receives a list of files and won't delete anything.

Protect server-only files with excludes

The manual says files excluded from the transfer are also excluded from deletion, unless you add --delete-excluded or use rules that only apply on the sending side. So excluding uploads/ both stops rsync copying your local test uploads and stops it deleting the real ones.

Common things to exclude for a website or app:

  • user uploads and media folders
  • .env and other server-specific config
  • cache and session folders
  • log files
  • anything your server or CMS writes at runtime

Keep the list in a file and use --exclude-from=deploy-excludes.txt so everyone deploys with the same rules.

Dry runs and itemised changes

--dry-run (or -n) performs a trial run with no changes made. Add --itemize-changes (-i) to get a line per file showing what would be sent or deleted. Scan the "deleting" lines before every first deploy to a new server, and after any change to your excludes or folder structure.

A safety limit on deletions

The manual describes --max-delete=NUM, which stops rsync deleting more than that many files; further deletions are skipped and rsync exits with an error. --max-delete=0 warns about extra files without removing any. In an automated deploy, a sensible limit turns a wrong path from a disaster into a failed job you can investigate.

Fewer half-updated moments

rsync updates files one by one, so for a moment a visitor might load new HTML with old CSS. The manual mentions --delay-updates, which puts updated files in place at the end of the transfer, so files appear at almost the same time. For bigger sites, deploying into a new release folder and switching a symlink is cleaner, because the switch happens in one step and rollback is just switching back.

Check the destination path twice

A typo in the destination is the other classic accident: /var/www/ instead of /var/www/site/ with --delete treats every other site on the server as extraneous. Put the destination in a variable in your deploy script, check it isn't empty or a top-level folder before running, and test the script against a staging server first. These two lines of checking cost nothing and have saved many servers.

Permissions and ownership

-a (archive) preserves permissions and timestamps from your machine. If your local files have different permissions from what the web server needs, use options such as --chmod or run a short permission fix after deploying. Deploy as a dedicated user rather than root, and give that user write access only to the site folder.

Using rsync from CI

Automating the deploy removes the biggest risk, which is someone typing a slightly different command from memory.

The same command works from a CI pipeline with an SSH key stored as a secret. Keep the dry-run step for pull requests, so reviewers can see what a deploy would change, and the real deploy for the main branch only.

A worked example

An illustrative Austin café's website ran on a small server with an online ordering add-on that stored menu photos in uploads/. A new developer deployed with rsync -av --delete build/ server:/var/www/site/ and every uploaded photo vanished, because uploads/ didn't exist in the build. Photos were restored from the host's backup. The team then added an excludes file covering uploads, .env and cache, made a dry run mandatory before the first deploy on any server, and set a --max-delete limit in the deploy script.

FAQ

Is rsync better than FTP for deploying?

It's faster, transfers only changes and runs over SSH. FTP has no equivalent of excludes plus delete.

What does -z do?

It compresses data during transfer, which helps on slow connections and matters little on fast ones.

Can rsync roll back a bad deploy?

Not by itself. Keep previous builds, or use release folders with a symlink switch.

Do I need --delete at all?

Without it, deleted files stay on the server. Use it with excludes and a dry run.

If your deploy process feels risky, describe how you push changes today and we'll help you make it repeatable and safe.

Sources

WhatsAppBook a call