X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/0dd2310cac470e16306aef6c262a9f76b62545d3..5deb19e4ea1c04cac93f39d60a3a8f891a6fff74:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 8a25a8cd..17e9025f 100644 --- a/rsync.yo +++ b/rsync.yo @@ -430,7 +430,7 @@ to the detailed description below for a complete description. verb( --log-file-format=FMT log updates using the specified FMT --password-file=FILE read daemon-access password from FILE --list-only list the files instead of copying them - --bwlimit=KBPS limit I/O bandwidth; KBytes per second + --bwlimit=RATE limit socket I/O bandwidth --write-batch=FILE write a batched update to FILE --only-write-batch=FILE like --write-batch but w/o updating dest --read-batch=FILE read a batched update from FILE @@ -446,7 +446,7 @@ Rsync can also be run as a daemon, in which case the following options are accepted: verb( --daemon run as an rsync daemon --address=ADDRESS bind to the specified address - --bwlimit=KBPS limit I/O bandwidth; KBytes per second + --bwlimit=RATE limit socket I/O bandwidth --config=FILE specify alternate rsyncd.conf file -M, --dparam=OVERRIDE override global daemon config parameter --no-detach do not detach from the parent @@ -761,17 +761,26 @@ its data needs to be updated: instead of the default method of creating a new copy of the file and moving it into place when it is complete, rsync instead writes the updated data directly to the destination file. -This has several effects: (1) in-use binaries cannot be updated (either the -OS will prevent this from happening, or binaries that attempt to swap-in -their data will misbehave or crash), (2) the file's data will be in an -inconsistent state during the transfer, (3) a file's data may be left in an -inconsistent state after the transfer if the transfer is interrupted or if -an update fails, (4) a file that does not have write permissions can not be -updated, and (5) the efficiency of rsync's delta-transfer algorithm may be -reduced if some data in the destination file is overwritten before it can -be copied to a position later in the file (one exception to this is if you -combine this option with bf(--backup), since rsync is smart enough to use -the backup file as the basis file for the transfer). +This has several effects: + +quote(itemization( + it() Hard links are not broken. This means the new data will be visible + through other hard links to the destination file. Moreover, attempts to + copy differing source files onto a multiply-linked destination file will + result in a "tug of war" with the destination data changing back and forth. + it() In-use binaries cannot be updated (either the OS will prevent this from + happening, or binaries that attempt to swap-in their data will misbehave or + crash). + it() The file's data will be in an inconsistent state during the transfer + and will be left that way if the transfer is interrupted or if an update + fails. + it() A file that does not have write permissions cannot be updated. + it() The efficiency of rsync's delta-transfer algorithm may be reduced if + some data in the destination file is overwritten before it can be copied to + a position later in the file. This does not apply if you use bf(--backup), + since rsync is smart enough to use the backup file as the basis file for the + transfer. +)) WARNING: you should not use this option to update files that are being accessed by others, so be careful when choosing to use this for a copy. @@ -881,6 +890,17 @@ bf(--force) or bf(--delete) is in effect). See also bf(--keep-dirlinks) for an analogous option for the receiving side. +bf(--copy-dirlinks) applies to all symlinks to directories in the source. If +you want to follow only a few specified symlinks, a trick you can use is to +pass them as additional source args with a trailing slash, using bf(--relative) +to make the paths match up right. For example: + +quote(tt(rsync -r --relative src/./ src/./follow-me/ dest/)) + +This works because rsync calls bf(lstat)(2) on the source arg as given, and the +trailing slash makes bf(lstat)(2) follow the symlink, giving rise to a directory +in the file-list which overrides the symlink found during the scan of "src/./". + dit(bf(-K, --keep-dirlinks)) This option causes the receiving side to treat a symlink to a directory as though it were a real directory, but only if it matches a real directory from the sender. Without this option, the @@ -904,17 +924,23 @@ to modify your receiving hierarchy. See also bf(--copy-dirlinks) for an analogous option for the sending side. dit(bf(-H, --hard-links)) This tells rsync to look for hard-linked files in -the transfer and link together the corresponding files on the receiving -side. Without this option, hard-linked files in the transfer are treated +the source and link together the corresponding files on the destination. +Without this option, hard-linked files in the source are treated as though they were separate files. -When you are updating a non-empty destination, this option only ensures -that files that are hard-linked together on the source are hard-linked -together on the destination. It does NOT currently endeavor to break -already existing hard links on the destination that do not exist between -the source files. Note, however, that if one or more extra-linked files -have content changes, they will become unlinked when updated (assuming you -are not using the bf(--inplace) option). +This option does NOT necessarily ensure that the pattern of hard links on the +destination exactly matches that on the source. Cases in which the +destination may end up with extra hard links include the following: + +quote(itemization( + it() If the destination already contains hard links, rsync will not break + them explicitly. However, if one or more of the paths have content + differences, the normal file-update process will break those links, unless + you are using the bf(--inplace) option. + it() If you specify a bf(--link-dest) directory that contains hard links, + rsync may use the same bf(--link-dest) file multiple times via several of + its paths. +)) Note that rsync can only detect hard links between files that are inside the transfer set. If rsync updates a file that has extra hard-link @@ -1005,14 +1031,18 @@ The source and destination systems must have compatible ACL entries for this option to work properly. See the bf(--fake-super) option for a way to backup and restore ACLs that are not compatible. -dit(bf(-X, --xattrs)) This option causes rsync to update the remote -extended attributes to be the same as the local ones. +dit(bf(-X, --xattrs)) This option causes rsync to update the destination +extended attributes to be the same as the source ones. For systems that support extended-attribute namespaces, a copy being done by a super-user copies all namespaces except system.*. A normal user only copies the user.* namespace. To be able to backup and restore non-user namespaces as a normal user, see the bf(--fake-super) option. +Note that this option does not copy rsyncs special xattr values (e.g. those +used by bf(--fake-super)) unless you repeat the option (e.g. -XX). This +"copy all xattrs" mode cannot be used with bf(--fake-super). + dit(bf(--chmod)) This option tells rsync to apply one or more comma-separated "chmod" strings to the permission of the files in the transfer. The resulting value is treated as though it were the permissions @@ -1584,6 +1614,20 @@ side will also be translated from the local to the remote character-set. The translation happens before wild-cards are expanded. See also the bf(--files-from) option. +You may also control this option via the RSYNC_PROTECT_ARGS environment +variable. If this variable has a non-zero value, this option will be enabled +by default, otherwise it will be disabled by default. Either state is +overridden by a manually specified positive or negative version of this option +(note that bf(--no-s) and bf(--no-protect-args) are the negative versions). +Since this option was first introduced in 3.0.0, you'll need to make sure it's +disabled if you ever need to interact with a remote rsync that is older than +that. + +Rsync can also be configured (at build time) to have this option enabled by +default (with is overridden by both the environment and the command-line). +This option will eventually become a new default setting at some +as-yet-undetermined point in the future. + dit(bf(-T, --temp-dir=DIR)) This option instructs rsync to use DIR as a scratch directory when creating temporary copies of the files transferred on the receiving side. The default behavior is to create each temporary @@ -2273,13 +2317,27 @@ avoid this problem, either specify the bf(--no-dirs) option (if you don't need to expand a directory's content), or turn on recursion and exclude the content of subdirectories: bf(-r --exclude='/*/*'). -dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum -transfer rate in kilobytes per second. This option is most effective when -using rsync with large files (several megabytes and up). Due to the nature -of rsync transfers, blocks of data are sent, then if rsync determines the -transfer was too fast, it will wait before sending the next data block. The -result is an average transfer rate equaling the specified limit. A value -of zero specifies no limit. +dit(bf(--bwlimit=RATE)) This option allows you to specify the maximum transfer +rate for the data sent over the socket, specified in units per second. The +RATE value can be suffixed with a string to indicate a size multiplier, and may +be a fractional value (e.g. "bf(--bwlimit=1.5m)"). If no suffix is specified, +the value will be assumed to be in units of 1024 bytes (as if "K" or "KiB" had +been appended). See the bf(--max-size) option for a description of all the +available suffixes. A value of zero specifies no limit. + +For backward-compatibility reasons, the rate limit will be rounded to the +nearest KiB unit, so no rate smaller than 1024 bytes per second is possible. + +Rsync writes data over the socket in blocks, and this option both limits the +size of the blocks that rsync writes, and tries to keep the average transfer +rate at the requested limit. Some "burstiness" may be seen where rsync writes +out a block of data and then sleeps to bring the average rate into compliance. + +Due to the internal buffering of data, the bf(--progress) option may not be an +accurate reflection on how fast the data is being sent. This is because some +files can show up as being rapidly sent when the data is quickly buffered, +while other can show up as very slow when the flushing of the output buffer +occurs. This may be fixed in a future version. dit(bf(--write-batch=FILE)) Record a file that can later be applied to another identical destination with bf(--read-batch). See the "BATCH MODE" @@ -2387,11 +2445,10 @@ allows you to specify a specific IP address (or hostname) to bind to. This makes virtual hosting possible in conjunction with the bf(--config) option. See also the "address" global option in the rsyncd.conf manpage. -dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum -transfer rate in kilobytes per second for the data the daemon sends. -The client can still specify a smaller bf(--bwlimit) value, but their -requested value will be rounded down if they try to exceed it. See the -client version of this option (above) for some extra details. +dit(bf(--bwlimit=RATE)) This option allows you to specify the maximum transfer +rate for the data the daemon sends over the socket. The client can still +specify a smaller bf(--bwlimit) value, but no larger value will be allowed. +See the client version of this option (above) for some extra details. dit(bf(--config=FILE)) This specifies an alternate config file than the default. This is only relevant when bf(--daemon) is specified. @@ -3116,7 +3173,10 @@ dit(bf(CVSIGNORE)) The CVSIGNORE environment variable supplements any ignore patterns in .cvsignore files. See the bf(--cvs-exclude) option for more details. dit(bf(RSYNC_ICONV)) Specify a default bf(--iconv) setting using this -environment variable. +environment variable. (First supported in 3.0.0.) +dit(bf(RSYNC_PROTECT_ARGS)) Specify a non-zero numeric value if you want the +bf(--protect-args) option to be enabled by default, or a zero value to make +sure that it is disabled by default. (First supported in 3.1.0.) dit(bf(RSYNC_RSH)) The RSYNC_RSH environment variable allows you to override the default shell used as the transport for rsync. Command line options are permitted after the command name, just as in the bf(-e) option.