- Renamed set_perms() to set_file_attrs().

[rsync/rsync.git] / rsync.yo

diff --git a/rsync.yo b/rsync.yo
index f8d3f1e..087912b 100644 (file)
--- a/rsync.yo
+++ b/rsync.yo
@@ -349,6 +349,7 @@ to the detailed description below for a complete description.  verb(
      --partial               keep partially transferred files
      --partial-dir=DIR       put a partially transferred file into DIR
      --delay-updates         put all updated files into place at end
+ -m, --prune-empty-dirs      prune empty directory chains from file-list
      --numeric-ids           don't map uid/gid values by user/group name
      --timeout=TIME          set I/O timeout in seconds
  -I, --ignore-times          don't skip files that match size and time
@@ -735,7 +736,7 @@ 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
 super-user can use bf(--no-super).
 
-dit(bf(--chmod)) This options tells rsync to apply the listed "chmod" pattern
+dit(bf(--chmod)) This option tells rsync to apply the listed "chmod" pattern
 to the permission of the files on the destination.  In addition to the normal
 parsing rules specified in the chmod manpage, you can specify an item that
 should only apply to a directory by prefixing it with a 'D', or specify an
@@ -853,7 +854,7 @@ See bf(--delete) (which is implied) for more details on file-deletion.
 dit(bf(--ignore-errors)) Tells bf(--delete) to go ahead and delete files
 even when there are I/O errors.
 
-dit(bf(--force)) This options tells rsync to delete directories even if
+dit(bf(--force)) This option tells rsync to delete directories even if
 they are not empty when they are to be replaced by non-directories.  This
 is only relevant without bf(--delete) because deletions are now done depth-first.
 Requires the bf(--recursive) option (which is implied by bf(-a)) to have any effect.
@@ -1385,6 +1386,36 @@ See also the "atomic-rsync" perl script in the "support" subdir for an
 update algorithm that is even more atomic (it uses bf(--link-dest) and a
 parallel hierarchy of files).
 
+dit(bf(-m, --prune-empty-dirs)) This option tells the receiving rsync to get
+rid of empty directories from the file-list, including nested directories
+that have no non-directory children.  This is useful for avoiding the
+creation of a bunch of useless directories when the sending rsync is
+recursively scanning a hierarchy of files using include/exclude/filter
+rules.
+
+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).
+
+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
+that the directory "emptydir" was kept in the file-list:
+
+quote(    --filter 'protect emptydir/')
+
+Here's an example that copies all .pdf files in a hierarchy, only creating
+the necessary destination directories to hold the .pdf files, and ensures
+that any superfluous files and directories in the destination are removed
+(note the hide filter of non-directories being used instead of an exclude):
+
+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
+in place of the hide-filter (if that is more natural to you).
+
 dit(bf(--progress)) This option tells rsync to print information
 showing the progress of the transfer. This gives a bored user
 something to watch.