X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/f177b7cca2c359dda4589c93ed52d46f12ac9e4d..9533e15a7996c5e01fff60a754c39d4fae5461f6:/rsync.yo

diff --git a/rsync.yo b/rsync.yo
index e257eff3..5faa561c 100644
--- a/rsync.yo
+++ b/rsync.yo
@@ -507,8 +507,13 @@ the source and target are on the local machine.
 dit(bf(--no-whole-file)) Turn off --whole-file, for use when it is the
 default.
 
-dit(bf(-p, --perms)) This option causes rsync to update the remote
-permissions to be the same as the local permissions.
+dit(bf(-p, --perms)) This option causes rsync to set the destination
+permissions to be the same as the source permissions.
+
+Without this option, each new file gets its permissions set based on the
+source file's permissions and the umask at the receiving end, while all
+other files (including updated files) retain their existing permissions
+(which is the same behavior as other file-copy utilities, such as cp).
 
 dit(bf(-o, --owner)) This option causes rsync to set the owner of the
 destination file to be the same as the source file.  On most systems,
@@ -651,7 +656,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 section on exclude patterns for information on the syntax of 
+See the EXCLUDE PATTERNS section for information on the syntax of 
 this option.
 
 dit(bf(--exclude-from=FILE)) This option is similar to the --exclude
@@ -664,7 +669,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 section of exclude patterns for information on the syntax of 
+See the EXCLUDE PATTERNS section for information on the syntax of 
 this option.
 
 dit(bf(--include-from=FILE)) This specifies a list of include patterns
@@ -734,6 +739,8 @@ 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.
 
 dit(bf(-z, --compress)) With this option, rsync compresses any data from
 the files that it sends to the destination machine.  This
@@ -871,6 +878,12 @@ 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 base directories, so patterns should not
+include the path elements to those base directories.  The
+only way in which a pattern will match the absolute path of
+a file or directory is if the base path is the root directory.
+
 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.
@@ -882,13 +895,18 @@ each. To add multiple patterns use the --include-from and
 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.  On the other hand, "foo" would match any file called "foo"
+  the filename.
+  This is the equivalent of a leading ^ in regular expressions.
+  Thus "/foo" would match a file called "foo" at the base of the
+  transferred 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.
+  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.
@@ -900,11 +918,11 @@ itemize(
   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.  Again, remember
-  that the algorithm is applied recursively so "full filename" can 
+  it() if the pattern contains a / (not counting a trailing /) or a "**"
+  then it is matched against the full filename, including any leading
+  directory. If the pattern doesn't contain a / or a "**", then it is
+  matched 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)
@@ -919,8 +937,9 @@ itemize(
   include/exclude list is reset, removing all previously defined patterns.
 )
 
-The +/- rules are most useful in exclude lists, allowing you to have a
-single exclude list that contains both include and exclude options.
+The +/- rules are most useful in a list that was read from a file, 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