Try to make the complexities of includes/excludes a little more clear.

diff --git a/rsync.yo b/rsync.yo
index c7bd1c9..1e2f2c7 100644 (file)
--- a/rsync.yo
+++ b/rsync.yo
@@ -895,15 +895,45 @@ 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.
 
 skipped. If no matching include/exclude pattern is found then the
 filename is not skipped.
 

-The filenames matched against the exclude/include patterns
-are relative to the destination directory, or "top
-directory", so patterns should not include the path elements
-of the source or destination directories.  The only way in
-which a pattern will match the absolute path of a file or
-directory is if the source path is the root directory.
+The filenames matched against the exclude/include patterns are relative
+to the "root of the transfer".  If you think of the transfer as a
+subtree of names that are being sent from sender to receiver, the root
+is where the tree starts to be duplicated in the destination directory.
+This root governs where patterns that start with a / match (see below).
+
+Because the matching is relative to the transfer-root, changing the
+trailing slash on the source path or changing your use of the --relative
+option affects the path you need to use in your matching (in addition to
+changing how much of the file tree is duplicated on the destination
+system).  The following examples demonstrate this.
+
+Let's say that we want to match a source filename that has an absolute
+path of "/home/me/foo/bar", here is how the various command choices can
+differ:
+
+verb(
+   Example cmd: rsync -a /home/me /dest
+   Source root: /home          ("me" is part of transfer)
+   +/- pattern: /me/foo/bar
+   Target file: /dest/me/foo/bar
+
+   Example cmd: rsync -a /home/me/ /dest
+   Source root: /home/me              (due to trailing /)
+   +/- pattern: /foo/bar              (note missing "me")
+   Target file: /dest/foo/bar
+
+   Example cmd: rsync -a --relative /home/me/ /dest
+   Source root: /home/me
+   +/- pattern: /home/me/foo/bar      (note full path)
+   Target file: /dest/home/me/foo/bar
+)
+
+The easiest way to see what name you should include/exclude is to just
+look at the output when using --verbose and put a / in front of the name
+(use the --dry-run option if you're not yet ready to copy any files).

 
 Note that when used with -r (which is implied by -a), every subcomponent of
 
 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
+every path is visited from the top down, so include/exclude patterns get

 applied recursively to each subcomponent.
 
 Note also that the --include and --exclude options take one pattern
 applied recursively to each subcomponent.
 
 Note also that the --include and --exclude options take one pattern


@@ -918,16 +948,15 @@ itemize(
   start of the filename, otherwise it is matched against the end of
   the filename.
   This is the equivalent of a leading ^ in regular expressions.
   start of the filename, otherwise it is matched against the end of
   the filename.
   This is the equivalent of a leading ^ in regular expressions.

-  Thus "/foo" would match a file called "foo" at the top of the
-  transferred tree.
+  Thus "/foo" would match a file called "foo" at the transfer-root
+  (see above for how this is different from the filesystem-root).

   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.
   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.

-  The leading / does not make the pattern an absolute pathname.

 
   it() if the pattern ends with a / then it will only match a
 
   it() if the pattern ends with a / then it will only match a

-  directory, not a file, link or device.
+  directory, not a file, link, or device.

 
   it() if the pattern contains a wildcard character from the set
   *?[ then expression matching is applied using the shell filename
 
   it() if the pattern contains a wildcard character from the set
   *?[ then expression matching is applied using the shell filename


@@ -970,12 +999,12 @@ Here are some exclude/include examples:
 
 itemize(
   it() --exclude "*.o" would exclude all filenames matching *.o
 
 itemize(
   it() --exclude "*.o" would exclude all filenames matching *.o

-  it() --exclude "/foo" would exclude a file called foo in the top directory
+  it() --exclude "/foo" would exclude a file called foo in the transfer-root directory

   it() --exclude "foo/" would exclude any directory called foo
   it() --exclude "/foo/*/bar" would exclude any file called bar two
   it() --exclude "foo/" would exclude any directory called foo
   it() --exclude "/foo/*/bar" would exclude any file called bar two

-  levels below a directory called foo in the top directory
+  levels below a directory called foo in the transfer-root directory

   it() --exclude "/foo/**/bar" would exclude any file called bar two
   it() --exclude "/foo/**/bar" would exclude any file called bar two

-  or more levels below a directory called foo in the top directory
+  or more levels below a directory called foo in the transfer-root directory

   it() --include "*/" --include "*.c" --exclude "*" would include all 
   directories and C source files
   it() --include "foo/" --include "foo/bar.c" --exclude "*" would include
   it() --include "*/" --include "*.c" --exclude "*" would include all 
   directories and C source files
   it() --include "foo/" --include "foo/bar.c" --exclude "*" would include


@@ -1029,11 +1058,11 @@ once, instead of sending the same data to every host individually.
 Example:
 
 verb(
 Example:
 
 verb(

-$ rsync --write-batch=pfx -a /source/dir/ /adest/dir/
-$ rcp pfx.rsync_* remote:
-$ ssh remote rsync --read-batch=pfx -a /bdest/dir/
-# or alternatively
-$ ssh remote ./pfx.rsync_argvs /bdest/dir/
+   $ rsync --write-batch=pfx -a /source/dir/ /adest/dir/
+   $ rcp pfx.rsync_* remote:
+   $ ssh remote rsync --read-batch=pfx -a /bdest/dir/
+   # or alternatively
+   $ ssh remote ./pfx.rsync_argvs /bdest/dir/

 )
 
 In this example, rsync is used to update /adest/dir/ with /source/dir/
 )
 
 In this example, rsync is used to update /adest/dir/ with /source/dir/