X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/a2b0471f1dd8dfbd24cc1b763b4a7c9723057b63..be92ac6c36086f0cf04c85ec7021266b4be20b04:/rsync.yo

diff --git a/rsync.yo b/rsync.yo
index edaac04f..ee3474ee 100644
--- a/rsync.yo
+++ b/rsync.yo
@@ -1,5 +1,5 @@
 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()
 
@@ -290,9 +290,9 @@ verb(
      --suffix=SUFFIX         backup suffix (default ~ w/o --backup-dir)
  -u, --update                update only (don't overwrite newer files)
  -l, --links                 copy symlinks as symlinks
- -L, --copy-links            copy the referent of symlinks
-     --copy-unsafe-links     copy links outside the source tree
-     --safe-links            ignore links outside the destination tree
+ -L, --copy-links            copy the referent of all symlinks
+     --copy-unsafe-links     copy the referent of "unsafe" symlinks
+     --safe-links            ignore "unsafe" symlinks
  -H, --hard-links            preserve hard links
  -p, --perms                 preserve permissions
  -o, --owner                 preserve owner (root only)
@@ -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).
+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 ~
@@ -471,15 +473,15 @@ dit(bf(-l, --links)) When symlinks are encountered, recreate the
 symlink on the destination.
 
 dit(bf(-L, --copy-links)) When symlinks are encountered, the file that
-they point to is copied, rather than the symlink.
+they point to (the referent) is copied, rather than the symlink.
 
 dit(bf(--copy-unsafe-links)) This tells rsync to copy the referent of
-symbolic links that point outside the source tree.  Absolute symlinks
+symbolic links that point outside the copied tree.  Absolute symlinks
 are also treated like ordinary files, and so are any symlinks in the
 source path itself when --relative is used.
 
 dit(bf(--safe-links)) This tells rsync to ignore any symbolic links
-which point outside the destination tree. All absolute symlinks are
+which point outside the copied tree. All absolute symlinks are
 also ignored. Using this option in conjunction with --relative may
 give unexpected results. 
 
@@ -652,8 +654,7 @@ useful in combination with a recursive transfer.
 You may use as many --exclude options on the command line as you like
 to build up the list of files to exclude.
 
-See the EXCLUDE PATTERNS section for information on the syntax of 
-this option.
+See the EXCLUDE PATTERNS section for detailed information on this option.
 
 dit(bf(--exclude-from=FILE)) This option is similar to the --exclude
 option, but instead it adds all exclude patterns listed in the file
@@ -665,8 +666,7 @@ dit(bf(--include=PATTERN)) This option tells rsync to not exclude the
 specified pattern of filenames. This is useful as it allows you to
 build up quite complex exclude/include rules.
 
-See the EXCLUDE PATTERNS section for information on the syntax of 
-this option.
+See the EXCLUDE PATTERNS section for detailed information on this option.
 
 dit(bf(--include-from=FILE)) This specifies a list of include patterns
 from a file.
@@ -729,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
-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
-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
@@ -889,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.
 
-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
@@ -897,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.
 
-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
@@ -920,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.
-  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.
-  The leading / does not make the pattern an absolute pathname.
 
   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
@@ -972,12 +1007,12 @@ Here are some exclude/include examples:
 
 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
-  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
-  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
@@ -1031,11 +1066,11 @@ once, instead of sending the same data to every host individually.
 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/