X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/2dc3db2a3e5d19f1d6197df054303aed6e2c3236..7a28d18448acbe1620a57c3c6b3d7c513aa67f8b:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 2a266d74..834c71be 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 @@ -533,6 +534,23 @@ details). dit(bf(-r, --recursive)) This tells rsync to copy directories recursively. See also bf(--dirs) (bf(-d)). +Beginning with rsync 3.0.0, the recursive algorithm used is now an +incremental scan that uses much less memory than before and begins the +transfer after the scanning of the first few directories have been +completed. This incremental scan only affects our recursion algorithm, and +does not change a non-recursive transfer (e.g. when using a fully-specified +bf(--files-from) list). It is also only possible when both ends of the +transfer are at least version 3.0.0. + +Some options require rsync to know the full file list, so these options +disable the incremental recursion mode. These include: bf(--delete-before), +bf(--delete-after), bf(--delay-updates), and (currently) bf(--hard-links). +Because of this, the default delete mode when you specify bf(--delete) is now +bf(--delete-during) when both ends of the connection are at least 3.0.0 +(use bf(--del) or bf(--delete-during) to request this improved deletion mode +explicitly). See also the bf(--delete-delay) option that is a better choice +than using bf(--delete-after). + dit(bf(-R, --relative)) Use relative paths. This means that the full path names specified on the command line are sent to the server rather than just the last parts of the filenames. This is particularly useful when @@ -610,7 +628,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 @@ -941,8 +959,8 @@ option or mark the rules as only matching on the sending side (see the include/exclude modifiers in the FILTER RULES section). Prior to rsync 2.6.7, this option would have no effect unless bf(--recursive) -was in effect. Beginning with 2.6.7, deletions will also occur when bf(--dirs) -(bf(-d)) is in effect, but only for directories whose contents are being copied. +was enabled. Beginning with 2.6.7, deletions will also occur when bf(--dirs) +(bf(-d)) is enabled, but only for directories whose contents are being copied. This option can be dangerous if used incorrectly! It is a very good idea to run first using the bf(--dry-run) option (bf(-n)) to see what files would be @@ -956,20 +974,22 @@ 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 without conflict, as well as bf(--delete-excluded). However, if none of the ---delete-WHEN options are specified, rsync will currently choose the -bf(--delete-before) algorithm. A future version may change this to choose the -bf(--delete-during) algorithm. See also bf(--delete-after). +--delete-WHEN options are specified, rsync will choose the +bf(--delete-during) algorithm when talking to an rsync 3.0.0 or newer, and +the bf(--delete-before) algorithm when talking to an older rsync. See also +bf(--delete-delay) and bf(--delete-after). dit(bf(--delete-before)) Request that the file-deletions on the receiving -side be done before the transfer starts. This is the default if bf(--delete) -or bf(--delete-excluded) is specified without one of the --delete-WHEN options. +side be done before the transfer starts. See bf(--delete) (which is implied) for more details on file-deletion. Deleting before the transfer is helpful if the filesystem is tight for space and removing extraneous files would help to make the transfer possible. However, it does introduce a delay before the start of the transfer, and this delay might cause the transfer to timeout (if bf(--timeout) was -specified). +specified). It also forces rsync to use the old, non-incremental recursion +algorithm that requires rsync to scan all the files in the transfer into +memory at once (see bf(--recursive)). dit(bf(--delete-during, --del)) Request that the file-deletions on the receiving side be done incrementally as the transfer happens. This is @@ -977,11 +997,22 @@ 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 during the transfer, and then removed after the transfer +completes. If the number of removed files overflows an internal buffer, a +temporary file will be created on the receiving side to hold the names (it +is removed while open, so you shouldn't see it during the transfer). If +the creation of the temporary file fails, rsync will try to fall back to +using bf(--delete-after) (which it cannot do if bf(--recursive) is doing an +incremental scan). + 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 you want their exclusions to take effect for the delete phase of the -current transfer. +current transfer. It also forces rsync to use the old, non-incremental +recursion algorithm that requires rsync to scan all the files in the +transfer into memory at once (see bf(--recursive)). See bf(--delete) (which is implied) for more details on file-deletion. dit(bf(--delete-excluded)) In addition to deleting the files on the @@ -1086,16 +1117,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). @@ -1668,7 +1700,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 @@ -1709,12 +1741,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 @@ -1967,8 +2001,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 @@ -2083,13 +2117,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 @@ -2106,6 +2140,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 @@ -2193,7 +2232,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) @@ -2439,7 +2478,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