Do better job at describing exclude/include in man page. Based on suggestions

[rsync/rsync.git] / rsync.yo

diff --git a/rsync.yo b/rsync.yo
index 7991f4c..ccb458d 100644 (file)
--- a/rsync.yo
+++ b/rsync.yo
@@ -658,7 +658,11 @@ skipped. If it is an include pattern then that filename is not
 skipped. If no matching include/exclude pattern is found then the
 filename is not skipped.
 
-Note that the --include and --exclude options take one pattern
+Note that when used with -r (which is implied by -a), every subcomponent of
+every path is visited from top down, so include/exclude patterns get
+applied recursively to each subcomponent.
+
+Note also that the --include and --exclude options take one pattern
 each. To add multiple patterns use the --include-from and
 --exclude-from options or multiple --include and --exclude options. 
 
@@ -667,9 +671,11 @@ The patterns can take several forms. The rules are:
 itemize(
   it() if the pattern starts with a / then it is matched against the
   start of the filename, otherwise it is matched against the end of
-  the filename. Thus /foo would match a file called foo
-  at the base of the tree whereas foo would match any file
-  called foo anywhere in the tree.
+  the filename.  Thus "/foo" would match a file called "foo" at the base of
+  the tree.  On the other hand, "foo" would match any file called "foo"
+  anywhere in the tree because the algorithm is applied recursively from
+  top down; it behaves as if each path component gets a turn at being the
+  end of the file name.
 
   it() if the pattern ends with a / then it will only match a
   directory, not a file, link or device.
@@ -678,12 +684,15 @@ itemize(
   *?[ then expression matching is applied using the shell filename
   matching rules. Otherwise a simple string match is used.
 
+  it() if the pattern includes a double asterisk "**" then all wildcards in
+  the pattern will match slashes, otherwise they will stop at slashes.
+
   it() if the pattern contains a / (not counting a trailing /) then it
   is matched against the full filename, including any leading
   directory. If the pattern doesn't contain a / then it is matched
-  only against the final component of the filename.  Furthermore, if
-  the pattern includes a double asterisk "**" then all wildcards in
-  the pattern will match slashes, otherwise they will stop at slashes.
+  only against the final component of the filename.  Again, remember
+  that the algorithm is applied recursively so "full filename" can 
+  actually be any portion of a path.
 
   it() if the pattern starts with "+ " (a plus followed by a space)
   then it is always considered an include pattern, even if specified as
@@ -700,6 +709,13 @@ itemize(
 The +/- rules are most useful in exclude lists, allowing you to have a
 single exclude list that contains both include and exclude options.
 
+If you end an exclude list with --exclude '*', note that since the
+algorithm is applied recursively that unless you explicitly include
+parent directories of files you want to include then the algorithm
+will stop at the parent directories and never see the files below
+them.  To include all directories, use --include '*/' before the
+--exclude '*'.
+
 Here are some exclude/include examples:
 
 itemize(