X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/8e2771aa6e1fe242c0ad2919d2721e800d505d8e..refs/heads/hacks/missing-args-b3.0.x:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 5db80b47..0f22dbec 100644 --- a/rsync.yo +++ b/rsync.yo @@ -1,5 +1,5 @@ mailto(rsync-bugs@samba.org) -manpage(rsync)(1)(28 Dec 2008)()() +manpage(rsync)(1)(8 May 2009)()() manpagename(rsync)(a fast, versatile, remote (and local) file-copying tool) manpagesynopsis() @@ -372,6 +372,8 @@ to the detailed description below for a complete description. verb( --delete-delay find deletions during, delete after --delete-after receiver deletes after transfer, not before --delete-excluded also delete excluded files from dest dirs + --ignore-missing-args ignore missing source args without error + --delete-missing-args delete missing source args from destination --ignore-errors delete even if there are I/O errors --force force deletion of dirs even if not empty --max-delete=NUM don't delete more than NUM files @@ -704,6 +706,10 @@ 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. +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 a new copy of the file and moving it into place when it is complete, rsync @@ -1014,7 +1020,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 @@ -1102,10 +1108,18 @@ 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 delete extraneous files). +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(--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 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. + 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 @@ -1201,6 +1215,23 @@ this way on the receiver, and for a way to protect files from bf(--delete-excluded). See bf(--delete) (which is implied) for more details on file-deletion. +dit(bf(--ignore-missing-args)) When rsync is first processing the explicitly +requested source files (e.g. command-line arguments or bf(--files-from) +entries), it is normally an error if the file cannot be found. This option +suppresses that error, and does not try to transfer the file. This does not +affect subsequent vanished-file errors if a file was initially found to be +present and later is no longer there. + +dit(bf(--delete-missing-args)) This option takes the behavior of (the implied) +bf(--ignore-missing-args) option a step farther: each missing arg will become +a deletion request of the corresponding destination file on the receiving side +(should it exist). If the destination file is a non-empty directory, it will +only be successfully deleted if --force or --delete are in effect. Other than +that, this option is independent of any other type of delete processing. + +The missing source files are represented by special file-list entries which +display as a "*missing" entry in the bf(--list-only) output. + dit(bf(--ignore-errors)) Tells bf(--delete) to go ahead and delete files even when there are I/O errors. @@ -1228,6 +1259,10 @@ file that is larger than the specified SIZE. The SIZE value can be suffixed with a string to indicate a size multiplier, and may be a fractional value (e.g. "bf(--max-size=1.5m)"). +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. + The suffixes are as follows: "K" (or "KiB") is a kibibyte (1024), "M" (or "MiB") is a mebibyte (1024*1024), and "G" (or "GiB") is a gibibyte (1024*1024*1024). @@ -1242,7 +1277,7 @@ Examples: --max-size=1.5mb-1 is 1499999 bytes, and --max-size=2g+1 is dit(bf(--min-size=SIZE)) This tells rsync to avoid transferring any file that is smaller than the specified SIZE, which can help in not transferring small, junk files. -See the bf(--max-size) option for a description of SIZE. +See the bf(--max-size) option for a description of SIZE and other information. dit(bf(-B, --block-size=BLOCKSIZE)) This forces the block size used in rsync's delta-transfer algorithm to a fixed value. It is normally selected based on @@ -1935,11 +1970,16 @@ creation of a bunch of useless directories when the sending rsync is recursively scanning a hierarchy of files using include/exclude/filter rules. +Note that the use of transfer rules, such as the bf(--min-size) option, does +not affect what goes into the file list, and thus does not leave directories +empty, even if none of the files in a directory match the transfer rule. + Because the file-list is actually being pruned, this option also affects what directories get deleted when a delete is active. However, keep in mind that excluded files and directories can prevent existing items from -being deleted (because an exclude hides source files and protects -destination files). +being deleted due to an exclude both hiding source files and protecting +destination files. See the perishable filter-rule option for how to avoid +this. You can prevent the pruning of certain empty directories from the file-list by using a global "protect" filter. For instance, this option would ensure @@ -2359,6 +2399,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 @@ -2407,46 +2480,13 @@ 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 + (above) in order to have the rules that are read in from the file default to having that modifier set. 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 are inherited in all subdirectories of the directory where the merge-file was found unless the 'n' modifier was used. Each subdirectory's rules are prefixed to the inherited per-directory rules @@ -2903,7 +2943,7 @@ url(http://rsync.samba.org/)(http://rsync.samba.org/) manpagesection(VERSION) -This man page is current for version 3.0.5 of rsync. +This man page is current for version 3.0.6 of rsync. manpagesection(INTERNAL OPTIONS)