X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/8f61dfdbd46da5c54816193e0e841e7b672dccdf..32b9011ae97cb4be9dbd6d1991a9b633b64ce6a0:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 37f981ca..18c79842 100644 --- a/rsync.yo +++ b/rsync.yo @@ -15,25 +15,26 @@ Access via rsync daemon: Push: rsync [OPTION...] SRC... [USER@]HOST::DEST rsync [OPTION...] SRC... rsync://[USER@]HOST[:PORT]/DEST) -Usages without a DEST list the source files instead of copying. +Usages with just one SRC arg and no DEST arg will list the source files +instead of copying. manpagedescription() -Rsync is a program that behaves in much the same way that rcp does, -but has many more options and uses the rsync remote-update protocol to -greatly speed up file transfers when the destination file is being -updated. - -The rsync remote-update protocol allows rsync to transfer just the -differences between two sets of files across the network connection, using -an efficient checksum-search algorithm described in the technical -report that accompanies this package. - -Rsync finds files that need to be transferred using a "quick check" algorithm -that looks for files that have changed in size or in last-modified time (by -default). Any changes in the other preserved attributes (as requested by -options) are made on the destination file directly when the quick check -indicates that the file's data does not need to be updated. +Rsync is a fast and extraordinarily versatile file copying tool. It can +copy locally, to/from another host over any remote shell, or to/from a +remote rsync daemon. It offers a large number of options that control +every aspect of its behavior and permit very flexible specification of the +set of files to be copied. It is famous for its delta-transfer algorithm, +which reduces the amount of data sent over the network by sending only the +differences between the source files and the existing files in the +destination. Rsync is widely used for backups and mirroring and as an +improved copy command for everyday use. + +Rsync finds files that need to be transferred using a "quick check" +algorithm (by default) that looks for files that have changed in size or +in last-modified time. Any changes in the other preserved attributes (as +requested by options) are made on the destination file directly when the +quick check indicates that the file's data does not need to be updated. Some of the additional features of rsync are: @@ -746,6 +747,12 @@ bf(--recursive) option, rsync will skip all directories it encounters (and output a message to that effect for each one). If you specify both bf(--dirs) and bf(--recursive), bf(--recursive) takes precedence. +This option is implied by the bf(--list-only) option (including an implied +bf(--list-only) usage) if bf(--recursive) wasn't specified (so that +directories are seen in the listing). Specify bf(--no-dirs) (or bf(--no-d)) +if you want to override this. This option is also implied by +bf(--files-from). + dit(bf(-l, --links)) When symlinks are encountered, recreate the symlink on the destination. @@ -1072,9 +1079,9 @@ Prior to rsync 2.6.7, this option would have no effect unless bf(--recursive) was enabled. Beginning with 2.6.7, deletions will also occur when bf(--dirs) (bf(-d)) is enabled, but only for directories whose contents are being copied. -This option can be dangerous if used incorrectly! It is a very good idea -to run first using the bf(--dry-run) option (bf(-n)) to see what files would be -deleted to make sure important files aren't listed. +This option can be dangerous if used incorrectly! It is a very good idea to +first try a run using the bf(--dry-run) option (bf(-n)) to see what files are +going to be deleted. If the sending side detects any I/O errors, then the deletion of any files at the destination will be automatically disabled. This is to @@ -1921,16 +1928,22 @@ dit(bf(--list-only)) This option will cause the source files to be listed instead of transferred. This option is inferred if there is a single source arg and no destination specified, so its main uses are: (1) to turn a copy command that includes a -destination arg into a file-listing command, (2) to be able to specify more -than one local source arg (note: be sure to include the destination), or -(3) to avoid the automatically added "bf(-r --exclude='/*/*')" options that -rsync usually uses as a compatibility kluge when generating a non-recursive -listing. Caution: keep in mind that a source arg with a wild-card is expanded -by the shell into multiple args, so it is never safe to try to list such an arg +destination arg into a file-listing command, or (2) to be able to specify +more than one source arg (note: be sure to include the destination). +Caution: keep in mind that a source arg with a wild-card is expanded by the +shell into multiple args, so it is never safe to try to list such an arg without using this option. For example: verb( rsync -av --list-only foo* dest/) +Compatibility note: when requesting a remote listing of files from an rsync +that is version 2.6.3 or older, you may encounter an error if you ask for a +non-recursive listing. This is because a file listing implies the bf(--dirs) +option w/o bf(--recursive), and older rsyncs don't have that option. To +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