X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/d252e47d09c5650cd1fba16a5ddae07efc8f43fe..aad635f766c450cd2cfac5fe5705213a417050b4:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 2838e0de..c34d4be7 100644 --- a/rsync.yo +++ b/rsync.yo @@ -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). @@ -1288,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 @@ -1725,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 @@ -1759,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. @@ -1773,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 @@ -1946,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: @@ -1981,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. @@ -2100,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()