Commonly Used rsync Arguments

rsync is a powerful backup and copy utility. While it has many options, here are some of the more common ones that we thing you might be interested in. The complete list of options can be found on the rsync man page.

The Basic rsync Command

To begin, we should recap what a basic rsync command — with an SSH key for identity — looks like (all on one line):

rsync -avz -e "ssh -i /ssh-private-key" /source/folder username@username.evbackup.com:destination-folder

Noteworthy rsync Arguments (Args)

"To err is human. To arg is pirate."

There several options that you can add to the basic rsync command. Full documentation for all of the rsync command arguments can be found on the rsync online manual page. However, here some commons arguments that many people use in their rsync command:

-a   or   --archive

-a is equivalent to rsync -rlptgoD (no -H,-A,-X).

-a / --archive is a quick way of saying you want recursion and want to preserve almost all attributes of the source files (with -H being a notable omission).

Note that -a does not preserve hard links, because finding multiply-linked files is expensive. You must separately specify -H.

  • Show examples »
  • « Hide examples
rsync -avz ...
rsync --archive --verbose --compress ...

-v   or   --verbose

This option increases the amount of information you are given during the transfer (rsync works silently without it). A single -v will give you information about what files are being transferred and a brief summary at the end. Two -v options (-vv) will give you information on what files are being skipped and slightly more information at the end. More than two -v options should only be used if you have insomnia.

  • Show examples »
  • « Hide examples
rsync -avz ...
rsync --archive --verbose --compress ...

-z   or   --compress

With this option, rsync compresses the file data as it is sent to the destination machine, which reduces the amount of data being transmitted -- something that is useful over a slow connection.

Note that this option typically achieves better compression ratios than can be achieved by using a compressing remote shell or a compressing transport because it takes advantage of the implicit information in the matching data blocks that are not explicitly sent over the connection.

However, it's worth noting that some file types will not be compressed during transfer. The default list of file extensions that will not be compressed is: gz zip z rpm deb iso bz2 tbz tgz 7z mp3 mp4 mov avi ogg jpg jpeg

  • Show examples »
  • « Hide examples
rsync -avz ...
rsync --archive --verbose --compress ...

-n   or   --dry-run

This makes rsync perform a trial run that doesn't make any changes (and produces mostly the same output as a real run). It is most commonly used in combination with the -v, --verbose and/or -i, --itemize-changes and/or --delete options to see what an rsync command is going to do before one actually runs it.

  • Show examples »
  • « Hide examples
rsync -avzn ...
rsync -avz --dry-run...
rsync --archive --verbose --compress --dry-run...

--delete

USE WITH CAUTION: Deletions on the server are not recoverable.

This tells rsync to delete extraneous files from the receiving side (files that aren't on the sending side), but only for the directories that are being synchronized.

To delete directories, you must ask rsync to send the whole directory (e.g. "dir" or "dir/") without using a wild card for the directory's contents (e.g. "dir/*") since the wild card is expanded by the shell and rsync thus gets a request to transfer individual files, not the files' parent directory.

To protect your data, it is highly suggested to first try a run using the --dry-run option (-n) to see what files are going to be deleted.

  • Show examples »
  • « Hide examples
rsync -avz --delete
rsync --archive --verbose --compress --delete...

-t   or   --times

NOTE: Not required if you use -a or --archive

This tells rsync to transfer modification times along with the files and update them on the remote system. Note that if this option is not used, the optimization that excludes files that have not been modified cannot be effective; in other words, a missing -t or a missing -a will cause the next transfer to behave as if it used -I, causing ALL files to be updated.

  • Show examples »
  • « Hide examples
rsync -vzt ...
rsync --verbose --compress --times...

-p   or   --perms

NOTE: Not required if you use -a or --archive

To give destination files (both old and new) the source permissions, use --perms. To give new files the destination-default permissions (while leaving existing files unchanged), make sure that the --perms option is off and use --chmod=ugo=rwX (which ensures that all non-masked bits get enabled).

  • Show examples »
  • « Hide examples
rsync -vzp ...
rsync --verbose --compress --perms...

-s   or   --protect-args

This option sends all file names and most options to the remote rsync without allowing the remote shell to interpret them. This means that spaces are not split in names, and any non-wildcard special characters are not translated (such as ~, $, ;, &, etc.). Wild cards are expanded on the remote host by rsync (instead of the shell doing it).

  • Show examples »
  • « Hide examples
rsync -avzs ...
rsync -avz --protect-args ...
rsync --archive --verbose --compress --protect-args...

-i   or   --itemize-changes

This option requests a simple itemized list of the changes that are being made to each file, including attribute changes. This is exactly the same as specifying --out-format='%i %n%L'. If you repeat the option, unchanged files will also be output.

For further details about --itemize-changes, see the rsync online manual page

  • Show examples »
  • « Hide examples
rsync -avzi ...
rsync -avz --itemize-changes ...
rsync --archive --verbose --compress --itemize-changes...

-l   or   --links

NOTE: Not required if you use -a or --archive

When symbolic links are encountered in the source files, rsync will recreate the symlink on the destination server instead of copying the file or folder that the symlink points to.

-H   or   --hard-links

This option tells rsync to look for hard-linked files in the transfer and link together the corresponding files on the receiving side. Without this option, hard-linked files in the transfer are treated as though they were separate files.

Note that rsync can only detect hard links between files that are inside the transfer set. If rsync updates a file that has extra hard-link connections to files outside the transfer, that linkage will be broken. If you are tempted to use the --inplace option to avoid this breakage, be very careful that you know how your files are being updated so that you are certain that no unintended changes happen due to lingering hard links (and see the --inplace option for more caveats).

-h   or   --human-readable

This option produces numbers in the log file and stdout in a more human-readable format. This makes big numbers output using larger units, with a K (kilobytes), M (megabytes), or G (gigabytes) suffix. If this option was specified once, these units are K (1000), M (1000*1000), and G (1000*1000*1000). If the option is specified twice (-hh) the units are powers of 1024 instead of 1000.

  • Show examples »
  • « Hide examples
rsync -avzh ...
rsync -avz --human-readable ...
rsync --archive --verbose --compress --human-readable...

--log-file=[File]

This option tells the rsync daemon to use the given log-file name instead of using the default "log file" setting. If you would like to keep a log file of your backups, this is the option for you.

  • Show examples »
  • « Hide examples
rsync -avz --log-file=/backup/rsync-job.log...
rsync --archive --verbose --compress --log-file=/backup/rsync-job.log...

--progress

This option tells rsync to print information showing the progress of the transfer. This gives a bored user something to watch. It implies --verbose if it wasn't already specified. The progress information looks like this:
782448 63% 110.64kB/s 0:00:04

In that example, the receiver has reconstructed 782448 bytes (or 63%) of the sender's file, which is being reconstructed at a rate of 110.64 kilobytes per second, and the transfer will finish in 4 seconds if the current rate is maintained until the end.

  • Show examples »
  • « Hide examples
rsync -avz --progress...
rsync --archive --verbose --compress --progress...