X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/13074c982bb4830a21287a1504b0e38a953f4f74..56fc9f70d385b20d431d9fa62ef4fd3941949717:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 90005c2c..c34d4be7 100644 --- a/rsync.yo +++ b/rsync.yo @@ -1,5 +1,5 @@ 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() @@ -314,6 +314,8 @@ manpagesection(OPTIONS SUMMARY) 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 @@ -412,6 +414,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 @@ -464,23 +467,61 @@ dit(bf(--version)) print the rsync version number and exit. 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 @@ -1026,16 +1067,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 +1158,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 +1180,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 +1197,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 +1329,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 @@ -1718,22 +1796,22 @@ you are talking to a recent enough rsync that it logs deletions instead of 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 @@ -1752,7 +1830,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. @@ -1766,7 +1844,9 @@ 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 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 @@ -1939,7 +2019,9 @@ in place of the hide-filter (if that is more natural to you). 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: @@ -1974,6 +2056,13 @@ dit(bf(-P)) The bf(-P) option is equivalent to bf(--partial) bf(--progress). It 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. @@ -2093,7 +2182,7 @@ by the server and defaults to the current code(time()). This option 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() @@ -2882,7 +2971,7 @@ url(http://rsync.samba.org/)(http://rsync.samba.org/) 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)