mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(22 Apr 2006)()()
+manpage(rsync)(1)(26 Oct 2006)()()
manpagename(rsync)(faster, flexible replacement for rcp)
manpagesynopsis()
Some of the additional features of rsync are:
-itemize(
+itemization(
it() support for copying links, devices, owners, groups, and permissions
it() exclude and exclude-from options similar to GNU tar
it() a CVS exclude mode for ignoring the same files that CVS would ignore
Using rsync in this way is the same as using it with a remote shell except
that:
-itemize(
+itemization(
it() you either use a double colon :: instead of a single colon to
separate the hostname from the path, or you use an rsync:// URL.
it() the first word of the "path" is actually a module name.
to the detailed description below for a complete description. verb(
-v, --verbose increase verbosity
-q, --quiet suppress non-error messages
+ --no-motd suppress daemon-mode MOTD (see caveat)
-c, --checksum skip based on checksum, not mod-time & size
-a, --archive archive mode; same as -rlptgoD (no -H)
--no-OPTION turn off an implied OPTION (e.g. --no-D)
-H, --hard-links preserve hard links
-p, --perms preserve permissions
-E, --executability preserve executability
- --chmod=CHMOD change destination permissions
+ --chmod=CHMOD affect file and/or directory permissions
-o, --owner preserve owner (super-user only)
-g, --group preserve group
--devices preserve device files (super-user only)
-B, --block-size=SIZE force a fixed checksum block-size
-e, --rsh=COMMAND specify the remote shell to use
--rsync-path=PROGRAM specify the rsync to run on remote machine
- --existing ignore non-existing files on receiving side
- --ignore-existing ignore files that already exist on receiver
- --remove-sent-files sent files/symlinks are removed from sender
+ --existing skip creating new files on receiver
+ --ignore-existing skip updating files that exist on receiver
+ --remove-source-files sender removes synchronized files (non-dir)
--del an alias for --delete-during
- --delete delete files that don't exist on sender
+ --delete delete extraneous files from dest dirs
--delete-before receiver deletes before transfer (default)
--delete-during receiver deletes during xfer, not before
--delete-after receiver deletes after transfer, not before
- --delete-excluded also delete excluded files on receiver
+ --delete-excluded also delete excluded files from dest dirs
--ignore-errors delete even if there are I/O errors
--force force deletion of dirs even if not empty
--max-delete=NUM don't delete more than NUM files
--progress show progress during transfer
-P same as --partial --progress
-i, --itemize-changes output a change-summary for all updates
- --log-format=FORMAT output filenames using the specified format
+ --out-format=FORMAT output updates using the specified FORMAT
+ --log-file=FILE log what we're doing to the specified FILE
+ --log-file-format=FMT log updates using the specified FMT
--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
-4, --ipv4 prefer IPv4
-6, --ipv6 prefer IPv6
--version print version number
-(-h) --help show this help (see below for -h comment)
-)
+(-h) --help show this help (see below for -h comment))
Rsync can also be run as a daemon, in which case the following options are
accepted: verb(
--config=FILE specify alternate rsyncd.conf file
--no-detach do not detach from the parent
--port=PORT listen on alternate port number
+ --log-file=FILE override the "log file" setting
+ --log-file-format=FMT override the "log format" setting
--sockopts=OPTIONS specify custom TCP options
-v, --verbose increase verbosity
-4, --ipv4 prefer IPv4
-6, --ipv6 prefer IPv6
- -h, --help show this help (if used after --daemon)
-)
+ -h, --help show this help (if used after --daemon))
manpageoptions()
you are debugging rsync.
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
+a default bf(--out-format) of "%n%L", which tells you just the name of the
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
+bf(--itemize-changes) or adding "%i" to the bf(--out-format) setting), the
output (on the client) increases to mention all items that are changed in
-any way. See the bf(--log-format) option for more details.
+any way. See the bf(--out-format) option for more details.
dit(bf(-q, --quiet)) This option decreases the amount of information you
are given during the transfer, notably suppressing information messages
from the remote server. This flag is useful when invoking rsync from
cron.
+dit(bf(--no-motd)) This option affects the information that is output
+by the client at the start of a daemon transfer. This suppresses the
+message-of-the-day (MOTD) text, but it also affects the list of modules
+that the daemon sends in response to the "rsync host::" request (due to
+a limitation in the rsync protocol), so omit this option if you want to
+request the list of modules from the deamon.
+
dit(bf(-I, --ignore-times)) Normally rsync will skip any files that are
already the same size and have the same modification time-stamp.
-This option turns off this "quick check" behavior.
+This option turns off this "quick check" behavior, causing all files to
+be updated.
dit(bf(--size-only)) Normally rsync will not transfer any files that are
already the same size and have the same modification time-stamp. With the
rule would never be reached).
dit(bf(--backup-dir=DIR)) In combination with the bf(--backup) option, this
-tells rsync to store all backups in the specified directory. This is
-very useful for incremental backups. You can additionally
+tells rsync to store all backups in the specified directory on the receiving
+side. This can be used for incremental backups. You can additionally
specify a backup suffix using the bf(--suffix) option
(otherwise the files backed up in the specified directory
will keep their original filenames).
When this option is em(off), permissions are set as follows:
-quote(itemize(
+quote(itemization(
it() Existing files (including updated files) retain their existing
permissions, though the bf(--executability) option might change just
the execute permission for the file.
executability differs from that of the corresponding source file, rsync
modifies the destination file's permissions as follows:
-quote(itemize(
+quote(itemization(
it() To make a file non-executable, rsync turns off all its 'x'
permissions.
it() To make a file executable, rsync turns on each 'x' permission that
by this option.
dit(bf(--existing, --ignore-non-existing)) This tells rsync to skip
-updating files that do not exist yet on the destination. If this option is
+creating files (including directories) that do not exist
+yet on the destination. If this option is
combined with the bf(--ignore-existing) option, no files will be updated
-(which can be useful if all you want to do is to delete missing files).
+(which can be useful if all you want to do is to delete extraneous files).
dit(bf(--ignore-existing)) This tells rsync to skip updating files that
-already exist on the destination. See also bf(--ignore-non-existing).
+already exist on the destination (this does em(not) ignore existing
+directores, or nothing would get done). See also bf(--existing).
-dit(bf(--remove-sent-files)) This tells rsync to remove from the sending
-side the files and/or symlinks that are newly created or whose content is
-updated on the receiving side. Directories and devices are not removed,
-nor are files/symlinks whose attributes are merely changed.
+dit(bf(--remove-source-files)) This tells rsync to remove from the sending
+side the files (meaning non-directories) that are a part of the transfer
+and have been successfully duplicated on the receiving side.
dit(bf(--delete)) This tells rsync to delete extraneous files from the
receiving side (ones that aren't on the sending side), but only for the
for standard input). It also tweaks the default behavior of rsync to make
transferring just the specified files and directories easier:
-quote(itemize(
+quote(itemization(
it() The bf(--relative) (bf(-R)) option is implied, which preserves the path
information that is specified for each item in the file (use
bf(--no-relative) or bf(--no-R) if you want to turn that off).
If a match is not found, a basis file from one of the em(DIR)s will be
selected to try to speed up the transfer.
+Note that if you combine this option with bf(--ignore-times), rsync will not
+link any files together because it only links identical files together as a
+substitute for transferring the file, never as an additional check after the
+file is updated.
+
If em(DIR) is a relative path, it is relative to the destination directory.
See also bf(--compare-dest) and bf(--copy-dest).
dit(bf(-i, --itemize-changes)) Requests a simple itemized list of the
changes that are being made to each file, including attribute changes.
-This is exactly the same as specifying bf(--log-format='%i %n%L').
+This is exactly the same as specifying bf(--out-format='%i %n%L').
If you repeat the option, unchanged files will also be output, but only
if the receiving rsync is at least version 2.6.7 (you can use bf(-vv)
with older versions of rsync, but that also turns on the output of other
The update types that replace the bf(Y) are as follows:
-quote(itemize(
+quote(itemization(
it() A bf(<) means that a file is being transferred to the remote host
(sent).
it() A bf(>) means that a file is being transferred to the local host
The attribute that is associated with each letter is as follows:
-quote(itemize(
+quote(itemization(
it() A bf(c) means the checksum of the file is different and will be
updated by the file transfer (requires bf(--checksum)).
it() A bf(s) means the size of the file is different and will be updated
you are talking to a recent enough rsync that it logs deletions instead of
outputting them as a verbose message).
-dit(bf(--log-format=FORMAT)) This allows you to specify exactly what the
-rsync client outputs to the user on a per-file basis. The format is a text
+dit(bf(--out-format=FORMAT)) This allows you to specify exactly what the
+rsync client outputs to the user on a per-update basis. The format is a text
string containing embedded single-character escape sequences prefixed with
a percent (%) character. For a list of the possible escape characters, see
-the "log format" setting in the rsyncd.conf manpage. (Note that this
-option does not affect what a daemon logs to its logfile.)
+the "log format" setting in the rsyncd.conf manpage.
Specifying this option will mention each file, dir, etc. that gets updated
in a significant way (a transferred file, a recreated symlink/device, or a
-touched directory) unless the itemize-changes escape (%i) is included in
-the string, in which case the logging of names increases to mention any
+touched directory). In addition, if the itemize-changes escape (%i) is
+included in the string, the logging of names increases to mention any
item that is changed in any way (as long as the receiving side is at least
2.6.4). See the bf(--itemize-changes) option for a description of the
output of "%i".
The bf(--verbose) option implies a format of "%n%L", but you can use
-bf(--log-format) without bf(--verbose) if you like, or you can override
+bf(--out-format) without bf(--verbose) if you like, or you can override
the format of its per-file output using this option.
-Rsync will output the log-format string prior to a file's transfer unless
+Rsync will output the out-format string prior to a file's transfer unless
one of the transfer-statistic escapes is requested, in which case the
logging is done at the end of the file's transfer. When this late logging
is in effect and bf(--progress) is also specified, rsync will also output
the name of the file being transferred prior to its progress information
-(followed, of course, by the log-format output).
+(followed, of course, by the out-format output).
+
+dit(bf(--log-file=FILE)) This option causes rsync to log what it is doing
+to a file. This is similar to the logging that a daemon does, but can be
+requested for the client side and/or the server side of a non-daemon
+transfer. If specified as a client option, transfer logging will be
+enabled with a default format of "%i %n%L". See the bf(--log-file-format)
+option if you wish to override this.
+
+Here's a example command that requests the remote side to log what is
+happening:
+
+verb( rsync -av --rsync-path="rsync --log-file=/tmp/rlog" src/ dest/)
+
+This is very useful if you need to debug why a connection is closing
+unexpectedly.
+
+dit(bf(--log-file-format=FORMAT)) This allows you to specify exactly what
+per-update logging is put into the file specified by the bf(--log-file) option
+(which must also be specified for this option to have any effect). If you
+specify an empty string, updated files will not be mentioned in the log file.
+For a list of the possible escape characters, see the "log format" setting
+in the rsyncd.conf manpage.
dit(bf(--stats)) This tells rsync to print a verbose set of statistics
on the file transfer, allowing you to tell how effective the rsync
algorithm is for your data.
-The current statistics are as follows: quote(itemize(
+The current statistics are as follows: quote(itemization(
it() bf(Number of files) is the count of all "files" (in the generic
sense), which includes directories, symlinks, etc.
it() bf(Number of files transferred) is the count of normal files that
something to watch.
Implies bf(--verbose) if it wasn't already specified.
-When the file is transferring, the data looks like this:
+While rsync is transferring a regular file, it updates a progress line that
+looks like this:
verb( 782448 63% 110.64kB/s 0:00:04)
-This tells you the current file size, the percentage of the transfer that
-is complete, the current calculated file-completion rate (including both
-data over the wire and data being matched locally), and the estimated time
-remaining in this transfer.
+In this example, the receiver has reconstructed 782448 bytes or 63% of the
+sender's file, which is being reconstructed at a rate of 110.64 kilobytes
+per second, and the transfer will finish in 4 seconds if the current rate
+is maintained until the end.
-After a file is complete, the data looks like this:
+These statistics can be misleading if the incremental transfer algorithm is
+in use. For example, if the sender's file consists of the basis file
+followed by additional data, the reported rate will probably drop
+dramatically when the receiver gets to the literal data, and the transfer
+will probably take much longer to finish than the receiver estimated as it
+was finishing the matched part of the file.
-verb( 1238099 100% 146.38kB/s 0:00:08 (5, 57.1% of 396))
+When the file transfer finishes, rsync replaces the progress line with a
+summary line that looks like this:
-This tells you the final file size, that it's 100% complete, the final
-transfer rate for the file, the amount of elapsed time it took to transfer
-the file, and the addition of a total-transfer summary in parentheses.
-These additional numbers tell you how many files have been updated, and
-what percent of the total number of files has been scanned.
+verb( 1238099 100% 146.38kB/s 0:00:08 (xfer#5, to-check=169/396))
+
+In this example, the file was 1238099 bytes long in total, the average rate
+of transfer for the whole file was 146.38 kilobytes per second over the 8
+seconds that it took to complete, it was the 5th transfer of a regular file
+during the current rsync session, and there are 169 more files for the
+receiver to check (to see if they are up-to-date or not) remaining out of
+the 396 total files in the file-list.
dit(bf(-P)) The bf(-P) option is equivalent to bf(--partial) bf(--progress). Its
purpose is to make it much easier to specify these two options for a long
daemon to listen on rather than the default of 873. See also the "port"
global option in the rsyncd.conf manpage.
+dit(bf(--log-file=FILE)) This option tells the rsync daemon to use the
+given log-file name instead of using the "log file" setting in the config
+file.
+
+dit(bf(--log-file-format=FORMAT)) This option tells the rsync daemon to use the
+given FORMAT string instead of using the "log format" setting in the config
+file. It also enables "transfer logging" unless the string is empty, in which
+case transfer logging is turned off.
+
dit(bf(--sockopts)) This overrides the bf(socket options) setting in the
rsyncd.conf file and has the same syntax.
the names of the files that are going to be transferred. These patterns
can take several forms:
-itemize(
+itemization(
it() if the pattern starts with a / then it is anchored to a
particular spot in the hierarchy of files, otherwise it is matched
against the end of the pathname. This is similar to a leading ^ in
Here are some examples of exclude/include matching:
-itemize(
+itemization(
it() "- *.o" would exclude all filenames matching *.o
it() "- /foo" would exclude a file (or directory) named foo in the
transfer-root directory
The following modifiers are accepted after a merge or dir-merge rule:
-itemize(
+itemization(
it() A bf(-) specifies that the file should consist of only exclude
patterns, with no other rule-parsing except for in-file comments.
it() A bf(+) specifies that the file should consist of only include
The following modifiers are accepted after a "+" or "-":
-itemize(
+itemization(
it() A "/" specifies that the include/exclude rule should be matched
against the absolute pathname of the current item. For example,
"-/ /etc/passwd" would exclude the passwd file any time the transfer
into the directory /bdest/dir. The differences between the two examples
reveals some of the flexibility you have in how you deal with batches:
-itemize(
+itemization(
it() The first example shows that the initial copy doesn't have to be
local -- you can push or pull data to/from a remote host using either the
remote-shell syntax or rsync daemon syntax, as desired.
manpagesection(VERSION)
-This man page is current for version 2.6.8 of rsync.
+This man page is current for version 2.6.9pre3 of rsync.
+
+manpagesection(INTERNAL OPTIONS)
+
+The options bf(--server) and bf(--sender) are used internally by rsync,
+and should never be typed by a user under normal circumstances. Some
+awareness of these options may be needed in certain scenarios, such as
+when setting up a login that can only run an rsync command. For instance,
+the support directory of the rsync distribution has an example script
+named rrsync (for restricted rsync) that can be used with a restricted
+ssh login.
manpagesection(CREDITS)