1.4 rsync

rsync – a fast, versatile, remote (and local) file-copying tool

1.4.1 Synopsis

Usages with just one SRC arg and no DEST arg will list the source files instead of copying.

1.4.2 Advanced usage

1.4.3 Connecting to an rsync daemon

It is also possible to use rsync without a remote shell as the transport. In this case you will directly connect to a remote rsync daemon, typically using TCP port 873.

Some modules on the remote daemon may require authentication. If so, you will receive a password prompt when you connect. You can avoid the password prompt by setting the environment variable RSYNC_PASSWORD to the password you want to use or using the option:

This may be useful when scripting rsync.

1.4.4 Options

Rsync accepts both long (double-dash + word) and short (single-dash + letter) options. When specifying a parameter, you can either use the form --option=param or replace the = with whitespace.

• --no-OPTION

  You may turn off one or more implied options by prefixing the option name with no-.

• --info=FLAGS

  Use --info=help to see all the available flag names. Use OPT or OPT1 for level 1 output, OPT2 for level 2, etc.; OPT0 silences. Some flags:

  • FLIST

    Mention file-list receiving/sending (levels 1-2).

  • NAME

    Mention 1) updated file/dir names, 2) unchanged names.

  • PROGRESS

    Mention 1) per-file progress or 2) total transfer progress.

  • STATS

    Mention statistics at end of run (levels 1-3).

• --stats

  This tells rsync to print a verbose set of statistics on the file transfer, equivalent to --info=stats2 or --info=stats3.

• --progress

  This option tells rsync to print information showing the progress of the transfer. This gives a bored user something to watch. With a modern rsync this is the same as specifying

  --info=flist2,name,progress

  .

• --human-readable, -h

  Output numbers in a more human-readable format.

• --verbose, -v

  This option increases the amount of information you are given during the transfer. A single -v will give you information about what files are being transferred and a brief summary at the end. Two

  -v

  options will give you information on what files are being skipped and slightly more information at the end.

• --ignore-times, -I

  Normally rsync will skip any files that are already the same size and have the same modification timestamp. This option turns off this "quick check" behavior, causing all files to be updated.

• --checksum, -c

  This changes the way rsync checks if the files have been changed and are in need of a transfer to comparing a 128-bit checksum for each file that has a matching size. Lots of disk I/O reading. Files with either a changed size or a changed checksum are selected for transfer.

• --protect-args, -s

  This option sends all filenames and most options to the remote rsync without allowing the remote shell to interpret them. Spaces are not split in names, and any non-wildcard special characters are not translated. Wildcards are expanded on the remote host by rsync (instead of the shell doing it).

• --archive, -a

  This is equivalent to -rlptgoD. It is a quick way of saying you want recursion and want to preserve almost everything (with -H being a notable omission).

• --hard-links, -H

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

• --recursive, -r

  This tells rsync to copy directories recursively. Beginning with rsync 3.0.0, the recursive algorithm used is now an incremental scan that begins the transfer after the scanning of the first few directories have been completed. Incremental recursion can be disabled using the --no-inc-recursive option or its shorter --no-i-r alias.

• --links, -l

  When symlinks are encountered, recreate the symlink on the destination.

• --perms, -p

  This option causes the receiving rsync to set the destination permissions to be the same as the source permissions.

• --times, -t

  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 will cause the next transfer to behave as if it used -I, causing all files to be updated.

• --group, -g

  This option causes rsync to set the group of the destination file to be the same as the source file. Without this option, the group is set to the default group of the invoking user on the receiving side.

• --owner, -o

  This option causes rsync to set the owner of the destination file to be the same as the source file, but only if the receiving rsync is being run as the super-user. Without this option, the owner of new and/or transferred files are set to the invoking user on the receiving side.

• -D

  Equivalent to --devices --specials.

• --devices

  This option causes rsync to transfer character and block device files to the remote system to recreate these devices.

• --specials

  This option causes rsync to transfer special files such as named sockets and fifos.

• --backup, -b

  With this option, preexisting destination files are renamed as each file is transferred or deleted.

• --backup-dir=DIR

  This implies the --backup option, and tells rsync to store all backups in the specified directory on the receiving side. This can be used for incremental backups.

• --relative, -R

  Use relative paths. This means that the full path names specified on the command line are sent to the server rather than just the last parts of the filenames.

• --update, -u

  This forces rsync to skip any files which exist on the destination and have a modified time that is newer than the source file.

• --dirs, -d

  Tell the sending side to include any directories that are encountered. Unlike --recursive, a directory’s contents are not copied unless the directory name specified is "." or ends with a trailing slash. Without this option or the --recursive option, rsync will skip all directories it encounters.

• --dry-run, -n

  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 *-vi* options to see what an rsync command is going to do before one actually runs it.

• --itemize-changes, -i

  Requests a simple itemized list of the changes that are being made to each file, including attribute changes.

• --delete

  This tells rsync to delete extraneous files from the receiving side (ones that aren’t on the sending side), but only for the directories that are being synchronized. The d in delete stands for DANGEROUS.

• --temp-dir=DIR, -T

  This option instructs rsync to use DIR as a scratch directory when creating temporary copies of the files transferred on the receiving side. The default behavior is to create each temporary file in the same directory as the associated destination file. This option is most often used when the receiving disk partition does not have enough free space to hold a copy of the largest file in the transfer.

• --compress, -z

  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.

• --log-file=FILE

  This option causes rsync to log what it is doing to a file. This is similar to the logging that a daemon does, but can be requested for the client side and/or the server side of a non-daemon transfer.

• --partial

  Tells rsync to keep the partial file which should make a subsequent transfer of the rest of the file much faster.

• -P

  Equivalent to --partial --progress. There is also a --info=progress2 option that outputs statistics based on the whole transfer, rather than individual files. Use this flag without outputting a filename (e.g. avoid -v or specify --info=name0) if you want to see how the transfer is doing without scrolling the screen with a lot of names.

• --inplace

  Instead of creating temporary files, write the updated data directly to the destination file. This option is useful for transferring large files with block-based changes or appended data, and also on systems that are disk bound. The option implies --partial.

• --append

  Efficiently update files where any existing content on the receiving side is also known to be the same as the content on the sender. Use append only in this particular case.

• --append-verify

  Like --append except that all the data in the file is included in the checksum verification.

• --bwlimit=RATE

  Specify the maximum transfer rate for the data sent over the socket. The RATE value can be suffixed with a string to indicate a size multiplier, and may be a fractional value. If no suffix is specified, the value will be assumed to be in units of 1024 bytes (as if "K" or "KiB" had been appended).

1.4.5 Examples

1.4.6 Version

This man page is current for version 3.2.3 of rsync.

1.4.7 Author

rsync was originally written by Andrew Tridgell and Paul Mackerras. It is currently maintained by Wayne Davison.