X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/1874f7e2e176dc7a3c2f05687a28bcbfe5964b06..e6109f496cd50da4da536241634cd7774b347ca8:/rsync.yo diff --git a/rsync.yo b/rsync.yo index aa9ccc8b..6d3973e0 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,7 +31,7 @@ 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. -It finds files that need to be transferred using a "quick check" algorithm +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 @@ -336,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 @@ -378,6 +378,7 @@ to the detailed description below for a complete description. verb( --link-dest=DIR hardlink to files in DIR when unchanged -z, --compress compress file data during the transfer --compress-level=NUM explicitly set compression level + --skip-compress=LIST skip compressing files with suffix in LIST -C, --cvs-exclude auto-ignore files in the same way CVS does -f, --filter=RULE add a file-filtering RULE -F same as --filter='dir-merge /.rsync-filter' @@ -484,7 +485,7 @@ be updated. 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 transferring files that have a changed size. This is useful +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. @@ -664,16 +665,15 @@ 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 -between the sender and receiver is always -considered to be important enough for an update, no matter what date -is on the objects. In other words, if the source has a directory or a -symlink where the destination has a file, the transfer would occur -regardless of the timestamps. This might change in the future (feel -free to comment on this on the mailing list if you have an opinion). +Note that this does not affect the copying of symlinks or other special +files. Also, a difference of file format between the sender and receiver +is always considered to be important enough for an update, no matter what +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 @@ -933,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 @@ -994,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. @@ -1092,13 +1099,15 @@ using bf(--delete-after), and it used to be non-functional unless the bf(--recursive) option was also enabled. dit(bf(--max-delete=NUM)) This tells rsync not to delete more than NUM -files or directories. -Beginning with version 3.0.0, you may specify bf(--max-delete=0) to -be warned about any extraneous files in the destination, but be very -careful to never specify a 0 value to an older rsync client, or the -option will be silently ignored. (A 3.0.0 client will die with an -error if the remote rsync is not new enough to handle the situation.) -This is useful when mirroring very large trees to prevent disasters. +files or directories. If that limit is exceeded, a warning is output +and rsync exits with an error code of 25 (new for 3.0.0). + +Also new for version 3.0.0, you may specify bf(--max-delete=0) to be warned +about any extraneous files in the destination without removing any of them. +Older clients interpreted this as "unlimited", so if you don't know what +version the client is, you can use the less obvious bf(--max-delete=-1) as +a backward-compatible way to specify that no deletions be allowed (though +older versions didn't warn when the limit was exceeded). 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 @@ -1273,7 +1282,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: @@ -1431,10 +1440,40 @@ be achieved by using a compressing remote shell or a compressing transport because it takes advantage of the implicit information in the matching data blocks that are not explicitly sent over the connection. +See the bf(--skip-compress) option for the default list of file suffixes +that will not be compressed. + dit(bf(--compress-level=NUM)) Explicitly set the compression level to use (see bf(--compress)) instead of letting it default. If NUM is non-zero, the bf(--compress) option is implied. +dit(bf(--skip-compress=LIST)) Override the list of file suffixes that will +not be compressed. The bf(LIST) should be one or more file suffixes +(without the dot) separated by slashes (/). + +You may specify an empty string to indicate that no file should be skipped. + +Simple character-class matching is supported: each must consist of a list +of letters inside the square brackets (e.g. no special classes, such as +"[:alpha:]", are supported). + +The characters asterisk (*) and question-mark (?) have no special meaning. + +Here's an example that specifies 6 suffixes to skip (since 1 of the 5 rules +matches 2 suffixes): + +verb( --skip-compress=gz/jpg/mp[34]/7z/bz2) + +The default list of suffixes that will not be compressed is this (several +of these are newly added for 3.0.0): + +verb( gz/zip/z/rpm/deb/iso/bz2/t[gb]z/7z/mp[34]/mov/avi/ogg/jpg/jpeg) + +This list will be replaced by your bf(--skip-compress) list in all but one +situation: a copy from a daemon rsync will add your skipped suffixes to +its list of non-compressing files (and its list may be configured to a +different default). + dit(bf(--numeric-ids)) With this option rsync will transfer numeric group and user IDs rather than using user and group names and mapping them at both ends. @@ -1530,9 +1569,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 @@ -2054,20 +2093,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 '[' . @@ -2085,7 +2123,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. ) @@ -2128,7 +2166,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