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()
--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
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
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.
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