X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/c64ff141b83dfb2bba32079db8309df176988388..d15f2ff0cf372be49d57b1d7884557ddbe1a4d9c:/rsync.yo diff --git a/rsync.yo b/rsync.yo index e9d1e20d..3af7e1b7 100644 --- a/rsync.yo +++ b/rsync.yo @@ -21,7 +21,7 @@ rsync [OPTION]... rsync://[USER@]HOST[:PORT]/SRC [DEST] manpagedescription() -rsync is a program that behaves in much the same way that rcp does, +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. @@ -31,6 +31,12 @@ 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. + Some of the additional features of rsync are: itemization( @@ -333,6 +339,7 @@ to the detailed description below for a complete description. verb( -t, --times preserve times -O, --omit-dir-times omit directories when preserving times --super receiver attempts super-user activities + --fake-super store/recover privileged attrs using xattrs -S, --sparse handle sparse files efficiently -n, --dry-run show what would have been transferred -W, --whole-file copy files whole (without rsync algorithm) @@ -401,6 +408,7 @@ to the detailed description below for a complete description. verb( --only-write-batch=FILE like --write-batch but w/o updating dest --read-batch=FILE read a batched update from FILE --protocol=NUM force an older protocol version to be used + --iconv=CONVERT_SPEC request charset conversion of filesnames --checksum-seed=NUM set block/file checksum seed (advanced) -4, --ipv4 prefer IPv4 -6, --ipv6 prefer IPv6 @@ -469,16 +477,16 @@ a limitation in the rsync protocol), so omit this option if you want to request the list of modules from the daemon. dit(bf(-I, --ignore-times)) Normally rsync will skip any files that are -already the same size and have the same modification time-stamp. +already the same size and have the same modification timestamp. This option turns off this "quick check" behavior, causing all files to be updated. -dit(bf(--size-only)) Normally rsync will not transfer any files that are -already the same size and have the same modification time-stamp. With the -bf(--size-only) option, files will not be transferred if they have the same size, -regardless of timestamp. This is useful when starting to use rsync -after using another mirroring system which may not preserve timestamps -exactly. +dit(bf(--size-only)) This modifies rsync's "quick check" algorithm for +finding files that need to be transferred, changing it from the default of +transferring files with either a changed size or a changed last-modified +time to just looking for files that have changed in size. This is useful +when starting to use rsync after using another mirroring system which may +not preserve timestamps exactly. dit(bf(--modify-window)) When comparing two timestamps, rsync treats the timestamps as being equal if they differ by no more than the modify-window @@ -865,7 +873,7 @@ permission value can be applied to the files in the transfer. dit(bf(-o, --owner)) This option causes rsync to set the owner of the destination file to be the same as the source file, but only if the receiving rsync is being run as the super-user (see also the bf(--super) -option to force rsync to attempt super-user activities). +and bf(--fake-super) options). Without this option, the owner is set to the invoking user on the receiving side. @@ -888,7 +896,7 @@ default, but may fall back to using the ID number in some circumstances dit(bf(--devices)) This option causes rsync to transfer character and block device files to the remote system to recreate these devices. This option has no effect if the receiving rsync is not run as the -super-user and bf(--super) is not specified. +super-user (see also the bf(--super) and bf(--fake-super) options). dit(bf(--specials)) This option causes rsync to transfer special files such as named sockets and fifos. @@ -918,6 +926,34 @@ also for ensuring that you will get errors if the receiving side isn't being running as the super-user. To turn off super-user activities, the super-user can use bf(--no-super). +dit(bf(--fake-super)) When this option is enabled, rsync simulates +super-user activities by saving/restoring the privileged attributes via a +special extended attribute that is attached to each file (as needed). This +includes the file's owner and group (if it is not the default), the file's +device info (device & special files are created as empty text files), and +any permission bits that we won't allow to be set on the real file (e.g. +the real file gets u-s,g-s,o-t for safety) or that would limit the owner's +access (since the real super-user can always access/change a file or +directory, the files we create can always be accessed/changed by the +creating user). + +The bf(--fake-super) option only affects the side where the option is used. +To affect the remote side of a remote-shell connection, specify an rsync +path: + +quote(tt( rsync -av --rsync-path="rsync --fake-super" /src/ host:/dest/)) + +Since there is only one "side" in a local copy, this option affects both +the sending and recieving of files. You'll need to specify a copy using +"localhost" if you need to avoid this. Note, however, that it is always +safe to copy from some non-fake-super files into some fake-super files +using a local bf(--fake-super) command because the non-fake source files +will just have their normal attributes. + +This option is overridden by both bf(--super) and bf(--no-super). + +See also the "fake super" setting in the daemon's rsyncd.conf file. + dit(bf(-S, --sparse)) Try to handle sparse files efficiently so they take up less space on the destination. Conflicts with bf(--inplace) because it's not possible to overwrite data in a sparse fashion. @@ -1837,6 +1873,24 @@ bf(--read-batch) option, you should use "--protocol=28" when creating the batch file to force the older protocol version to be used in the batch file (assuming you can't upgrade the rsync on the reading system). +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. +The default setting of this option is site-specific, and can also be +affected via the RSYNC_ICONV environment variable. + +Note that rsync does not do any conversion of names in filter files +(including include/exclude files), in a files-from file, nor those +specified on the command line. It is up to you to ensure that you're +requesting the right names from a remote server, and you can specify +extra include/exclude rules if there are filename differences on the +two sides that need to be accounted for. (In the future there may be +a way to specify a UTF-8 filter rule that gets auto-converted to the +local side's character set.) + 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 @@ -2588,6 +2642,8 @@ startdit() 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. 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.