Improved the docs on --delete and --delete-after.

diff --git a/rsync.yo b/rsync.yo
index 2d7b649..589545a 100644 (file)
--- a/rsync.yo
+++ b/rsync.yo
@@ -658,17 +658,22 @@ file that is larger than the specified SIZE. The SIZE value can be
 suffixed with a letter to indicate a size multiplier (K, M, or G) and
 may be a fractional value (e.g. "--max-size=1.5m").
 
-dit(bf(--delete)) This tells rsync to delete any files on the receiving
-side that aren't on the sending side.   Files that are excluded from
-transfer are excluded from being deleted unless you use --delete-excluded.
+dit(bf(--delete)) This tells rsync to delete extraneous files from the
+receiving side (ones that aren't on the sending side), but only for the
+directories that are being synchronized.  You must have asked rsync to
+send the whole directory (e.g. "dir" or "dir/") without using a wildcard
+for the directory's contents (e.g. "dir/*") since the wildcard is expanded
+by the shell and rsync thus gets a request to transfer those files, not
+the files' parent directory.  Files that are excluded from transfer are
+excluded from being deleted unless you use --delete-excluded.
 
 This option has no effect if directory recursion is not selected.
 
 This option can be dangerous if used incorrectly!  It is a very good idea
-to run first using the dry run option (-n) to see what files would be
+to run first using the --dry-run option (-n) to see what files would be
 deleted to make sure important files aren't listed.
 
-If the sending side detects any I/O errors then the deletion of any
+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
@@ -684,6 +689,10 @@ receiving side before transferring files to try to ensure that there is
 sufficient space on the receiving filesystem. If you want to delete
 after transferring, use the --delete-after switch. Implies --delete.
 
+One reason to use --delete-after is to avoid a delay before the start of
+the transfer (while the receiving side is scanned for deletions) as this
+delay might cause the transfer to timeout.  
+
 dit(bf(--ignore-errors)) Tells --delete to go ahead and delete files
 even when there are I/O errors.