X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/7a2eca415b0d7f40618dd67aa30bafef810b3724..e34ad4e925293ff222bb4fe47b010153fa9f30ab:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 33773129..efa99904 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 @@ -334,6 +336,7 @@ to the detailed description below for a complete description. verb( -L, --copy-links transform symlink into referent file/dir --copy-unsafe-links only "unsafe" symlinks are transformed --safe-links ignore symlinks that point outside the tree + --munge-links munge symlinks to make them safer -k, --copy-dirlinks transform symlink to dir into referent dir -K, --keep-dirlinks treat symlinked dir on receiver as dir -H, --hard-links preserve hard links @@ -436,6 +439,7 @@ accepted: verb( --address=ADDRESS bind to the specified address --bwlimit=KBPS limit I/O bandwidth; KBytes per second --config=FILE specify alternate rsyncd.conf file + -M, --dparam=OVERRIDE override global daemon config parameter --no-detach do not detach from the parent --port=PORT listen on alternate port number --log-file=FILE override the "log file" setting @@ -465,23 +469,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 @@ -791,6 +833,25 @@ which point outside the copied tree. All absolute symlinks are also ignored. Using this option in conjunction with bf(--relative) may give unexpected results. +dit(bf(--munge-links)) This option tells rsync to (1) modify all symlinks on +the receiving side in a way that makes them unusable but recoverable (see +below), or (2) to unmunge symlinks on the sending side that had been stored in +a munged state. This is useful if you don't quite trust the source of the data +to not try to slip in a symlink to a unexpected place. + +The way rsync disables the use of symlinks is to prefix each one with the +string "/rsyncd-munged/". This prevents the links from being used as long as +that directory does not exist. When this option is enabled, rsync will refuse +to run if that path is a directory or a symlink to a directory. + +The option only affects the client side of the transfer, so if you need it to +affect the server, specify it via bf(--remote-option). (Note that in a local +transfer, the client side is the sender.) + +This option has no affect on a daemon, since the daemon configures whether it +wants munged symlinks via its "munge symlinks" parameter. See also the +"munge-symlinks" perl script in the support directory of the source code. + dit(bf(-k, --copy-dirlinks)) This option causes the sending side to treat a symlink to a directory as though it were a real directory. This is useful if you don't want symlinks to non-directories to be affected, as @@ -1560,6 +1621,11 @@ An example: quote(tt( rsync -av --link-dest=$PWD/prior_dir host:src_dir/ new_dir/)) +If file's aren't linking, double-check their attributes. Also check if some +attributes are getting forced outside of rsync's control, such a mount option +that squishes root to a single user, or mounts a removable drive with generic +ownership (such as OS X's "Ignore ownership on this volume" option). + Beginning in version 2.6.4, multiple bf(--link-dest) directories may be provided, which will cause rsync to search the list in the order specified for an exact match. @@ -1756,22 +1822,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 @@ -1804,7 +1870,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 @@ -1977,7 +2045,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: @@ -2012,6 +2082,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. @@ -2131,7 +2208,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() @@ -2169,6 +2246,14 @@ The default is /etc/rsyncd.conf unless the daemon is running over a remote shell program and the remote user is not the super-user; in that case the default is rsyncd.conf in the current directory (typically $HOME). +dit(bf(-M, --dparam=OVERRIDE)) This option can be used to set a daemon-config +parameter when starting up rsync in daemon mode. It is equivalent to adding +the parameter at the end of the global settings prior to the first module's +definition. The parameter names can be specified without spaces, if you so +desire. For instance: + +verb( rsync --daemon -M pidfile=/path/rsync.pid ) + dit(bf(--no-detach)) When running as a daemon, this option instructs rsync to not detach itself and become a background process. This option is required when running as a service on Cygwin, and may also