mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(15 Mar 2005)()()
+manpage(rsync)(1)(30 Mar 2005)()()
manpagename(rsync)(faster, flexible replacement for rcp)
manpagesynopsis()
tt(rsync -av /src/foo/ /dest/foo)nl()
)
+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 "/dest":
+
+quote(
+tt(rsync -av host: /dest)nl()
+tt(rsync -av host::module /dest)nl()
+)
+
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
an improved copy command.
--include=PATTERN don't exclude files matching PATTERN
--include-from=FILE read include patterns from FILE
--files-from=FILE read list of source-file names from FILE
- -0, --from0 all *from file lists are delimited by nulls
- --version print version number
+ -0, --from0 all *from/filter files are delimited by 0s
+ --address=ADDRESS bind address for outgoing socket to daemon
--port=PORT specify double-colon alternate port number
--blocking-io use blocking I/O for the remote shell
--no-blocking-io turn off blocking I/O when it is default
--progress show progress during transfer
-P same as --partial --progress
-i, --itemize-changes output a change-summary for all updates
- --log-format=FORMAT log file-transfers using specified format
+ --log-format=FORMAT output filenames using the specified format
--password-file=FILE read password from FILE
--list-only list the files instead of copying them
--bwlimit=KBPS limit I/O bandwidth; KBytes per second
--write-batch=FILE write a batched update to FILE
+ --only-write-batch=FILE like --write-batch but w/o updating dest
--read-batch=FILE read a batched update from FILE
--protocol=NUM force an older protocol version to be used
--checksum-seed=NUM set block/file checksum seed (advanced)
-4, --ipv4 prefer IPv4
-6, --ipv6 prefer IPv6
+ --version print version number
-h, --help show this help screen)
Rsync can also be run as a daemon, in which case the following options are
Note that the names of the transferred files that are output are done using
a default bf(--log-format) of "%n%L", which tells you just the name of the
-file and, if the item is a symlink, where it points. At the single bf(-v)
+file and, if the item is a link, where it points. At the single bf(-v)
level of verbosity, this does not mention when a file gets its attributes
changed. If you ask for an itemized list of changed attributes (either
bf(--itemize-changes) or adding "%i" to the bf(--log-format) setting), the
dit(bf(-p, --perms)) This option causes rsync to set the destination
permissions to be the same as the source permissions.
-Without this option, each new file gets its permissions set based on the
-source file's permissions and the umask at the receiving end, while all
-other files (including updated files) retain their existing permissions
+Without this option, all existing files (including updated files) retain
+their existing permissions, while each new file gets its permissions set
+based on the source file's permissions, but masked by the receiving end's
+umask setting
(which is the same behavior as other file-copy utilities, such as cp).
dit(bf(-o, --owner)) This option causes rsync to set the owner of the
This would copy all the files specified in the /path/file-list file that
was located on the remote "src" host.
-dit(bf(-0, --from0)) This tells rsync that the filenames it reads from a
+dit(bf(-0, --from0)) This tells rsync that the rules/filenames it reads from a
file are terminated by a null ('\0') character, not a NL, CR, or CR+LF.
This affects bf(--exclude-from), bf(--include-from), bf(--files-from), and any
merged files specified in a bf(--filter) rule.
timeout in seconds. If no data is transferred for the specified time
then rsync will exit. The default is 0, which means no timeout.
+dit(bf(--address)) By default rsync will bind to the wildcard address when
+connecting to an rsync daemon. The bf(--address) option allows you to
+specify a specific IP address (or hostname) to bind to. See also this
+option in the bf(--daemon) mode section.
+
dit(bf(--port=PORT)) This specifies an alternate TCP port number to use
rather than the default of 873. This is only needed if you are using the
double-colon (::) syntax to connect with an rsync daemon (since the URL
(sent).
it() A bf(>) means that a file is being transferred to the local host
(received).
- it() A bf(c) means that a local change/creation is occuring for the item
+ it() A bf(c) means that a local change/creation is occurring for the item
(such as the creation of a directory or the changing of a symlink, etc.).
it() A bf(h) means that the item is a hard-link to another item (requires
bf(--hard-links)).
))
The file-types that replace the bf(X) are: bf(f) for a file, a bf(d) for a
-dir, an bf(L) for a symlink, and a bf(D) for a device.
+directory, an bf(L) for a symlink, and a bf(D) for a device.
The other letters in the string above are the actual letters that
will be output if the associated attribute for the item is being updated or
a "." for no change. Three exceptions to this are: (1) a newly created
-item replaces each letter with a "+", (2) an identical item replaces each
-letter with a space, and (3) an unknown attribute replaces each letter with
-a "?" (this happens when talking to an older rsync).
+item replaces each letter with a "+", (2) an identical item replaces the
+dots with spaces, and (3) an unknown attribute replaces each letter with
+a "?" (this can happen when talking to an older rsync).
The attribute that is associated with each letter is as follows:
quote(itemize(
it() A bf(c) means the checksum of the file is different and will be
- updated by the file transfer (requries bf(--checksum)).
+ updated by the file transfer (requires bf(--checksum)).
it() A bf(s) means the size of the file is different and will be updated
by the file transfer.
it() A bf(t) means the modification time is different and is being updated
in a significant way (a transferred file, a recreated symlink/device, or a
touched directory) unless the itemized-changes escape (%i) is included in
the string, in which case the logging of names increases to mention any
-item that is updated in any way (as long as the receiving side is version
+item that is changed in any way (as long as the receiving side is at least
2.6.4). See the bf(--itemized-changes) option for a description of the
output of "%i".
dit(bf(--write-batch=FILE)) Record a file that can later be applied to
another identical destination with bf(--read-batch). See the "BATCH MODE"
-section for details.
+section for details, and also the bf(--only-write-batch) option.
+
+dit(bf(--only-write-batch=FILE)) Works like bf(--write-batch), except that
+no updates are made on the destination system when creating the batch.
+This lets you transport the changes to the destination system via some
+other means and then apply the changes via bf(--read-batch).
+
+Note that you can feel free to write the batch directly to some portable
+media: if this media fills to capacity before the end of the transfer, you
+can just apply that partial transfer to the destination and repeat the
+whole process to get the rest of the changes (as long as you don't mind a
+partially updated destination system while the multi-update cycle is
+happening).
+
+Also note that you only save bandwidth when pushing changes to a remote
+system because this allows the batched data to be diverted from the sender
+into the batch file without having to flow over the wire to the receiver
+(when pulling, the sender is remote, and thus can't write the batch).
dit(bf(--read-batch=FILE)) Apply all of the changes stored in FILE, a
file previously generated by bf(--write-batch).
is useful for creating a batch file that is compatible with an older
version of rsync. For instance, if rsync 2.6.4 is being used with the
bf(--write-batch) option, but rsync 2.6.3 is what will be used to run the
-bf(--read-batch) option, you should use "--protocol=28" (when creating the
-batch file) to force the older protocol version to be used in the batch
-file (assuming you can't upgrade the rsync on the reading system to 2.6.4).
+bf(--read-batch) option, you should use "--protocol=28" when creating the
+batch file to force the older protocol version to be used in the batch
+file (assuming you can't upgrade the rsync on the reading system).
dit(bf(-4, --ipv4) or bf(-6, --ipv6)) Tells rsync to prefer IPv4/IPv6
when creating sockets. This only affects sockets that rsync has direct
requests accordingly. See the rsyncd.conf(5) man page for more
details.
-dit(bf(--address)) By default rsync will bind to the wildcard address
-when run as a daemon with the bf(--daemon) option or when connecting to a
-rsync server. The bf(--address) option allows you to specify a specific IP
-address (or hostname) to bind to. This makes virtual hosting possible
-in conjunction with the bf(--config) option. See also the "address" global
-option in the rsyncd.conf manpage.
+dit(bf(--address)) By default rsync will bind to the wildcard address when
+run as a daemon with the bf(--daemon) option. The bf(--address) option
+allows you to specify a specific IP address (or hostname) to bind to. This
+makes virtual hosting possible in conjunction with the bf(--config) option.
+See also the "address" global option in the rsyncd.conf manpage.
dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum
transfer rate in kilobytes per second for the data the daemon sends.