mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(30 Apr 2004)()()
+manpage(rsync)(1)(21 Sep 2004)()()
manpagename(rsync)(faster, flexible replacement for rcp)
manpagesynopsis()
rsync is a program that behaves in much the same way that rcp does,
but has many more options and uses the rsync remote-update protocol to
-greatly speed up file transfers when the destination file already
-exists.
+greatly speed up file transfers when the destination file is being
+updated.
The rsync remote-update protocol allows rsync to transfer just the
differences between two sets of files across the network connection, using
Perhaps the best way to explain the syntax is with some examples:
-quote(rsync *.c foo:src/)
+quote(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
files in the same way, including their setting of the attributes of
/dest/foo:
-quote(rsync -avz /src/foo /dest)
-quote(rsync -avz /src/foo/ /dest/foo)
+quote(rsync -av /src/foo /dest)
+quote(rsync -av /src/foo/ /dest/foo)
You can also use rsync in local-only mode, where both the source and
destination don't have a ':' in the name. In this case it behaves like
somehost.mydomain.com. (See the following section for more details.)
+manpagesection(ADVANCED USAGE)
+
+The syntax for requesting multiple files from a remote host involves using
+quoted spaces in the SRC. Some examples:
+
+quote(rsync host::'modname/dir1/file1 modname/dir2/file2' /dest)
+
+This would copy file1 and file2 into /dest from an rsync daemon. Each
+additional arg must include the same "modname/" prefix as the first one,
+and must be preceded by a single space. All other spaces are assumed
+to be a part of the filenames.
+
+quote(rsync -av host:'dir1/file1 dir2/file2' /dest)
+
+This would copy file1 and file2 into /dest using a remote shell. This
+word-splitting is done by the remote shell, so if it doesn't work it means
+that the remote shell isn't configured to split its args based on
+whitespace (a very rare setting, but not unknown). If you need to transfer
+a filename that contains whitespace, you'll need to either escape the
+whitespace in a way that the remote shell will understand, or use wildcards
+in place of the spaces. Two examples of this are:
+
+quote(rsync -av host:'file\ name\ with\ spaces' /dest)
+quote(rsync -av host:file?name?with?spaces /dest)
+
+This latter example assumes that your shell passes through unmatched
+wildcards. If it complains about "no match", put the name in quotes.
+
+
manpagesection(CONNECTING TO AN RSYNC SERVER)
It is also possible to use rsync without a remote shell as the
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, and all files will have
-their checksums compared and show up in log messages even if they haven't
-changed.
+cause the next transfer to behave as if it used -I, causing all files to be
+updated (though the rsync algorithm will make the update fairly efficient
+if the files haven't actually changed, you're much better off using -t).
dit(bf(-n, --dry-run)) This tells rsync to not do any file transfers,
instead it will just report the actions it would have taken.
This option increases the usefulness of --partial because partially
transferred files will remain in the new temporary destination until they
have a chance to be completed. If DIR is a relative path, it is relative
-to the destination directory (which changes in a recursive transfer).
+to the destination directory.
dit(bf(--link-dest=DIR)) This option behaves like bf(--compare-dest) but
also will create hard links from em(DIR) to the destination directory for
unchanged files. Files with changed ownership or permissions will not be
linked.
-Like bf(--compare-dest) if DIR is a relative path, it is relative
-to the destination directory (which changes in a recursive transfer).
An example:
verb(
rsync -av --link-dest=$PWD/prior_dir host:src_dir/ new_dir/
)
+Like bf(--compare-dest) if DIR is a relative path, it is relative to the
+destination directory.
+Note that rsync versions prior to 2.6.1 had a bug that could prevent
+--link-dest from working properly for a non-root user when -o was specified
+(or implied by -a). If the receiving rsync is not new enough, you can work
+around this bug by avoiding the -o option.
+
dit(bf(-z, --compress)) With this option, rsync compresses any data from
the files that it sends to the destination machine. This
option is useful on slow connections. The compression method used is the
file to the destination dir. Rsync will also use a file found in this
dir as data to speed up the transfer (i.e. when you redo the send after
rsync creates a partial file) and delete such a file after it has served
-its purpose.
+its purpose. Note that if --whole-file is specified (or implied) that an
+existing partial-dir file will not be used to speedup the transfer (since
+rsync is sending files without using the incremental rsync algorithm).
Rsync will create the dir if it is missing (just the last dir -- not the
whole path). This makes it easy to use a relative path (such as
end of the transfer when using --delete-after, or at the beginning of the
transfer when using --delete). E.g. "--exclude=.rsync-partial/".
-IMPORTANT: the --partial-dir should not be writable by other users to
-avoid a security risk. E.g. AVOID "/tmp".
+IMPORTANT: the --partial-dir should not be writable by other users or it
+is a security risk. E.g. AVOID "/tmp".
+
+You can also set the partial-dir value the RSYNC_PARTIAL_DIR environment
+variable. Setting this in the environment does not force --partial to be
+enabled, but rather it effects where partial files go when --partial (or
+-P) is used. For instance, instead of specifying --partial-dir=.rsync-tmp
+along with --progress, you could set RSYNC_PARTIAL_DIR=.rsync-tmp in your
+environment and then just use the -P option to turn on the use of the
+.rsync-tmp dir for partial transfers. The only time the --partial option
+does not look for this environment value is when --inplace was also
+specified (since --inplace conflicts with --partial-dir).
dit(bf(--progress)) This option tells rsync to print information
showing the progress of the transfer. This gives a bored user
appears to be up-to-date already) or the file-update may be attempted
and then, if the file fails to verify, the update discarded with an
error. This means that it should be safe to re-run a read-batch operation
-if the command got updated. If you wish to force the batched-update to
+if the command got interrupted. If you wish to force the batched-update to
always be attempted regardless of the file's size and date, use the -I
-option. If an error occurs, the destination tree will probably be in a
+option (when reading the batch).
+If an error occurs, the destination tree will probably be in a
partially updated state. In that case, rsync can
be used in its regular (non-batch) mode of operation to fix up the
destination tree.
The rsync version used on all destinations must be at least as new as the
-one used to generate the batch file.
+one used to generate the batch file. Rsync will die with an error if the
+protocol version in the batch file is too new for the batch-reading rsync
+to handle.
The --dry-run (-n) option does not work in batch mode and yields a runtime
error.
user can ignore this detail and just use the shell script as an easy way
to run the appropriate --read-batch command for the batched data.
-See bf(http://www.ils.unc.edu/i2dsi/unc_rsync+.html) for papers and technical
-reports.
+The original batch mode in rsync was based on "rsync+", but the latest
+version uses a new implementation.
manpagesection(SYMBOLIC LINKS)
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff