X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/d100e733db1c34030385e46dae47fdbf1984de60..cc56eb2acca94ac29149d4a838fe43db6edc3867:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 658ad99d..626aff50 100644 --- a/rsync.yo +++ b/rsync.yo @@ -1,5 +1,5 @@ mailto(rsync-bugs@samba.org) -manpage(rsync)(1)(26 Oct 2007)()() +manpage(rsync)(1)(17 May 2008)()() manpagename(rsync)(a fast, versatile, remote (and local) file-copying tool) manpagesynopsis() @@ -353,7 +353,7 @@ to the detailed description below for a complete description. verb( --fake-super store/recover privileged attrs using xattrs -S, --sparse handle sparse files efficiently -n, --dry-run perform a trial run with no changes made - -W, --whole-file copy files whole (without rsync algorithm) + -W, --whole-file copy files whole (w/o delta-xfer algorithm) -x, --one-file-system don't cross filesystem boundaries -B, --block-size=SIZE force a fixed checksum block-size -e, --rsh=COMMAND specify the remote shell to use @@ -378,7 +378,8 @@ to the detailed description below for a complete description. verb( --delay-updates put all updated files into place at end -m, --prune-empty-dirs prune empty directory chains from file-list --numeric-ids don't map uid/gid values by user/group name - --timeout=TIME set I/O timeout in seconds + --timeout=SECONDS set I/O timeout in seconds + --contimeout=SECONDS set daemon connection timeout in seconds -I, --ignore-times don't skip files that match size and time --size-only skip files that match in size --modify-window=NUM compare mod-times with reduced accuracy @@ -527,7 +528,7 @@ either a changed size or a changed checksum are selected for transfer. Note that rsync always verifies that each em(transferred) file was correctly reconstructed on the receiving side by checking a whole-file -checksum that is generated when as the file is transferred, but that +checksum that is generated as the file is transferred, but that automatic after-the-transfer verification has nothing to do with this option's before-the-transfer "Does this file need to be updated?" check. @@ -696,13 +697,25 @@ date is on the objects. In other words, if the source has a directory where the destination has a file, the transfer would occur regardless of the timestamps. -dit(bf(--inplace)) This causes rsync not to create a new copy of the file -and then move it into place. Instead rsync will overwrite the existing -file, meaning that the rsync algorithm can't accomplish the full amount of -network reduction it might be able to otherwise (since it does not yet try -to sort data matches). One exception to this is if you combine the option -with bf(--backup), since rsync is smart enough to use the backup file as the -basis file for the transfer. +dit(bf(--inplace)) This option changes how rsync transfers a file when the +file's 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). + +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. This option is useful for transfer of large files with block-based changes or appended data, and also on systems that are disk bound, not network @@ -713,18 +726,15 @@ 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) 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 -should not use this option to update files that are in use. Also note that -rsync will be unable to update a file in-place that is not writable by the -receiving user. - dit(bf(--append)) This causes rsync to update a file by appending data onto the end of the file, which presumes that the data that already exists on the receiving side is identical with the start of the file on the sending -side. Any files that are the same size or shorter on the receiving size -are skipped. Files that do not yet exist on the receiving side are also -sent, since they are considered to have 0 length. Implies bf(--inplace), +side. If a file needs to be transferred and its size on the receiver is +the same or longer than the size on the sender, the file is skipped. This +does not interfere with the updating of a file's non-content attributes +(e.g. permissions, ownership, etc.) when the file does not need to be +transferred, nor does it affect the updating of any non-regular files. +Implies bf(--inplace), but does not conflict with bf(--sparse) (since it is always extending a file's length). @@ -747,11 +757,15 @@ 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 +The bf(--dirs) option is implied by the bf(--files-from) option +or 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). +if you want to turn this off. + +There is also a backward-compatibility helper option, bf(--old-dirs) (or +bf(--old-d)) that tells rsync to use a hack of "-r --exclude='/*/*'" to get +an older rsync to list a single directory without recursing. dit(bf(-l, --links)) When symlinks are encountered, recreate the symlink on the destination. @@ -816,11 +830,24 @@ the transfer and link together the corresponding files on the receiving side. Without this option, hard-linked files in the transfer are treated as though they were separate files. -Note that rsync can only detect hard links if both parts of the link -are in the list of files being sent. +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). + +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 +connections to files outside the transfer, that linkage will be broken. If +you are tempted to use the bf(--inplace) option to avoid this breakage, be +very careful that you know how your files are being updated so that you are +certain that no unintended changes happen due to lingering hard links (and +see the bf(--inplace) option for more caveats). If incremental recursion is active (see bf(--recursive)), rsync may transfer -a missing hard-linked file before it finds that another link for the file +a missing hard-linked file before it finds that another link for that contents exists elsewhere in the hierarchy. This does not affect the accuracy of the transfer, just its efficiency. One way to avoid this is to disable incremental recursion using the bf(--no-inc-recursive) option. @@ -965,7 +992,7 @@ with the files and update them on the remote system. Note that if this option is not used, the optimization that excludes files that have not been modified cannot be effective; in other words, a missing bf(-t) or bf(-a) will cause the next transfer to behave as if it used bf(-I), causing all files to be -updated (though the rsync algorithm will make the update fairly efficient +updated (though rsync's delta-transfer algorithm will make the update fairly efficient 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 @@ -1037,7 +1064,7 @@ the "bytes sent", "bytes received", "literal data", and "matched data" statistics are too small, and the "speedup" value is equivalent to a run where no file transfers are needed. -dit(bf(-W, --whole-file)) With this option the delta transfer algorithm +dit(bf(-W, --whole-file)) With this option rsync's delta-transfer algorithm is not used and the whole file is sent as-is instead. The transfer may be faster if this option is used when the bandwidth between the source and destination machines is higher than the bandwidth to disk (especially when the @@ -1204,7 +1231,7 @@ transferring small, junk files. See the bf(--max-size) option for a description of SIZE. 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 +rsync's delta-transfer algorithm to a fixed value. It is normally selected based on the size of each file being updated. See the technical report for details. dit(bf(-e, --rsh=COMMAND)) This option allows you to choose an alternative @@ -1292,7 +1319,10 @@ exclude certain files from the list of files to be transferred. This is most useful in combination with a recursive transfer. You may use as many bf(--filter) options on the command line as you like -to build up the list of files to exclude. +to build up the list of files to exclude. If the filter contains whitespace, +be sure to quote it so that the shell gives the rule to rsync as a single +argument. The text below also mentions that you can use an underscore to +replace the space that separates a rule from its arg. See the FILTER RULES section for detailed information on this option. @@ -1405,7 +1435,7 @@ characters are not translated (such as ~, $, ;, &, etc.). Wildcards are expanded on the remote host by rsync (instead of the shell doing it). If you use this option with bf(--iconv), the args will also be translated -from the local to the remote character set. The translation happens before +from the local to the remote character-set. The translation happens before wild-cards are expanded. See also the bf(--files-from) option. dit(bf(-T, --temp-dir=DIR)) This option instructs rsync to use DIR as a @@ -1415,7 +1445,7 @@ file in the same directory as the associated destination file. This option is most often used when the receiving disk partition does not have enough free space to hold a copy of the largest file in the transfer. -In this case (i.e. when the scratch directory in on a different disk +In this case (i.e. when the scratch directory is on a different disk partition), rsync will not be able to rename each received temporary file over the top of the associated destination file, but instead must copy it into place. Rsync does this by copying the file over the top of the @@ -1582,6 +1612,10 @@ dit(bf(--timeout=TIMEOUT)) This option allows you to set a maximum I/O timeout in seconds. If no data is transferred for the specified time then rsync will exit. The default is 0, which means no timeout. +dit(bf(--contimeout)) This option allows you to set the amount of time +that rsync will wait for its connection to an rsync daemon to succeed. +If the timeout is reached, rsync exits with an error. + dit(bf(--address)) By default rsync will bind to the wildcard address when connecting to an rsync daemon. The bf(--address) option allows you to specify a specific IP address (or hostname) to bind to. See also this @@ -1635,6 +1669,8 @@ quote(itemization( bf(--hard-links)). it() A bf(.) means that the item is not being updated (though it might have attributes that are being modified). + it() A bf(*) means that the rest of the itemized-output area contains + a message (e.g. "deleting"). )) The file-types that replace the bf(X) are: bf(f) for a file, a bf(d) for a @@ -1651,26 +1687,29 @@ a "?" (this can happen when talking to an older rsync). The attribute that is associated with each letter is as follows: quote(itemization( - it() A bf(c) means the checksum of the file is different and will be - updated by the file transfer (requires bf(--checksum)). - it() A bf(s) means the size of the file is different and will be updated + it() A bf(c) means either that a regular file has a different checksum + (requires bf(--checksum)) or that a symlink, device, or special file has + a changed value. + Note that if you are sending files to an rsync prior to 3.0.1, this + change flag will be present only for checksum-differing regular files. + it() A bf(s) means the size of a regular file is different and will be updated by the file transfer. it() A bf(t) means the modification time is different and is being updated to the sender's value (requires bf(--times)). An alternate value of bf(T) means that the modification time will be set to the transfer time, which happens - anytime a symlink is transferred, or when a regular file or device is - transferred without bf(--times). + when a file/symlink/device is updated without bf(--times) and when a + symlink is changed and the receiver can't set its time. + (Note: when using an rsync 3.0.0 client, you might see the bf(s) flag combined + with bf(t) instead of the proper bf(T) flag for this time-setting failure.) it() A bf(p) means the permissions are different and are being updated to the sender's value (requires bf(--perms)). it() An bf(o) means the owner is different and is being updated to the sender's value (requires bf(--owner) and super-user privileges). it() A bf(g) means the group is different and is being updated to the sender's value (requires bf(--group) and the authority to set the group). - it() The bf(u) slot is reserved for reporting update (access) time changes - (a feature that is not yet released). + it() The bf(u) slot is reserved for future use. it() The bf(a) means that the ACL information changed. - it() The bf(x) slot is reserved for reporting extended attribute changes - (a feature that is not yet released). + it() The bf(x) means that the extended attribute information changed. )) One other output is possible: when deleting files, the "%i" will output @@ -1726,14 +1765,14 @@ For a list of the possible escape characters, see the "log format" setting 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 the rsync +on the file transfer, allowing you to tell how effective rsync's delta-transfer algorithm is for your data. The current statistics are as follows: quote(itemization( it() bf(Number of files) is the count of all "files" (in the generic sense), which includes directories, symlinks, etc. it() bf(Number of files transferred) is the count of normal files that - were updated via the rsync algorithm, which does not include created + were updated via rsync's delta-transfer algorithm, which does not include created dirs, symlinks, etc. it() bf(Total file size) is the total sum of all file sizes in the transfer. This does not count any size for directories or special files, but does @@ -1794,7 +1833,7 @@ after it has served its purpose. Note that if bf(--whole-file) is specified (or implied), any partial-dir file that is found for a file that is being updated will simply be removed (since -rsync is sending files without using the delta transfer algorithm). +rsync is sending files without using rsync's delta-transfer algorithm). Rsync will create the em(DIR) if it is missing (just the last dir -- not the whole path). This makes it easy to use a relative path (such as @@ -1912,7 +1951,7 @@ sender's file, which is being reconstructed at a rate of 110.64 kilobytes per second, and the transfer will finish in 4 seconds if the current rate is maintained until the end. -These statistics can be misleading if the delta transfer algorithm is +These statistics can be misleading if rsync's delta-transfer algorithm is in use. For example, if the sender's file consists of the basis file followed by additional data, the reported rate will probably drop dramatically when the receiver gets to the literal data, and the transfer @@ -1939,6 +1978,8 @@ 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. +This option does not supply a password to a remote shell transport such as +ssh; to learn how to do that, consult the remote shell's documentation. When accessing an rsync daemon using a remote shell as the transport, this option only comes into effect after the remote shell finishes its authentication (i.e. if you have also specified a password in the daemon's @@ -2010,11 +2051,17 @@ dit(bf(--iconv=CONVERT_SPEC)) Rsync can convert filenames between character sets using this option. Using a CONVERT_SPEC of "." tells rsync to look up the default character-set via the locale setting. Alternately, you can fully specify what conversion to do by giving a local and a remote charset -separated by a comma (local first), e.g. bf(--iconv=utf8,iso88591). -Finally, you can specify a CONVERT_SPEC of "-" to turn off any conversion. +separated by a comma in the order bf(--iconv=LOCAL,REMOTE), e.g. +bf(--iconv=utf8,iso88591). This order ensures that the option +will stay the same whether you're pushing or pulling files. +Finally, you can specify either bf(--no-iconv) or a CONVERT_SPEC of "-" +to turn off any conversion. The default setting of this option is site-specific, and can also be affected via the RSYNC_ICONV environment variable. +For a list of what charset names your local iconv library supports, you can +run "iconv --list". + If you specify the bf(--protect-args) option (bf(-s)), rsync will translate the filenames you specify on the command-line that are being sent to the remote host. See also the bf(--files-from) option. @@ -2025,6 +2072,11 @@ specifying matching rules that can match on both sides of the transfer. For instance, you can specify extra include/exclude rules if there are filename differences on the two sides that need to be accounted for. +When you pass an bf(--iconv) option to an rsync daemon that allows it, the +daemon uses the charset specified in its "charset" configuration parameter +regardless of the remote charset you actually pass. Thus, you may feel free to +specify just the local charset for a daemon transfer (e.g. bf(--iconv=utf8)). + dit(bf(-4, --ipv4) or bf(-6, --ipv6)) Tells rsync to prefer IPv4/IPv6 when creating sockets. This only affects sockets that rsync has direct control over, such as the outgoing socket when directly contacting an @@ -2775,6 +2827,7 @@ dit(bf(23)) Partial transfer due to error dit(bf(24)) Partial transfer due to vanished source files dit(bf(25)) The --max-delete limit stopped deletions dit(bf(30)) Timeout in data send/receive +dit(bf(35)) Timeout waiting for daemon connection enddit() manpagesection(ENVIRONMENT VARIABLES) @@ -2794,7 +2847,8 @@ rsync daemon. You should set RSYNC_PROXY to a hostname:port pair. dit(bf(RSYNC_PASSWORD)) Setting RSYNC_PASSWORD to the required password allows you to run authenticated rsync connections to an rsync daemon without user intervention. Note that this does not supply a -password to a shell transport such as ssh. +password to a remote shell transport such as ssh; to learn how to do that, +consult the remote shell's documentation. dit(bf(USER) or bf(LOGNAME)) The USER or LOGNAME environment variables are used to determine the default username sent to an rsync daemon. If neither is set, the username defaults to "nobody". @@ -2828,7 +2882,7 @@ url(http://rsync.samba.org/)(http://rsync.samba.org/) manpagesection(VERSION) -This man page is current for version 3.0.0pre4 of rsync. +This man page is current for version 3.0.3pre2 of rsync. manpagesection(INTERNAL OPTIONS)