X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/dc0f24976d941a5bf197b4eab7f5680a85990659..ea38b5af722f8c343871c197c5f09cbca77e2384:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 0c21a922..1daed83e 100644 --- a/rsync.yo +++ b/rsync.yo @@ -1,5 +1,5 @@ mailto(rsync-bugs@samba.org) -manpage(rsync)(1)(30 Sep 2004)()() +manpage(rsync)(1)(22 Feb 2005)()() manpagename(rsync)(faster, flexible replacement for rcp) manpagesynopsis() @@ -332,6 +332,7 @@ to the detailed description below for a complete description. verb( --rsync-path=PATH specify path to rsync on the remote machine --existing only update files that already exist --ignore-existing ignore files that already exist on receiver + --remove-sent-files sent files/symlinks are removed from sender --del an alias for --delete-during --delete delete files that don't exist on sender --delete-before receiver deletes before transfer (default) @@ -353,7 +354,6 @@ to the detailed description below for a complete description. verb( -T, --temp-dir=DIR create temporary files in directory DIR -y, --fuzzy find similar file for basis if no dest file --compare-dest=DIR also compare received files relative to DIR - --copy-dest=DIR ... and include copies of unchanged files --link-dest=DIR hardlink to files in DIR when unchanged -z, --compress compress file data during the transfer -C, --cvs-exclude auto-ignore files in the same way CVS does @@ -373,7 +373,7 @@ to the detailed description below for a complete description. verb( --stats give some file-transfer stats --progress show progress during transfer -P same as --partial --progress - -w, --what-has-changed output a change summary for all updates + -i, --itemize-changes output a change-summary for all updates --log-format=FORMAT log file-transfers using specified format --password-file=FILE read password from FILE --list-only list the files instead of copying them @@ -420,6 +420,15 @@ 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 you are debugging rsync. +Note that the names of the transferred files that are output are done using +a default bf(--log-format) of "%n%L", which tells you just the name of the +file and, if the item is a symlink, 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(--log-format) setting), the +output (on the client) increases to mention all items that are changed in +any way. See the bf(--log-format) option for more details. + 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 @@ -453,7 +462,7 @@ receiver are not transferred. This option can be quite slow. dit(bf(-a, --archive)) This is equivalent to bf(-rlptgoD). It is a quick way of saying you want recursion and want to preserve almost everything. The only exception to this is if bf(--files-from) was -specified, in which case bf(-d) is implied instead of bf(-r). +specified, in which case bf(-r) is not implied. Note that bf(-a) bf(does not preserve hardlinks), because finding multiply-linked files is expensive. You must separately @@ -505,6 +514,8 @@ dit(bf(-b, --backup)) With this option, preexisting destination files are renamed as each file is transferred or deleted. You can control where the backup file goes and what (if any) suffix gets appended using the bf(--backup-dir) and bf(--suffix) options. +Note that if you don't specify bf(--backup-dir), the bf(--omit-dir-times) +option will be enabled. dit(bf(--backup-dir=DIR)) In combination with the bf(--backup) option, this tells rsync to store all backups in the specified directory. This is @@ -512,8 +523,6 @@ very useful for incremental backups. You can additionally specify a backup suffix using the bf(--suffix) option (otherwise the files backed up in the specified directory will keep their original filenames). -If DIR is a relative path, it is relative to the destination directory -(which changes in a recursive transfer). dit(bf(--suffix=SUFFIX)) This option allows you to override the default backup suffix used with the bf(--backup) (bf(-b)) option. The default suffix is a ~ @@ -546,8 +555,8 @@ bound. The option implies bf(--partial) (since an interrupted transfer does not delete the file), but conflicts with bf(--partial-dir) and bf(--delay-updates). -Prior to rsync 2.6.4 bf(--inplace) was also incompatible with bf(--compare-dest), -bf(--copy-dest), and bf(--link-dest). +Prior to rsync 2.6.4 bf(--inplace) was also incompatible with bf(--compare-dest) +and bf(--link-dest). WARNING: The file's data will be in an inconsistent state during the transfer (and possibly afterward if the transfer gets interrupted), so you @@ -643,6 +652,7 @@ if the files haven't actually changed, you're much better off using bf(-t)). dit(bf(-O, --omit-dir-times)) This tells rsync to omit directories when it is preserving modification times (see bf(--times)). If NFS is sharing the directories on the receiving side, it is a good idea to use bf(-O). +This option is inferred if you use bf(--backup) without bf(--backup-dir). dit(bf(-n, --dry-run)) This tells rsync to not do any file transfers, instead it will just report the actions it would have taken. @@ -665,14 +675,10 @@ dit(bf(--ignore-existing)) This tells rsync not to update files that already exist on the destination. -dit(bf(--max-delete=NUM)) This tells rsync not to delete more than NUM -files or directories. This is useful when mirroring very large trees -to prevent disasters. - -dit(bf(--max-size=SIZE)) This tells rsync to avoid transferring any -file that is larger than the specified SIZE. The SIZE value can be -suffixed with a letter to indicate a size multiplier (K, M, or G) and -may be a fractional value (e.g. "bf(--max-size=1.5m)"). +dit(bf(--remove-sent-files)) This tells rsync to remove from the sending +side the files and/or symlinks that are newly created or whose content is +updated on the receiving side. Directories and devices are not removed, +nor are files/symlinks whose attributes are merely changed. dit(bf(--delete)) This tells rsync to delete extraneous files from the receiving side (ones that aren't on the sending side), but only for the @@ -743,6 +749,15 @@ they are not empty when they are to be replaced by non-directories. This is only relevant without bf(--delete) because deletions are now done depth-first. Requires the bf(--recursive) option (which is implied by bf(-a)) to have any effect. +dit(bf(--max-delete=NUM)) This tells rsync not to delete more than NUM +files or directories. This is useful when mirroring very large trees +to prevent disasters. + +dit(bf(--max-size=SIZE)) This tells rsync to avoid transferring any +file that is larger than the specified SIZE. The SIZE value can be +suffixed with a letter to indicate a size multiplier (K, M, or G) and +may be a fractional value (e.g. "bf(--max-size=1.5m)"). + dit(bf(-B, --block-size=BLOCKSIZE)) This forces the block size used in the rsync algorithm to a fixed value. It is normally selected based on the size of each file being updated. See the technical report for details. @@ -935,19 +950,9 @@ finds an existing file. That first discovery is used as the basis file, and also determines if the transfer needs to happen. If em(DIR) is a relative path, it is relative to the destination directory. -See also bf(--copy-dest) and bf(--link-dest). - -dit(bf(--copy-dest=DIR)) This option behaves like bf(--compare-dest), but -rsync will also copy unchanged files found in em(DIR) to the destination -directory (using the data in the em(DIR) for an efficient copy). This is -useful for doing transfers to a new destination while leaving existing -files intact, and then doing a flash-cutover when all files have been -successfully transferred. +See also bf(--link-dest). -If em(DIR) is a relative path, it is relative to the destination directory. -See also bf(--compare-dest) and bf(--link-dest). - -dit(bf(--link-dest=DIR)) This option behaves like bf(--copy-dest), but +dit(bf(--link-dest=DIR)) This option behaves like bf(--compare-dest), but unchanged files are hard linked from em(DIR) to the destination directory. The files must be identical in all preserved attributes (e.g. permissions, possibly ownership) in order for the files to be linked together. @@ -961,7 +966,7 @@ the list in the order specified), and if not found, a basis file from one of the em(DIR)s will be selected to try to speed up the transfer. If em(DIR) is a relative path, it is relative to the destination directory. -See also bf(--compare-dest) and bf(--copy-dest). +See also bf(--compare-dest). Note that rsync versions prior to 2.6.1 had a bug that could prevent bf(--link-dest) from working properly for a non-root user when bf(-o) was specified @@ -1012,43 +1017,26 @@ ssh prefers non-blocking I/O.) dit(bf(--no-blocking-io)) Turn off bf(--blocking-io), for use when it is the default. -dit(bf(--what-has-changed)) Outputs a change-summary for each updated -item. The format is as follows: - -quote(tt( *XcstpogDL ITEM_NAME)) - -The bf(*) will be present if this is a file that is being transferred, -otherwise it will be replaced with a space. The bf(X) will be replaced by -one of the following: an "f" for a file, a "d" for a dir, an "L" for a -symlink, or a "D" for a device. The rest of the letters in the string -above are the actual letters that will be output if the associated -attribute for the item is being updated; if not the letter will be replaced -by either a "-" if no change is occurring, or a "+" if this is a new item. -The meanings of the attribute letters are as follows: - -itemize( - it() The bf(c) means the checksum of the file is different and will be - updated by the file transfer (requries bf(--checksum)). - it() A bf(s) means the size of the file is different and will be updated - by the file transfer. - it() A bf(t) means the modified time is being updated to the server's - value (requires --times, but transferred files without --times will be - marked with a bf(T) because the time is updated to the transfer time). - it() A bf(p) means the permissions are being updated (requires - bf(--perms)). - it() The bf(o) means the owner is being updated (requires bf(--owner) and - root privileges). - it() The bf(g) means the group is being updated (requires bf(--group)). - it() The bf(D) means the device is being updated (requires bf(--devices) - and root privileges). - it() The bf(L) means the symlink value is being updated (requires - --links). -) +dit(bf(-i, --itemize-changes)) Requests a simple itemized list of the +changes that are being made to each file, including attribute changes. +This is equivalent to specifying bf(--log-format='%i %n%L'). (See the +description of what the output of '%i' means in the rsyncd.conf manpage.) +Rsync also mentions the delete action when an item replaces an item of a +different type (e.g. a directory replaces a file of the same name). dit(bf(--log-format=FORMAT)) This allows you to specify exactly what the -rsync client logs to stdout on a per-file basis. The log format is -specified using the same format conventions as the log format option in -rsyncd.conf. +rsync client logs to stdout on a per-file basis. This format can be used +without bf(--verbose) to enable just the outputting of the file-transfer +information, or it can be used to change how the names are output when +bf(--verbose) is enabled. Rsync will log the name of an item prior to its +transfer unless one of the transferred-byte-count values is requested, in +which case the logging is done at the end of the item's transfer. In this +late-transfer state, if bf(--progress) is also specified, rsync will output +just the name of the file prior to the progress information. + +The log format is specified using the same format conventions as the +"log format" option in rsyncd.conf, so see that manpage for details. +(Note that this option does not affect what a daemon logs to its logfile.) dit(bf(--stats)) This tells rsync to print a verbose set of statistics on the file transfer, allowing you to tell how effective the rsync