rsync Reference

The -a flag enables archive mode, which is equivalent to -rlptgoD: it recursively copies directories (-r), preserves symlinks (-l), preserves permissions (-p), preserves modification times (-t), preserves group ownership (-g), preserves owner (-o), and preserves device/special files (-D). The -v flag enables verbose output so you can see each file being transferred. Use -av as your default starting point for most synchronization tasks.

The trailing slash on the source path makes a significant difference. With a trailing slash (rsync -av /src/ /dest/), rsync copies the contents of /src/ directly into /dest/, so the files end up in /dest/file.txt. Without a trailing slash (rsync -av /src /dest/), rsync copies the directory itself, creating /dest/src/file.txt. The destination path trailing slash does not matter. This is one of the most common sources of rsync mistakes.

Use the -n or --dry-run flag: rsync -avn --delete /src/ /dest/. Combined with -v, this shows exactly which files would be created, updated, or deleted without actually making any changes. Always run a dry run before using --delete or other destructive operations to verify the file list is what you expect. The output format is the same as a real run, making it easy to review.

Use the --link-dest option to create hard-link-based incremental backups. The pattern is: LATEST=$(ls -td /backup/*/ | head -1) && rsync -av --link-dest="$LATEST" /src/ /backup/$(date +%Y%m%d)/. Files that have not changed since the last backup are hard-linked from the previous backup directory (using no extra disk space), while changed files are copied fresh. Each dated backup directory appears to contain a complete copy but uses minimal additional space.

Use the -e flag to specify SSH transport options: rsync -avz -e "ssh -p 2222" /local/ user@remote:/data/. The -e option replaces the default remote shell command, so you can pass any ssh flags including -p for port, -i for key file, -o for SSH config options, and -C for SSH-level compression. If you use a non-standard port frequently, add it to your ~/.ssh/config with Host and Port directives instead.

Use --exclude flags: rsync -av --exclude='.git/' --exclude='node_modules/' /project/ user@server:/var/www/project/. You can chain multiple --exclude flags. For larger projects, put all exclusion patterns in a text file (one per line) and use --exclude-from=exclude-list.txt. Alternatively, use --cvs-exclude (or -C) which automatically excludes common VCS and build artifact directories including .git, .svn, *.o, and *.swp.

The --delete flag causes rsync to delete files in the destination that no longer exist in the source, making the destination an exact mirror of the source. This is essential for true mirroring but dangerous if used carelessly — any file that exists only in the destination will be permanently deleted. Always run with --dry-run first to verify the file list, and consider using --backup or --backup-dir to save deleted files before using --delete in production.

By default, rsync decides whether to transfer a file by comparing its size and modification time. This is fast but can miss cases where a file was modified and restored to the same size and timestamp. The --checksum flag forces rsync to compute an MD5 or similar checksum of each file and compare checksums instead of size/time. This is slower (requires reading every byte of every file) but guarantees bit-for-bit accuracy. Use --checksum when data integrity is critical, such as after media copy or when timestamps cannot be trusted.