Rsync

rsync is a fast and extraordinarily versatile file copying tool. It can copy locally, to/from another host over any remote shell, or to/from a remote rsync daemon. It offers a large number of options that control every aspect of its behavior and permit very flexible specification of the set of files to be copied. It is famous for its delta-transfer algorithm, which reduces the amount of data sent over the network by sending only the differences between the source files and the existing files in the destination. Rsync is widely used for backups and mirroring and as an improved copy command for everyday use.

rsync finds files that need to be transferred using a lqquick checkrq algorithm (by default) that looks for files that have changed in size or in last-modified time. Any changes in the other preserved attributes (as requested by options) are made on the destination file directly when the quick check indicates that the file's data does not need to be updated.

General

rsync copies files either to or from a remote host, or locally on the current host (it does not support copying files between two remote hosts).

There are two different ways for rsync to contact a remote system: using a remote-shell program as the transport (such as ssh or rsh) or contacting an rsync daemon directly via TCP. The remote-shell transport is used whenever the source or destination path contains a single colon (:) separator after a host specification. Contacting an rsync daemon directly happens when the source or destination path contains a double colon (::) separator after a host specification, OR when an rsync:// URL is specified (see also the lqUSING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTIONrq section for an exception to this latter rule).

As a special case, if a single source arg is specified without a destination, the files are listed in an output format similar to lqls -lrq.

As expected, if neither the source or destination path specify a remote host, the copy occurs locally (see also the --list-only option).

rsync refers to the local side as the lqclientrq and the remote side as the lqserverrq. Don't confuse lqserverrq with an rsync daemon -- a daemon is always a server, but a server can be either a daemon or a remote-shell spawned process.

Usage

You use rsync in the same way you use rcp. You must specify a source and a destination, one of which may be remote.

Perhaps the best way to explain the syntax is with some examples:

    rsync -t *.c foo:src/

This would transfer all files matching the pattern *.c from the current directory to the directory src on the machine foo. If any of the files already exist on the remote system then the rsync remote-update protocol is used to update the file by sending only the differences. See the tech report for details.

    rsync -avz foo:src/bar /data/tmp

This would recursively transfer all files from the directory src/bar on the machine foo into the /data/tmp/bar directory on the local machine. The files are transferred in lqarchiverq mode, which ensures that symbolic links, devices, attributes, permissions, ownerships, etc. are preserved in the transfer. Additionally, compression will be used to reduce the size of data portions of the transfer.

    rsync -avz foo:src/bar/ /data/tmp

A trailing slash on the source changes this behavior to avoid creating an additional directory level at the destination. You can think of a trailing / on a source as meaning lqcopy the contents of this directoryrq as opposed to lqcopy the directory by namerq, but in both cases the attributes of the containing directory are transferred to the containing directory on the destination. In other words, each of the following commands copies the files in the same way, including their setting of the attributes of /dest/foo:

    rsync -av /src/foo /dest
    rsync -av /src/foo/ /dest/foo

Note also that host and module references don't require a trailing slash to copy the contents of the default directory. For example, both of these copy the remote directory's contents into lq/destrq:

    rsync -av host: /dest
    rsync -av host::module /dest

You can also use rsync in local-only mode, where both the source and destination don't have a oq:cq in the name. In this case it behaves like an improved copy command.

Finally, you can list all the (listable) modules available from a particular rsync daemon by leaving off the module name:

    rsync somehost.mydomain.com::

See the following section for more details.

Advanced Usage

The syntax for requesting multiple files from a remote host is done by specifying additional remote-host args in the same style as the first, or with the hostname omitted. For instance, all these work:

    rsync -av host:file1 :file2 host:file{3,4} /dest/
    rsync -av host::modname/file{1,2} host::modname/file3 /dest/
    rsync -av host::modname/file1 ::modname/file{3,4}

Older versions of rsync required using quoted spaces in the SRC, like these examples:

    rsync -av host:'dir1/file1 dir2/file2' /dest
    rsync host::'modname/dir1/file1 modname/dir2/file2' /dest

This word-splitting still works (by default) in the latest rsync, but is not as easy to use as the first method.

If you need to transfer a filename that contains whitespace, you can either specify the --protect-args (-s) option, or you'll need to escape the whitespace in a way that the remote shell will understand. For instance:

    rsync -av host:'file\ name\ with\ spaces' /dest

You can also rsync over ssh.

   rsync -avzP -e 'ssh -p 22' docrootfrom user@example.com:docrootdest