mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(22 Jun 2008)()()
+manpage(rsync)(1)(29 Jun 2008)()()
manpagename(rsync)(a fast, versatile, remote (and local) file-copying tool)
manpagesynopsis()
Here is a short summary of the options available in rsync. Please refer
to the detailed description below for a complete description. verb(
-v, --verbose increase verbosity
+ --info=FLAGS fine-grained informational verbosity
+ --debug=FLAGS fine-grained debug 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
--progress show progress during transfer
-P same as --partial --progress
-i, --itemize-changes output a change-summary for all updates
+ -M, --remote-option=OPTION send OPTION to the remote side only
--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
dit(bf(-v, --verbose)) This option increases the amount of information you
are given during the transfer. By default, rsync works silently. A
single bf(-v) will give you information about what files are being
-transferred and a brief summary at the end. Two bf(-v) flags will give you
+transferred and a brief summary at the end. Two bf(-v) options will give you
information on what files are being skipped and slightly more
-information at the end. More than two bf(-v) flags should only be used if
+information at the end. More than two bf(-v) options should only be used if
you are debugging rsync.
-Note that the names of the transferred files that are output are done using
-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(--out-format) setting), the
-output (on the client) increases to mention all items that are changed in
-any way. See the bf(--out-format) option for more details.
+In a modern rsync, the bf(-v) option is equivalent to the setting of groups
+of bf(--info) and bf(--debug) options. You can choose to use these newer
+options in addition to, or in place of using bf(--verbose), as any
+fine-grained settings override the implied settings of bf(-v). Both
+bf(--info) and bf(--debug) have a way to ask for help that tells you
+exactly what flags are set for each increase in verbosity.
+
+dit(bf(--info=FLAGS))
+This option lets you have fine-grained control over the
+information
+output you want to see. An individual flag name may be followed by a level
+number, with 0 meaning to silence that output, 1 being the default output
+level, and higher numbers increasing the output of that flag (for those
+that support higher levels). Use
+bf(--info=help)
+to see all the available flag names, what they output, and what flag names
+are added for each increase in the verbose level. Some examples:
+
+verb( rsync -a --info=progress2 src/ dest/
+ rsync -avv --info=stats2,misc1,flist0 src/ dest/ )
+
+Note that bf(--info=name)'s output is affected by the bf(--out-format) and
+bf(--itemize-changes) (bf(-i)) options. See those options for more
+information on what is output and when.
+
+This option was added to 3.1.0, so an older rsync on the server side might
+reject your attempts at fine-grained control (if one or more flags needed
+to be send to the server and the server was too old to understand them).
+
+dit(bf(--debug=FLAGS))
+This option lets you have fine-grained control over the
+debug
+output you want to see. An individual flag name may be followed by a level
+number, with 0 meaning to silence that output, 1 being the default output
+level, and higher numbers increasing the output of that flag (for those
+that support higher levels). Use
+bf(--debug=help)
+to see all the available flag names, what they output, and what flag names
+are added for each increase in the verbose level. Some examples:
+
+verb( rsync -avvv --debug=none src/ dest/
+ rsync -avA --del --debug=del2,acl src/ dest/ )
+
+This option was added to 3.1.0, so an older rsync on the server side might
+reject your attempts at fine-grained control (if one or more flags needed
+to be send to the server and the server was too old to understand them).
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
+from the remote server. This option name is useful when invoking rsync from
cron.
dit(bf(--no-motd)) This option affects the information that is output
ACLs from incompatible systems.
The bf(--fake-super) option only affects the side where the option is used.
-To affect the remote side of a remote-shell connection, specify an rsync
-path:
+To affect the remote side of a remote-shell connection, use the
+bf(--remote-option) (bf(-M)) option:
-quote(tt( rsync -av --rsync-path="rsync --fake-super" /src/ host:/dest/))
+quote(tt( rsync -av -M--fake-super /src/ host:/dest/))
-Since there is only one "side" in a local copy, this option affects both
-the sending and receiving of files. You'll need to specify a copy using
-"localhost" if you need to avoid this, possibly using the "lsh" shell
-script (from the support directory) as a substitute for an actual remote
-shell (see bf(--rsh)).
+For a local copy, this option affects both the source and the destination.
+If you wish a local copy to enable this option just for the destination
+files, specify bf(-M--fake-super). If you wish a local copy to enable
+this option just for the source files, combine bf(--fake-super) with
+bf(-M--super).
This option is overridden by both bf(--super) and bf(--no-super).
send the whole directory (e.g. "dir" or "dir/") without using a wildcard
for the directory's contents (e.g. "dir/*") since the wildcard is expanded
by the shell and rsync thus gets a request to transfer individual files, not
-the files' parent directory. Files that are excluded from transfer are
+the files' parent directory. Files that are excluded from the transfer are
also excluded from being deleted unless you use the bf(--delete-excluded)
option or mark the rules as only matching on the sending side (see the
include/exclude modifiers in the FILTER RULES section).
The bf(--delete) option may be combined with one of the --delete-WHEN options
without conflict, as well as bf(--delete-excluded). However, if none of the
--delete-WHEN options are specified, rsync will choose the
-bf(--delete-during) algorithm when talking to an rsync 3.0.0 or newer, and
+bf(--delete-during) algorithm when talking to rsync 3.0.0 or newer, and
the bf(--delete-before) algorithm when talking to an older rsync. See also
bf(--delete-delay) and bf(--delete-after).
memory at once (see bf(--recursive)).
dit(bf(--delete-during, --del)) Request that the file-deletions on the
-receiving side be done incrementally as the transfer happens. This is
-a faster method than choosing the before- or after-transfer algorithm,
-but it is only supported beginning with rsync version 2.6.4.
+receiving side be done incrementally as the transfer happens. The
+per-directory delete scan is done right before each directory is checked
+for updates, so it behaves like a more efficient bf(--delete-before),
+including doing the deletions prior to any per-directory filter files
+being updated. This option was first added in rsync version 2.6.4.
See bf(--delete) (which is implied) for more details on file-deletion.
dit(bf(--delete-delay)) Request that the file-deletions on the receiving
-side be computed during the transfer, and then removed after the transfer
-completes. If the number of removed files overflows an internal buffer, a
+side be computed during the transfer (like bf(--delete-during)), and then
+removed after the transfer completes. This is useful when combined with
+bf(--delay-updates) and/or bf(--fuzzy), and is more efficient than using
+bf(--delete-after) (but can behave differently, since bf(--delete-after)
+computes the deletions in a separate pass after all updates are done).
+If the number of removed files overflows an internal buffer, a
temporary file will be created on the receiving side to hold the names (it
is removed while open, so you shouldn't see it during the transfer). If
the creation of the temporary file fails, rsync will try to fall back to
using bf(--delete-after) (which it cannot do if bf(--recursive) is doing an
incremental scan).
+See bf(--delete) (which is implied) for more details on file-deletion.
dit(bf(--delete-after)) Request that the file-deletions on the receiving
side be done after the transfer has completed. This is useful if you
quote(tt( rsync -avR --rsync-path="cd /a/b && rsync" host:c/d /e/))
+dit(bf(-M, --remote-option=OPTION)) This option is used for more advanced
+situations where you want certain effects to be limited to one side of the
+transfer only. For instance, if you want to pass bf(--log-file=FILE) and
+bf(--fake-super) to the remote system, specify it like this:
+
+quote(tt( rsync -av -M --log-file=foo -M--fake-super src/ dest/))
+
+If you want to have an option affect only the local side of a transfer when
+it normally affects both sides, send its negation to the remote side. Like
+this:
+
+quote(tt( rsync -av -x -M--no-x src/ dest/))
+
+Be cautious using this, as it is possible to toggle an option that will cause
+rsync to have a different idea about what data to expect next over the socket,
+and that will make it fail in a cryptic fashion.
+
+Note that it is best to use a separate bf(--remote-option) for each option you
+want to pass. This makes your useage compatible with the bf(--protect-args)
+option. If that option is off, any spaces in your remote options will be split
+by the remote shell unless you take steps to protect them.
+
+When performing a local transfer, the "local" side is the sender and the
+"remote" side is the receiver.
+
+Note some versions of the popt option-parsing library have a bug in them that
+prevents you from using an adjacent arg with an equal in it next to a short
+option letter (e.g. tt(-M--log-file=/tmp/foo). If this bug affects your
+version of popt, you can use the version of popt that is included with rsync.
+
dit(bf(-C, --cvs-exclude)) This is a useful shorthand for excluding a
broad range of files that you often don't want to transfer between
systems. It uses a similar algorithm to CVS to determine if
outputting them as a verbose message).
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.
-
-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). 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(--out-format) without bf(--verbose) if you like, or you can override
-the format of its per-file output using this option.
+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. A default format of "%n%L" is assumed if
+either bf(--info=name) or bf(-v) is specified (this tells you just the name
+of the file and, if the item is a link, where it points). For a full list
+of the possible escape characters, see the "log format" setting in the
+rsyncd.conf manpage.
+
+Specifying the bf(--out-format) option implies the bf(--info=name) option,
+which will mention each file, dir, etc. that gets updated in a significant
+way (a transferred file, a recreated symlink/device, or a touched
+directory). In addition, if the itemize-changes escape (%i) is included in
+the string (e.g. if the bf(--itemize-changes) option was used), 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".
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
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/)
+verb( rsync -av --remote-option=--log-file=/tmp/rlog src/ dest/)
This is very useful if you need to debug why a connection is closing
unexpectedly.
dit(bf(--stats)) This tells rsync to print a verbose set of statistics
on the file transfer, allowing you to tell how effective rsync's delta-transfer
-algorithm is for your data.
+algorithm is for your data. This option is equivalent to bf(--info=stats2)
+if combined with 0 or 1 bf(-v) options, or bf(--info=stats3) if combined
+with 2 or more bf(-v) options.
The current statistics are as follows: quote(itemization(
it() bf(Number of files) is the count of all "files" (in the generic
dit(bf(--progress)) This option tells rsync to print information
showing the progress of the transfer. This gives a bored user
something to watch.
-Implies bf(--verbose) if it wasn't already specified.
+With a modern rsync this is the same as specifying
+bf(--info=flist2,name,progress), but any user-supplied settings for those
+info flags takes precedence (e.g. "--info=flist0 --progress").
While rsync is transferring a regular file, it updates a progress line that
looks like this:
purpose is to make it much easier to specify these two options for a long
transfer that may be interrupted.
+There is also a bf(--info=progress2) option that outputs statistics based
+on the whole transfer, rather than individual files. Use this flag without
+outputting a filename (e.g. avoid bf(-v) or specify bf(--info=name0) if you
+want to see how the transfer is doing without scrolling the screen with a
+lot of names. (You don't need to specify the bf(--progress) option in
+order to use bf(--info=progress2).)
+
dit(bf(--password-file)) This option allows you to provide a password in a
file for accessing an rsync daemon. The file must not be world readable.
It should contain just the password as a single line.
is used to set a specific checksum seed, which is useful for
applications that want repeatable block and file checksums, or
in the case where the user wants a more random checksum seed.
-Note that setting NUM to 0 causes rsync to use the default of code(time())
+Setting NUM to 0 causes rsync to use the default of code(time())
for checksum seed.
enddit()
manpagesection(VERSION)
-This man page is current for version 3.0.3pre3 of rsync.
+This man page is current for version 3.0.3 of rsync.
manpagesection(INTERNAL OPTIONS)
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff