keepcalculator

06 Numbers and Powers

rsync Delete Safely: A Practical Guide

Card No. 06·79669 · Updated · Standard formula, shown below

Rsync is a powerful file synchronization tool, but its delete options can be dangerous if used carelessly. This guide explains how to use rsync’s delete flags safely, covering the essential options, safety checks, and common pitfalls. You’ll learn how to synchronize directories while ensuring you never accidentally delete files you need.

What You’ll Need

  • A Unix-like system (Linux, macOS, BSD) with rsync installed (usually pre-installed).
  • Two directories: a source and a destination. They can be local or remote (via SSH).
  • Basic familiarity with the command line.
  • Optional: a test directory with dummy files to practice on.

Step-by-Step

  1. Understand the default behavior. Without any delete flag, rsync copies files from the source to the destination, but it does not remove files in the destination that are not in the source. This is safe but can lead to a destination that has extra files.
  2. Use –dry-run first. Always run rsync with the --dry-run (or -n) option before doing a real sync. This shows what would be transferred and deleted without actually doing it. Example: rsync -av --delete --dry-run /source/ /destination/
  3. Add the –delete flag. When you are ready to delete extra files in the destination, add --delete to your rsync command. This tells rsync to remove files in the destination that are not in the source. Important: This only applies to files within the destination directory itself, not to files outside it.
  4. Protect the destination path with a trailing slash. When using --delete, always put a trailing slash on the source path (e.g., /source/) to copy the contents of the source into the destination. If you omit the trailing slash, rsync copies the source directory itself into the destination, which can lead to unexpected deletions. Example: rsync -av --delete /source/ /destination/
  5. Use –delete-excluded for fine control. If you have an exclude list (e.g., --exclude='*.tmp'), by default rsync will not delete excluded files in the destination. If you want to delete them too, add --delete-excluded. Use this with caution.
  6. Consider –delete-delay. This option moves files to be deleted into a hidden trash directory (named .rsync-trash) inside the destination, rather than permanently deleting them. This gives you a chance to recover files if you made a mistake. Example: rsync -av --delete-delay /source/ /destination/
  7. Use –backup for extra safety. The --backup option (or -b) backs up files that would be overwritten or deleted to a backup directory (specified with --backup-dir). This is a great safety net. Example: rsync -av --delete --backup --backup-dir=/path/to/backup /source/ /destination/
  8. Test with a real but small directory. Before running a production sync, test the command on a small directory with dummy files to verify the behavior.
  9. Run the real command. Once you are confident, remove --dry-run and run the actual sync. Monitor the output to see what is being deleted.

Common Mistakes

  • Forgetting the trailing slash on the source. This is the most common mistake. Without it, rsync creates a subdirectory in the destination, and the delete behavior can be unexpected.
  • Using –delete on a destination that contains files you want to keep. Always double-check that the destination is truly a mirror of the source.
  • Not using –dry-run. Skipping the dry run is like playing Russian roulette with your data.
  • Confusing –delete with –delete-excluded. The former only deletes files that are not in the source; the latter also deletes files that are excluded but present in the destination.
  • Running rsync as root without care. If you run rsync as root, it can delete files that belong to other users. Always use the least privilege necessary.

Tips

  • Always use -v (verbose) to see what rsync is doing.
  • Use --itemize-changes (or -i) to see exactly what is being transferred, updated, or deleted.
  • Combine --delete with --backup and --backup-dir to have a rollback option.
  • For remote syncing, test with a local directory first to ensure your paths are correct.
  • Consider using --delete-after instead of the default --delete-before. The default deletes files before transferring new ones, which can be risky if the transfer fails. --delete-after deletes after the transfer, so new files are in place first.

Troubleshooting

  • Files are not being deleted. Check if you have any --exclude patterns that might be protecting those files. Also, ensure the source path has a trailing slash.
  • Files are deleted that I wanted to keep. If you used --delete without a backup, it’s hard to recover. Check if you have a backup from before the sync. If you used --delete-delay, look in the .rsync-trash directory inside the destination.
  • rsync says “Permission denied”. You may not have write permission on the destination or delete permission on the files. Check the ownership and permissions.
  • rsync is slow. If you are syncing a huge directory, consider using --delete-after to avoid holding locks during the delete phase.
  • The dry run shows deletions but the real run doesn’t delete. This can happen if the source changes between the dry run and the real run. Always run the dry run immediately before the real run.

Frequently Asked Questions

Does rsync delete files in the destination that are not in the source?

Only if you use the --delete flag. Without it, rsync only copies new or updated files.

What is the difference between –delete and –delete-excluded?

--delete deletes files in the destination that are not in the source. --delete-excluded also deletes files that are excluded by your exclude patterns but exist in the destination.

Can I undo a rsync deletion?

If you used --backup or --delete-delay, you can recover files from the backup directory or the .rsync-trash folder. Otherwise, you need a separate backup.

Is it safe to use –delete on a remote server?

Yes, but you must be extra careful with the paths. Always test with a dry run and ensure you are connecting to the correct server and directory.

What does the trailing slash on the source do?

It tells rsync to copy the contents of the source directory into the destination, rather than copying the source directory itself as a subdirectory. This is crucial for correct delete behavior.

Can I use –delete with –exclude to keep certain files?

Yes, by default excluded files are not deleted. If you want to delete them too, add --delete-excluded.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →