mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(6 Nov 2006)()()
-manpagename(rsync)(faster, flexible replacement for rcp)
+manpage(rsync)(1)(11 Oct 2007)()()
+manpagename(rsync)(a fast, versatile, remote (and local) file-copying tool)
manpagesynopsis()
-rsync [OPTION]... SRC [SRC]... DEST
+verb(Local: rsync [OPTION...] SRC... [DEST]
-rsync [OPTION]... SRC [SRC]... [USER@]HOST:DEST
+Access via remote shell:
+ Pull: rsync [OPTION...] [USER@]HOST:SRC... [DEST]
+ Push: rsync [OPTION...] SRC... [USER@]HOST:DEST
-rsync [OPTION]... SRC [SRC]... [USER@]HOST::DEST
+Access via rsync daemon:
+ Pull: rsync [OPTION...] [USER@]HOST::SRC... [DEST]
+ rsync [OPTION...] rsync://[USER@]HOST[:PORT]/SRC... [DEST]
+ Push: rsync [OPTION...] SRC... [USER@]HOST::DEST
+ rsync [OPTION...] SRC... rsync://[USER@]HOST[:PORT]/DEST)
-rsync [OPTION]... SRC [SRC]... rsync://[USER@]HOST[:PORT]/DEST
-
-rsync [OPTION]... SRC
-
-rsync [OPTION]... [USER@]HOST:SRC [DEST]
-
-rsync [OPTION]... [USER@]HOST::SRC [DEST]
-
-rsync [OPTION]... rsync://[USER@]HOST[:PORT]/SRC [DEST]
+Usages with just one SRC arg and no DEST arg will list the source files
+instead of copying.
manpagedescription()
-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 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
-an efficient checksum-search algorithm described in the technical
-report that accompanies this package.
-
-Rsync finds files that need to be transferred using a "quick check" algorithm
-that looks for files that have changed in size or in last-modified time (by
-default). 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.
+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 "quick check"
+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.
Some of the additional features of rsync are:
manpagesection(ADVANCED USAGE)
-The syntax for requesting multiple files from a remote host involves using
-quoted spaces in the SRC. Some examples:
+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:
-quote(tt(rsync host::'modname/dir1/file1 modname/dir2/file2' /dest))
+quote(tt(rsync -av host:file1 :file2 host:file{3,4} /dest/)nl()
+tt(rsync -av host::modname/file{1,2} host::modname/file3 /dest/)nl()
+tt(rsync -av host::modname/file1 ::modname/file{3,4}))
-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.
+Older versions of rsync required using quoted spaces in the SRC, like these
+examples:
-quote(tt(rsync -av host:'dir1/file1 dir2/file2' /dest))
+quote(tt(rsync -av host:'dir1/file1 dir2/file2' /dest)nl()
+tt(rsync host::'modname/dir1/file1 modname/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:
+This word-splitting still works (by default) in the latest rsync, but is
+not as easy to use as the first method.
-quote(
-tt(rsync -av host:'file\ name\ with\ spaces' /dest)nl()
-tt(rsync -av host:file?name?with?spaces /dest)nl()
-)
+If you need to transfer a filename that contains whitespace, you can either
+specify the bf(--protect-args) (bf(-s)) option, or you'll need to escape
+the whitespace in a way that the remote shell will understand. For
+instance:
-This latter example assumes that your shell passes through unmatched
-wildcards. If it complains about "no match", put the name in quotes.
+quote(tt(rsync -av host:'file\ name\ with\ spaces' /dest))
manpagesection(CONNECTING TO AN RSYNC DAEMON)
output a message to that effect for each one). If you specify both
bf(--dirs) and bf(--recursive), bf(--recursive) takes precedence.
+This option is implied by the bf(--list-only) option (including an implied
+bf(--list-only) usage) if bf(--recursive) wasn't specified (so that
+directories are seen in the listing). Specify bf(--no-dirs) (or bf(--no-d))
+if you want to override this. This option is also implied by
+bf(--files-from).
+
dit(bf(-l, --links)) When symlinks are encountered, recreate the
symlink on the destination.
was enabled. Beginning with 2.6.7, deletions will also occur when bf(--dirs)
(bf(-d)) is enabled, but only for directories whose contents are being copied.
-This option can be dangerous if used incorrectly! It is a very good idea
-to run first using the bf(--dry-run) option (bf(-n)) to see what files would be
-deleted to make sure important files aren't listed.
+This option can be dangerous if used incorrectly! It is a very good idea to
+first try a run using the bf(--dry-run) option (bf(-n)) to see what files are
+going to be deleted.
If the sending side detects any I/O errors, then the deletion of any
files at the destination will be automatically disabled. This is to
instead of transferred. This option is inferred if there is a single source
arg and no destination specified, so its main uses are: (1) to turn a copy
command that includes a
-destination arg into a file-listing command, (2) to be able to specify more
-than one local source arg (note: be sure to include the destination), or
-(3) to avoid the automatically added "bf(-r --exclude='/*/*')" options that
-rsync usually uses as a compatibility kluge when generating a non-recursive
-listing. Caution: keep in mind that a source arg with a wild-card is expanded
-by the shell into multiple args, so it is never safe to try to list such an arg
+destination arg into a file-listing command, or (2) to be able to specify
+more than one source arg (note: be sure to include the destination).
+Caution: keep in mind that a source arg with a wild-card is expanded by the
+shell into multiple args, so it is never safe to try to list such an arg
without using this option. For example:
verb( rsync -av --list-only foo* dest/)
+Compatibility note: when requesting a remote listing of files from an rsync
+that is version 2.6.3 or older, you may encounter an error if you ask for a
+non-recursive listing. This is because a file listing implies the bf(--dirs)
+option w/o bf(--recursive), and older rsyncs don't have that option. To
+avoid this problem, either specify the bf(--no-dirs) option (if you don't
+need to expand a directory's content), or turn on recursion and exclude
+the content of subdirectories: bf(-r --exclude='/*/*').
+
dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum
transfer rate in kilobytes per second. This option is most effective when
using rsync with large files (several megabytes and up). Due to the nature
manpagesection(VERSION)
-This man page is current for version 2.6.9 of rsync.
+This man page is current for version 3.0.0pre2 of rsync.
manpagesection(INTERNAL OPTIONS)
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff