X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/adc4ebdd76cf98aacbe87b9664dd291199294297..d8d13893489ba8245d2ff1e67fbb5c46dd047ef6:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 30a5187b..33773129 100644 --- a/rsync.yo +++ b/rsync.yo @@ -1,5 +1,5 @@ mailto(rsync-bugs@samba.org) -manpage(rsync)(1)(7 May 2008)()() +manpage(rsync)(1)(29 Jun 2008)()() manpagename(rsync)(a fast, versatile, remote (and local) file-copying tool) manpagesynopsis() @@ -412,6 +412,7 @@ to the detailed description below for a complete description. verb( --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 @@ -1026,16 +1027,16 @@ This is a good way to backup data without using a super-user, and to store 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). @@ -1117,7 +1118,7 @@ directories that are being synchronized. You must have asked rsync to 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). @@ -1139,7 +1140,7 @@ destination. You can override this with the bf(--ignore-errors) option. 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). @@ -1156,19 +1157,26 @@ algorithm that requires rsync to scan all the files in the transfer into 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 @@ -1281,6 +1289,36 @@ machine for use with the bf(--relative) option. For instance: 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 @@ -1752,7 +1790,7 @@ 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/) +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. @@ -2882,7 +2920,7 @@ url(http://rsync.samba.org/)(http://rsync.samba.org/) manpagesection(VERSION) -This man page is current for version 3.0.3pre1 of rsync. +This man page is current for version 3.0.3 of rsync. manpagesection(INTERNAL OPTIONS)