X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/fd2b6046cb0afc960da8cbd2c1dab40c786f8097..6f098b0f8c1c3582013f20970bf575ab487f6bda:/rsync.yo diff --git a/rsync.yo b/rsync.yo index e5869adf..13055a73 100644 --- a/rsync.yo +++ b/rsync.yo @@ -674,7 +674,7 @@ quote(tt( rsync -avR /foo/./bar/baz.c remote:/tmp/)) That would create /tmp/bar/baz.c on the remote machine. (Note that the dot must be followed by a slash, so "/foo/." would not be abbreviated.) -(2) For older rsync versions, you would need to use a chdir to limit the +For older rsync versions, you would need to use a chdir to limit the source path. For example, when pushing files: quote(tt( (cd /foo; rsync -avR bar/baz.c remote:/tmp/) )) @@ -756,8 +756,8 @@ This option is a transfer rule, not an exclude, so it doesn't affect the data that goes into the file-lists, and thus it doesn't affect deletions. It just limits the files that the receiver requests to be transferred. -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 +dit(bf(--inplace)) This option changes how rsync transfers a file when +its 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. @@ -776,7 +776,7 @@ 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 +This option is useful for transferring large files with block-based changes or appended data, and also on systems that are disk bound, not network bound. @@ -1015,7 +1015,7 @@ a normal user, see the bf(--fake-super) option. dit(bf(--chmod)) This option tells rsync to apply one or more comma-separated "chmod" strings to the permission of the files in the -transfer. The resulting value is treated as though it was the permissions +transfer. The resulting value is treated as though it were the permissions that the sending side supplied for the file, which means that this option can seem to have no effect on existing files if bf(--perms) is not enabled. @@ -1085,7 +1085,7 @@ all groups (not just the current user's groups) via the bf(--groups) option, and copying devices via the bf(--devices) option. This is useful for systems that allow such activities without being the super-user, and 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 +being run 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 @@ -1124,8 +1124,8 @@ up less space on the destination. Conflicts with bf(--inplace) because it's not possible to overwrite data in a sparse fashion. NOTE: Don't use this option when the destination is a Solaris "tmpfs" -filesystem. It doesn't seem to handle seeks over null regions -correctly and ends up corrupting the files. +filesystem. It seems to have problems seeking over null regions, +and ends up corrupting the files. dit(bf(-n, --dry-run)) This makes rsync perform a trial run that doesn't make any changes (and produces mostly the same output as a real run). It @@ -1135,19 +1135,20 @@ to do before one actually runs it. The output of bf(--itemize-changes) is supposed to be exactly the same on a dry run and a subsequent real run (barring intentional trickery and system -call failures); if it isn't, that's a bug. Other output is the same to the -extent practical, but may differ in some areas. Notably, a dry run does not +call failures); if it isn't, that's a bug. Other output should be mostly +unchanged, but may differ in some areas. Notably, a dry run does not send the actual data for file transfers, so bf(--progress) has no effect, 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. +where no file transfers were needed. 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 "disk" is actually a networked filesystem). This is the default when both -the source and destination are specified as local paths. +the source and destination are specified as local paths, but only if no +batch-writing option is in effect. dit(bf(-x, --one-file-system)) This tells rsync to avoid crossing a filesystem boundary when recursing. This does not limit the user's ability @@ -1219,7 +1220,7 @@ going to be deleted. If the sending side detects any I/O errors, then the deletion of any files at the destination will be automatically disabled. This is to prevent temporary filesystem failures (such as NFS errors) on the -sending side causing a massive deletion of files on the +sending side from causing a massive deletion of files on the destination. You can override this with the bf(--ignore-errors) option. The bf(--delete) option may be combined with one of the --delete-WHEN options @@ -1722,7 +1723,7 @@ 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). +"[:alpha:]", are supported, and '-' has no special meaning). The characters asterisk (*) and question-mark (?) have no special meaning. @@ -1731,10 +1732,32 @@ 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) +The default list of suffixes that will not be compressed is this (in this +version of rsync): + +bf(7z) +bf(ace) +bf(avi) +bf(bz2) +bf(deb) +bf(gpg) +bf(gz) +bf(iso) +bf(jpeg) +bf(jpg) +bf(lzma) +bf(lzo) +bf(mov) +bf(mp3) +bf(mp4) +bf(ogg) +bf(rar) +bf(rpm) +bf(rzip) +bf(tbz) +bf(tgz) +bf(z) +bf(zip) 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 @@ -2589,6 +2612,39 @@ itemization( explicitly included or it would be excluded by the "*") ) +The following modifiers are accepted after a "+" or "-": + +itemization( + it() A bf(/) specifies that the include/exclude rule should be matched + against the absolute pathname of the current item. For example, + "-/ /etc/passwd" would exclude the passwd file any time the transfer + was sending files from the "/etc" directory, and "-/ subdir/foo" + would always exclude "foo" when it is in a dir named "subdir", even + if "foo" is at the root of the current transfer. + it() A bf(!) specifies that the include/exclude should take effect if + the pattern fails to match. For instance, "-! */" would exclude all + non-directories. + it() A bf(C) is used to indicate that all the global CVS-exclude rules + should be inserted as excludes in place of the "-C". No arg should + follow. + it() An bf(s) is used to indicate that the rule applies to the sending + side. When a rule affects the sending side, it prevents files from + being transferred. The default is for a rule to affect both sides + unless bf(--delete-excluded) was specified, in which case default rules + become sender-side only. See also the hide (H) and show (S) rules, + which are an alternate way to specify sending-side includes/excludes. + it() An bf(r) is used to indicate that the rule applies to the receiving + side. When a rule affects the receiving side, it prevents files from + being deleted. See the bf(s) modifier for more info. See also the + protect (P) and risk (R) rules, which are an alternate way to + specify receiver-side includes/excludes. + it() A bf(p) indicates that a rule is perishable, meaning that it is + ignored in directories that are being deleted. For instance, the bf(-C) + option's default rules that exclude things like "CVS" and "*.o" are + marked as perishable, and will not prevent a directory that was removed + on the source from being deleted on the destination. +) + manpagesection(MERGE-FILE FILTER RULES) You can merge whole files into your filter rules by specifying either a @@ -2637,44 +2693,15 @@ itemization( "- foo + bar" is parsed as two rules (assuming that prefix-parsing wasn't also disabled). it() You may also specify any of the modifiers for the "+" or "-" rules - (below) in order to have the rules that are read in from the file - default to having that modifier set. For instance, "merge,-/ .excl" would + (above) in order to have the rules that are read in from the file + default to having that modifier set (except for the bf(!) modifier, which + would not be useful). For instance, "merge,-/ .excl" would treat the contents of .excl as absolute-path excludes, while "dir-merge,s .filt" and ":sC" would each make all their - per-directory rules apply only on the sending side. -) - -The following modifiers are accepted after a "+" or "-": - -itemization( - it() A bf(/) specifies that the include/exclude rule should be matched - against the absolute pathname of the current item. For example, - "-/ /etc/passwd" would exclude the passwd file any time the transfer - was sending files from the "/etc" directory, and "-/ subdir/foo" - would always exclude "foo" when it is in a dir named "subdir", even - if "foo" is at the root of the current transfer. - it() A bf(!) specifies that the include/exclude should take effect if - the pattern fails to match. For instance, "-! */" would exclude all - non-directories. - it() A bf(C) is used to indicate that all the global CVS-exclude rules - should be inserted as excludes in place of the "-C". No arg should - follow. - it() An bf(s) is used to indicate that the rule applies to the sending - side. When a rule affects the sending side, it prevents files from - being transferred. The default is for a rule to affect both sides - unless bf(--delete-excluded) was specified, in which case default rules - become sender-side only. See also the hide (H) and show (S) rules, - which are an alternate way to specify sending-side includes/excludes. - it() An bf(r) is used to indicate that the rule applies to the receiving - side. When a rule affects the receiving side, it prevents files from - being deleted. See the bf(s) modifier for more info. See also the - protect (P) and risk (R) rules, which are an alternate way to - specify receiver-side includes/excludes. - it() A bf(p) indicates that a rule is perishable, meaning that it is - ignored in directories that are being deleted. For instance, the bf(-C) - option's default rules that exclude things like "CVS" and "*.o" are - marked as perishable, and will not prevent a directory that was removed - on the source from being deleted on the destination. + per-directory rules apply only on the sending side. If the merge rule + specifies sides to affect (via the bf(s) or bf(r) modifier or both), + then the rules in the file must not specify sides (via a modifier or + a rule prefix such as bf(hide)). ) Per-directory rules are inherited in all subdirectories of the directory @@ -2997,9 +3024,9 @@ bf(--links). If bf(--copy-links) is specified, then symlinks are "collapsed" by copying their referent, rather than the symlink. -rsync also distinguishes "safe" and "unsafe" symbolic links. An -example where this might be used is a web site mirror that wishes -ensure the rsync module they copy does not include symbolic links to +Rsync can also distinguish "safe" and "unsafe" symbolic links. An +example where this might be used is a web site mirror that wishes to +ensure that the rsync module that is copied does not include symbolic links to bf(/etc/passwd) in the public section of the site. Using bf(--copy-unsafe-links) will cause any links to be copied as the file they point to on the destination. Using bf(--safe-links) will cause @@ -3166,7 +3193,7 @@ Jean-loup Gailly and Mark Adler. manpagesection(THANKS) -Especial thanks go out to: John Van Essen, Matt McCutchen, Wesley W. Terpstra, +Special thanks go out to: John Van Essen, Matt McCutchen, Wesley W. Terpstra, David Dykstra, Jos Backus, Sebastian Krahmer, Martin Pool, and our gone-but-not-forgotten compadre, J.W. Schultz.