X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/9439c0cb5a4b020b9bfcfe0351e33c17b9c53b54..8e3b627d0733c3b21312c707ef03dd9686bb453c:/rsync.yo diff --git a/rsync.yo b/rsync.yo index fd229d6e..3be9dd64 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( @@ -402,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 @@ -470,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 @@ -926,9 +933,8 @@ 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). +access (since the real super-user can always access/change a file, 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 @@ -987,12 +993,20 @@ dit(bf(--existing, --ignore-non-existing)) This tells rsync to skip creating files (including directories) that do not exist yet on the destination. If this option is combined with the bf(--ignore-existing) option, no files will be updated -(which can be useful if all you want to do is to delete extraneous files). +(which can be useful if all you want to do is delete extraneous files). dit(bf(--ignore-existing)) This tells rsync to skip updating files that already exist on the destination (this does em(not) ignore existing directories, or nothing would get done). See also bf(--existing). +This option can be useful for those doing backups using the bf(--link-dest) +option when they need to continue a backup run that got interrupted. Since +a bf(--link-dest) run is copied into a new directory hierarchy (when it is +used properly), using bf(--ignore existing) will ensure that the +already-handled files don't get tweaked (which avoids a change in +permissions on the hard-linked files). This does mean that this option +is only looking at the existing files in the destination hierarchy itself. + dit(bf(--remove-source-files)) This tells rsync to remove from the sending side the files (meaning non-directories) that are a part of the transfer and have been successfully duplicated on the receiving side. @@ -1266,7 +1280,7 @@ quote(itemization( bf(--files-from), as does bf(--no-R) and all other options). )) -The file names that are read from the FILE are all relative to the +The filenames that are read from the FILE are all relative to the source dir -- any leading slashes are removed and no ".." references are allowed to go higher than the source dir. For example, take this command: @@ -1524,8 +1538,8 @@ quote(itemization( 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 time will be set to the transfer time, which happens - anytime a symlink is transferred, or when a file or device is transferred - without bf(--times). + anytime a symlink is transferred, or when a regular file or device is + transferred without bf(--times). 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 @@ -1866,6 +1880,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 @@ -2029,20 +2061,19 @@ itemization( particular spot in the hierarchy of files, otherwise it is matched against the end of the pathname. This is similar to a leading ^ in regular expressions. - Thus "/foo" would match a file named "foo" at either the "root of the + Thus "/foo" would match a name of "foo" at either the "root of the transfer" (for a global rule) or in the merge-file's directory (for a per-directory rule). - An unqualified "foo" would match any file or directory named "foo" - anywhere in the tree because the algorithm is applied recursively from - the + An unqualified "foo" would match a name of "foo" anywhere in the + tree because the algorithm is applied recursively from the top down; it behaves as if each path component gets a turn at being the - end of the file name. Even the unanchored "sub/foo" would match at + end of the filename. Even the unanchored "sub/foo" would match at any point in the hierarchy where a "foo" was found within a directory named "sub". See the section on ANCHORING INCLUDE/EXCLUDE PATTERNS for a full discussion of how to specify a pattern that matches at the root of the transfer. it() if the pattern ends with a / then it will only match a - directory, not a file, link, or device. + directory, not a regular file, symlink, or device. it() rsync chooses between doing a simple string match and wildcard matching by checking if the pattern contains one of these three wildcard characters: '*', '?', and '[' . @@ -2060,7 +2091,7 @@ itemization( can actually be any portion of a path from the starting directory on down.) it() a trailing "dir_name/***" will match both the directory (as if - "dir_name/" had been specified) and all the files in the directory + "dir_name/" had been specified) and everything in the directory (as if "dir_name/**" had been specified). This behavior was added in version 2.6.7. ) @@ -2103,7 +2134,7 @@ tt(- *)nl() Here are some examples of exclude/include matching: itemization( - it() "- *.o" would exclude all filenames matching *.o + it() "- *.o" would exclude all names matching *.o it() "- /foo" would exclude a file (or directory) named foo in the transfer-root directory it() "- foo/" would exclude any directory named foo @@ -2617,6 +2648,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.