rsync

Name

rsync -- faster, flexible replacement for rcp

Synopsis

rsync [OPTION]... SRC [SRC]... [USER@]HOST:DEST
rsync [OPTION]... [USER@]HOST:SRC DEST
rsync [OPTION]... SRC [SRC]... DEST
rsync [OPTION]... [USER@]HOST::SRC [DEST]
rsync [OPTION]... SRC [SRC]... [USER@]HOST::DEST
rsync [OPTION]... rsync://[USER@]HOST[:PORT]/SRC [DEST]

Description

rsync behaves in much the same way that rcp does, but has many more options and uses its remote-update protocol to greatly speedup file transfers when the destination file already exists.

The remote-update protocol allows rsync to transfer just the differences between two sets of files across the network link, using an efficient checksum-search algorithm described in the technical report that accompanies this package.

Standard Options

--version

prints the rsync version number and exits.

-v, --verbose

increases the amount of information given during the transfer. By default, rsync works silently. A single -v gives information about what files are being transferred and a brief summary at the end. Two -v flags give information on what files are being skipped and slightly more information at the end.

-q, --quiet

decreases the amount of information given during the transfer, notably suppressing information messages from the remote server. This flag is useful when invoking rsync from cron.

-I, --ignore-times

turns off the skipping of files that are already the same length and have the same time-stamp.

-c, --checksum

forces the sender to checksum all files using a 128-bit MD4 checksum before transfer. The checksum is then explicitly checked on the receiver and any files of the same name which already exist and have the same checksum and size on the receiver are skipped. This option can be quite slow.

-a, --archive

is a shortcut for specifying recursion and to preserve all attributes.

-r, --recursive

copies directories recursively. If not specified, rsync will not copy directories at all.

-R, --relative

uses 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.

-b, --backup

renames preexisting destination files with a ~ extension as each file is transferred. You can control the backup suffix using the --suffix option.

--backup-dir=DIR

combines with --backup to store all backups in the specified directory. This is very useful for incremental backups.

--suffix=SUFFIX

overrides the default backup suffix used with the -b option. The default is a ~.

-u, --update

skips any files for which the destination file already exists and has a date later than the source file.

-l, --links

recreates symbolic links on the remote system to be the same as the local system. Without this option, all symbolic links are skipped.

-L, --copy-links

transfers the file referenced by a symbolic link, rather than recreating the link.

--copy-unsafe-links

treats symbolic links that point outside the source tree like ordinary files. Absolute symlinks are also treated like ordinary files, and so are any symlinks in the source path itself when --relative is used.

--safe-links

ignores any symbolic links that point outside the destination tree. All absolute symlinks are also ignored.

-H, --hard-links

recreates hard links on the remote system to be the same as the local system. Without this option hard links are treated like regular files.

-W, --whole-file

does not use the incremental rsync algorithm and sends the whole file as-is instead. This may be useful when using rsync with a local machine.

-p, --perms

updates the remote permissions to be the same as the local permissions.

-o, --owner

updates the remote owner of the file to be the same as the local owner. This is only available to the super-user. Note that if the source system is a daemon using chroot, --numeric-ids is implied because the source system cannot get access to the usernames.

-g, --group

updates the remote group of the file to be the same as the local group. If the receiving system is not running as the super-user, only groups that the receiver is a member of will be preserved (by group name, not group id number).

-D, --devices

transfers character and block device information to the remote system to recreate these devices. This option is only available to the super-user.

-t, --times

transfers modification times along with the files and updates them on the remote system.

-n, --dry-run

does not perform any file transfers, but simply reports the actions it would have taken.

-x, --one-file-system

does not cross filesystem boundaries when recursing.

--existing

does not create any new files - only updates files that already exist on the destination.

--max-delete=NUM

does not delete more than NUM files or directories.

--delete

deletes any files on the receiving side that are not on the sending side. Files that are excluded from transfer are excluded from being deleted unless --delete-excluded is specified.

has no effect if directory recursion is not selected.

--delete-excluded

deletes any files on the receiving side that are excluded, in addition to deleting the files on the receiving side that are not on the sending side. (See --exclude.)

--delete-after

processes file deletions after transferring files, as opposed to the default behavior of deleting before the transfer to ensure that there is sufficient space on the receiving filesystem.

-B, --block-size=BLOCKSIZE

controls the block size used in the rsync algorithm. See the technical report for details.

-e, --rsh=COMMAND

specifies the remote shell program to use for communication between the local and remote copies of rsync.

You can also choose the remote shell program using the RSYNC_RSH environment variable.

--rsync-path=PATH

specifies the path to the copy of rsync on the remote machine. Note that this is the full path to the binary, not just the directory that the binary is in.

--exclude=PATTERN

selectively excludes certain files from the list of files to be transferred.

You may use as many --exclude options on the command line as you like to build up the list of files to exclude.

--exclude-from=FILE

is like the --exclude option, but instead adds all exclude patterns listed in the file FILE to the exclude list. Blank lines in FILE and lines starting with ; or # are ignored.

--include=PATTERN

does not exclude the specified pattern of filenames. This is useful as it allows you to build up quite complex exclude/include rules.

--include-from=FILE

specifies a list of include patterns from a file.

-T, --temp-dir=DIR

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 the temporary files in the receiving directory.

-z, --compress

compresses any data from the source file(s) that it sends to the destination machine.

--numeric-ids

transfers numeric group and user ids rather than using user and group names and mapping them at both ends.

By default rsync will use the user name and group name to determine what ownership to give files. The special uid 0 and the special group 0 are never mapped via user/group names even if --numeric-ids is not specified.

--timeout=TIMEOUT

sets a maximum IO timeout in seconds. If no data is transferred for the specified time, rsync will exit. The default is 0, which means no timeout.

--port=PORT

specifies an alternate TCP port number to use rather than the default port 873. This only has effect when using rsync to connect to a remote rsync daemon.

--blocking-io

specifies whether rsync will use blocking IO when launching a remote shell transport. You may find this is needed for some remote shells that cant handle the default non-blocking IO.

--partial

keeps any partially-transferred file in the event of an incomplete transfer (causing a subsequent transfer of the file remainder to process more rapidly) as opposed to the default behavior of rsync where an incomplete file is deleted.

--progress

prints information showing the progress of the transfer.

-P

is equivalent to --partial --progress.

--password-file

allows you to provide a password in a file for accessing a remote rsync server. Note that this option is only useful when accessing a rsync server using the built in transport, not when using a remote shell as the transport. The file must not be world readable. It should contain just the password as a single line.

--bwlimit=KBPS

specifies a maximum transfer rate in kilobytes per second. A value of zero specifies no limit.