Added one more example to the new include/exclude section to show how

[rsync/rsync.git] / rsync.yo

diff --git a/rsync.yo b/rsync.yo
index acc3e9c..ee3474e 100644 (file)
--- a/rsync.yo
+++ b/rsync.yo
@@ -1,5 +1,5 @@
 mailto(rsync-bugs@samba.org)
 mailto(rsync-bugs@samba.org)

-manpage(rsync)(1)(1 Jan 2004)()()
+manpage(rsync)(1)(24 Mar 2004)()()

 manpagename(rsync)(faster, flexible replacement for rcp)
 manpagesynopsis()
 
 manpagename(rsync)(faster, flexible replacement for rcp)
 manpagesynopsis()
 


@@ -458,6 +458,8 @@ very useful for incremental backups.  You can additionally
 specify a backup suffix using the --suffix option
 (otherwise the files backed up in the specified directory
 will keep their original filenames).
 specify a backup suffix using the --suffix option
 (otherwise the files backed up in the specified directory
 will keep their original filenames).

+If DIR is a relative path, it is relative to the destination directory
+(which changes in a recursive transfer).

 
 dit(bf(--suffix=SUFFIX)) This option allows you to override the default
 backup suffix used with the --backup (-b) option. The default suffix is a ~
 
 dit(bf(--suffix=SUFFIX)) This option allows you to override the default
 backup suffix used with the --backup (-b) option. The default suffix is a ~


@@ -727,14 +729,14 @@ although this skips files that haven't changed; see also --link-dest).
 This option increases the usefulness of --partial because partially
 transferred files will remain in the new temporary destination until they
 have a chance to be completed.  If DIR is a relative path, it is relative
 This option increases the usefulness of --partial because partially
 transferred files will remain in the new temporary destination until they
 have a chance to be completed.  If DIR is a relative path, it is relative

-to the destination directory.
+to the destination directory (which changes in a recursive transfer).

 
 dit(bf(--link-dest=DIR)) This option behaves like bf(--compare-dest) but
 also will create hard links from em(DIR) to the destination directory for
 unchanged files.  Files with changed ownership or permissions will not be
 linked.
 Like bf(--compare-dest) if DIR is a relative path, it is relative
 
 dit(bf(--link-dest=DIR)) This option behaves like bf(--compare-dest) but
 also will create hard links from em(DIR) to the destination directory for
 unchanged files.  Files with changed ownership or permissions will not be
 linked.
 Like bf(--compare-dest) if DIR is a relative path, it is relative

-to the destination directory.
+to the destination directory (which changes in a recursive transfer).

 
 dit(bf(-z, --compress)) With this option, rsync compresses any data from
 the files that it sends to the destination machine.  This
 
 dit(bf(-z, --compress)) With this option, rsync compresses any data from
 the files that it sends to the destination machine.  This


@@ -887,7 +889,7 @@ manpagesection(EXCLUDE PATTERNS)
 The exclude and include patterns specified to rsync allow for flexible
 selection of which files to transfer and which files to skip.
 
 The exclude and include patterns specified to rsync allow for flexible
 selection of which files to transfer and which files to skip.
 

-rsync builds an ordered list of include/exclude options as specified on
+Rsync builds an ordered list of include/exclude options as specified on

 the command line. Rsync checks each file and directory 
 name against each exclude/include pattern in turn. The first matching
 pattern is acted on. If it is an exclude pattern, then that file is
 the command line. Rsync checks each file and directory 
 name against each exclude/include pattern in turn. The first matching
 pattern is acted on. If it is an exclude pattern, then that file is


@@ -895,15 +897,51 @@ 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).

 
 

-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
+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
+
+   Example cmd: cd /home; rsync -a --relative me/foo/ /dest
+   Source root: ./me/foo         (source is not absolute)
+   +/- pattern: /me/foo/bar      (only uses specified path)
+   Target file: /dest/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 using the --recursive (-r) option (which is implied by -a),
+every subcomponent of
+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 +956,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 +1007,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 +1066,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/