X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/0c6d79528ac651ef064173327d769ba7a2b338ab..42c6b139019f7417a5067cdb93ad3f2452a69e7c:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 05d18936..b4fcb261 100644 --- a/rsync.yo +++ b/rsync.yo @@ -345,6 +345,7 @@ to the detailed description below for a complete description. verb( --delete delete extraneous files from dest dirs --delete-before receiver deletes before transfer (default) --delete-during receiver deletes during xfer, not before + --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-errors delete even if there are I/O errors @@ -391,7 +392,7 @@ to the detailed description below for a complete description. verb( --out-format=FORMAT output updates using the specified FORMAT --log-file=FILE log what we're doing to the specified FILE --log-file-format=FMT log updates using the specified FMT - --password-file=FILE read password from FILE + --password-file=FILE read daemon-access password from FILE --list-only list the files instead of copying them --bwlimit=KBPS limit I/O bandwidth; KBytes per second --write-batch=FILE write a batched update to FILE @@ -610,7 +611,7 @@ Note that if you don't specify bf(--backup-dir), (1) the bf(--omit-dir-times) option will be implied, and (2) if bf(--delete) is also in effect (without bf(--delete-excluded)), rsync will add a "protect" filter-rule for the backup suffix to the end of all your existing excludes -(e.g. -f "P *~"). This will prevent previously backed-up files from being +(e.g. bf(-f "P *~")). This will prevent previously backed-up files from being deleted. Note that if you are supplying your own filter rules, you may need to manually insert your own exclude/protect rule somewhere higher up in the list so that it has a high enough priority to be effective (e.g., if @@ -977,6 +978,12 @@ a faster method than choosing the before- or after-transfer algorithm, but it is only supported beginning with rsync version 2.6.4. See bf(--delete) (which is implied) for more details on file-deletion. +dit(bf(--delete-delay)) Request that the file-deletions on the receiving +side be computed incrementally as the transfer happens, and then removed +after the transfer completes. A temporary file will be created on the +receiving side to hold the names, but it is removed while open, so you +won't see it during the transfer. + dit(bf(--delete-after)) Request that the file-deletions on the receiving side be done after the transfer has completed. This is useful if you are sending new per-directory merge files as a part of the transfer and @@ -1004,7 +1011,12 @@ 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 (NUM must be non-zero). +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. dit(bf(--max-size=SIZE)) This tells rsync to avoid transferring any @@ -1081,16 +1093,17 @@ quote(tt( rsync -avR --rsync-path="cd /a/b && rsync" hst:c/d /e/)) dit(bf(-C, --cvs-exclude)) This is a useful shorthand for excluding a broad range of files that you often don't want to transfer between -systems. It uses the same algorithm that CVS uses to determine if +systems. It uses a similar algorithm to CVS to determine if a file should be ignored. -The exclude list is initialized to: +The exclude list is initialized to exclude the following items (these +initial items are marked as perishable -- see the FILTER RULES section): quote(quote(tt(RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state .nse_depinfo *~ #* .#* ,* _$* *$ *.old *.bak *.BAK *.orig *.rej -.del-* *.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln core .svn/))) +.del-* *.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln core .svn/ .bzr/))) -then files listed in a $HOME/.cvsignore are added to the list and any +then, files listed in a $HOME/.cvsignore are added to the list and any files listed in the CVSIGNORE environment variable (all cvsignore names are delimited by whitespace). @@ -1663,7 +1676,7 @@ that any superfluous files and directories in the destination are removed quote( rsync -avm --del --include='*.pdf' -f 'hide,! */' src/ dest) If you didn't want to remove superfluous destination files, the more -time-honored options of "--include='*/' --exclude='*'" would work fine +time-honored options of "bf(--include='*/' --exclude='*')" would work fine in place of the hide-filter (if that is more natural to you). dit(bf(--progress)) This option tells rsync to print information @@ -1704,12 +1717,14 @@ dit(bf(-P)) The bf(-P) option is equivalent to bf(--partial) bf(--progress). It purpose is to make it much easier to specify these two options for a long transfer that may be interrupted. -dit(bf(--password-file)) This option allows you to provide a password -in a file for accessing a remote rsync daemon. Note that this option -is only useful when accessing an rsync daemon using the built in -transport, not when using a remote shell as the transport. The file -must not be world readable. It should contain just the password as a -single line. +dit(bf(--password-file)) This option allows you to provide a password in a +file for accessing an rsync daemon. The file must not be world readable. +It should contain just the password as a single line. + +When accessing an rsync daemon using a remote shell as the transport, this +option only comes into effect after the remote shell finishes its +authentication (i.e. if you have also specified a password in the daemon's +config file). dit(bf(--list-only)) This option will cause the source files to be listed instead of transferred. This option is inferred if there is a single source @@ -1962,8 +1977,8 @@ itemization( 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 - (as if "dir_name/**" had been specified). (This behavior is new for - version 2.6.7.) + (as if "dir_name/**" had been specified). This behavior was added in + version 2.6.7. ) Note that, when using the bf(--recursive) (bf(-r)) option (which is implied by @@ -2078,13 +2093,13 @@ itemization( The following modifiers are accepted after a "+" or "-": itemization( - it() A "/" specifies that the include/exclude rule should be matched + 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 "!" specifies that the include/exclude should take effect if + 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 @@ -2101,6 +2116,11 @@ itemization( 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 @@ -2188,7 +2208,7 @@ that follow the :C instead of being subservient to all your rules. To affect the other CVS exclude rules (i.e. the default list of exclusions, the contents of $HOME/.cvsignore, and the value of $CVSIGNORE) you should omit the bf(-C) command-line option and instead insert a "-C" rule into -your filter rules; e.g. "--filter=-C". +your filter rules; e.g. "bf(--filter=-C)". manpagesection(LIST-CLEARING FILTER RULE) @@ -2434,7 +2454,7 @@ unsafe links to be omitted altogether. (Note that you must specify bf(--links) for bf(--safe-links) to have any effect.) Symbolic links are considered unsafe if they are absolute symlinks -(start with bf(/)), empty, or if they contain enough bf("..") +(start with bf(/)), empty, or if they contain enough ".." components to ascend from the directory being copied. Here's a summary of how the symlink options are interpreted. The list is