X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/332cf6df7c32dbaa47cbfe515121da7bd53974e8..6e058b4b60e01b874bfe6a9814b1d6b1944d6ae7:/rsync.yo diff --git a/rsync.yo b/rsync.yo index dad93e8d..b1279e5d 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( @@ -330,8 +336,8 @@ to the detailed description below for a complete description. verb( --devices preserve device files (super-user only) --specials preserve special files -D same as --devices --specials - -t, --times preserve times - -O, --omit-dir-times omit directories when preserving times + -t, --times preserve modification times + -O, --omit-dir-times omit directories from --times --super receiver attempts super-user activities --fake-super store/recover privileged attrs using xattrs -S, --sparse handle sparse files efficiently @@ -471,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 @@ -658,7 +664,7 @@ if no -bf(-backup-dir) was specified, otherwise it is an empty string. dit(bf(-u, --update)) This forces rsync to skip any files which exist on the destination and have a modified time that is newer than the source -file. (If an existing destination file has a modify time equal to the +file. (If an existing destination file has a modification time equal to the source file's, it will be updated if the sizes are different.) In the current implementation of bf(--update), a difference of file format @@ -927,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 @@ -988,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. @@ -1267,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,9 +1537,9 @@ quote(itemization( 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 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). + 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). 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 @@ -2048,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 '[' . @@ -2079,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. ) @@ -2122,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