Implement the "m", "o", "g" include modifiers to tweak the permissions,
[rsync/rsync.git] / rsync.yo
index a1b69ef..5fbe868 100644 (file)
--- a/rsync.yo
+++ b/rsync.yo
@@ -752,6 +752,10 @@ date is on the objects.  In other words, if the source has a directory
 where the destination has a file, the transfer would occur regardless of
 the timestamps.
 
+This option is a transfer rule, not an exclude, so it doesn't affect the
+data that goes into the file-lists, and thus it doesn't affect deletions.
+It just limits the files that the receiver requests to be transferred.
+
 dit(bf(--inplace)) This option changes how rsync transfers a file when the
 file's data needs to be updated: instead of the default method of creating
 a new copy of the file and moving it into place when it is complete, rsync
@@ -1024,6 +1028,8 @@ quote(--chmod=Dg+s,ug+w,Fo-w,+X)
 
 It is also legal to specify multiple bf(--chmod) options, as each
 additional option is just appended to the list of changes to make.
+To change permissions of files matching a pattern, use an include filter with
+the bf(m) modifier, which takes effect before any bf(--chmod) options.
 
 See the bf(--perms) and bf(--executability) options for how the resulting
 permission value can be applied to the files in the transfer.
@@ -1169,10 +1175,18 @@ yet on the destination.  If this option is
 combined with the bf(--ignore-existing) option, no files will be updated
 (which can be useful if all you want to do is delete extraneous files).
 
+This option is a transfer rule, not an exclude, so it doesn't affect the
+data that goes into the file-lists, and thus it doesn't affect deletions.
+It just limits the files that the receiver requests to be transferred.
+
 dit(bf(--ignore-existing)) This tells rsync to skip updating files that
 already exist on the destination (this does em(not) ignore existing
 directories, or nothing would get done).  See also bf(--existing).
 
+This option is a transfer rule, not an exclude, so it doesn't affect the
+data that goes into the file-lists, and thus it doesn't affect deletions.
+It just limits the files that the receiver requests to be transferred.
+
 This option can be useful for those doing backups using the bf(--link-dest)
 option when they need to continue a backup run that got interrupted.  Since
 a bf(--link-dest) run is copied into a new directory hierarchy (when it is
@@ -1312,6 +1326,10 @@ file that is larger than the specified SIZE. The SIZE value can be
 suffixed with a string to indicate a size multiplier, and
 may be a fractional value (e.g. "bf(--max-size=1.5m)").
 
+This option is a transfer rule, not an exclude, so it doesn't affect the
+data that goes into the file-lists, and thus it doesn't affect deletions.
+It just limits the files that the receiver requests to be transferred.
+
 The suffixes are as follows: "K" (or "KiB") is a kibibyte (1024),
 "M" (or "MiB") is a mebibyte (1024*1024), and "G" (or "GiB") is a
 gibibyte (1024*1024*1024).
@@ -1326,7 +1344,7 @@ Examples: --max-size=1.5mb-1 is 1499999 bytes, and --max-size=2g+1 is
 dit(bf(--min-size=SIZE)) This tells rsync to avoid transferring any
 file that is smaller than the specified SIZE, which can help in not
 transferring small, junk files.
-See the bf(--max-size) option for a description of SIZE.
+See the bf(--max-size) option for a description of SIZE and other information.
 
 dit(bf(-B, --block-size=BLOCKSIZE)) This forces the block size used in
 rsync's delta-transfer algorithm to a fixed value.  It is normally selected based on
@@ -1792,6 +1810,10 @@ be omitted, but if USER is empty, a leading colon must be supplied.
 If you specify "--chown=foo:bar, this is exactly the same as specifying
 "--usermap=*:foo --groupmap=*:bar", only easier.
 
+To change ownership of files matching a pattern, use an include filter with
+the bf(o) and bf(g) modifiers, which take effect before uid/gid mapping and
+therefore em(can) be mixed with bf(--usermap) and bf(--groupmap).
+
 dit(bf(--timeout=TIMEOUT)) This option allows you to set a maximum I/O
 timeout in seconds. If no data is transferred for the specified time
 then rsync will exit. The default is 0, which means no timeout.
@@ -2116,11 +2138,16 @@ creation of a bunch of useless directories when the sending rsync is
 recursively scanning a hierarchy of files using include/exclude/filter
 rules.
 
+Note that the use of transfer rules, such as the bf(--min-size) option, does
+not affect what goes into the file list, and thus does not leave directories
+empty, even if none of the files in a directory match the transfer rule.
+
 Because the file-list is actually being pruned, this option also affects
 what directories get deleted when a delete is active.  However, keep in
 mind that excluded files and directories can prevent existing items from
-being deleted (because an exclude hides source files and protects
-destination files).
+being deleted due to an exclude both hiding source files and protecting
+destination files.  See the perishable filter-rule option for how to avoid
+this.
 
 You can prevent the pruning of certain empty directories from the file-list
 by using a global "protect" filter.  For instance, this option would ensure
@@ -2436,15 +2463,15 @@ must come after either a single space or an underscore (_).
 Here are the available rule prefixes:
 
 quote(
-bf(exclude, -) specifies an exclude pattern. nl()
-bf(include, +) specifies an include pattern. nl()
-bf(merge, .) specifies a merge-file to read for more rules. nl()
-bf(dir-merge, :) specifies a per-directory merge-file. nl()
-bf(hide, H) specifies a pattern for hiding files from the transfer. nl()
-bf(show, S) files that match the pattern are not hidden. nl()
-bf(protect, P) specifies a pattern for protecting files from deletion. nl()
-bf(risk, R) files that match the pattern are not protected. nl()
-bf(clear, !) clears the current include/exclude list (takes no arg) nl()
+bf(exclude, -) Exclude matching files. nl()
+bf(include, +) Don't exclude matching files. nl()
+bf(merge, .) Read a merge-file for more rules. nl()
+bf(dir-merge, :) Specify a per-directory merge-file. nl()
+bf(hide, H) Hide matching source files from the transfer (shorthand for bf(-s)). nl()
+bf(show, S) Do not hide matching source files from the transfer (shorthand for bf(+s)). nl()
+bf(protect, P) Protect matching destination files from deletion (shorthand for bf(-r)). nl()
+bf(risk, R) Do not protect matching destination files from deletion (shorthand for bf(+r)). nl()
+bf(clear, !) Clear the current include/exclude list (takes no argument). nl()
 )
 
 When rules are being read from a file, empty lines are ignored, as are
@@ -2568,6 +2595,48 @@ itemization(
   explicitly included or it would be excluded by the "*")
 )
 
+The following modifiers are accepted after a "+" or "-":
+
+itemization(
+  it() A bf(/) specifies that the include/exclude rule should be matched
+  against the absolute pathname of the current item.  For example,
+  "-/ /etc/passwd" would exclude the passwd file any time the transfer
+  was sending files from the "/etc" directory, and "-/ subdir/foo"
+  would always exclude "foo" when it is in a dir named "subdir", even
+  if "foo" is at the root of the current transfer.
+  it() A bf(!) specifies that the include/exclude should take effect if
+  the pattern fails to match.  For instance, "-! */" would exclude all
+  non-directories.
+  it() A bf(C) is used to indicate that all the global CVS-exclude rules
+  should be inserted as excludes in place of the "-C".  No arg should
+  follow.
+  it() An bf(s) is used to indicate that the rule applies to the sending
+  side.  When a rule affects the sending side, it prevents files from
+  being transferred.  The default is for a rule to affect both sides
+  unless bf(--delete-excluded) was specified, in which case default rules
+  become sender-side only.  See also the hide (H) and show (S) rules,
+  which are an alternate way to specify sending-side includes/excludes.
+  it() An bf(r) is used to indicate that the rule applies to the receiving
+  side.  When a rule affects the receiving side, it prevents files from
+  being deleted.  See the bf(s) modifier for more info.  See also the
+  protect (P) and risk (R) rules, which are an alternate way to
+  specify receiver-side includes/excludes.
+  it() A bf(p) indicates that a rule is perishable, meaning that it is
+  ignored in directories that are being deleted.  For instance, the bf(-C)
+  option's default rules that exclude things like "CVS" and "*.o" are
+  marked as perishable, and will not prevent a directory that was removed
+  on the source from being deleted on the destination.
+  it() An bf(m+nop()(CHMOD)) on an include rule tweaks the permissions of matching
+  source files in the same way as bf(--chmod).  This happens before any
+  tweaks requested via bf(--chmod) options.
+  it() An bf(o+nop()(USER)) on an include rule pretends that matching source files
+  are owned by bf(USER) (a name or numeric uid).  This happens before any uid
+  mapping by name or bf(--usermap).
+  it() A bf(g+nop()(GROUP)) on an include rule pretends that matching source files
+  are owned by bf(GROUP) (a name or numeric gid).  This happens before any gid
+  mapping by name or bf(--groupmap).
+)
+
 manpagesection(MERGE-FILE FILTER RULES)
 
 You can merge whole files into your filter rules by specifying either a
@@ -2616,45 +2685,22 @@ itemization(
   "- foo + bar" is parsed as two rules (assuming that prefix-parsing wasn't
   also disabled).
   it() You may also specify any of the modifiers for the "+" or "-" rules
-  (below) in order to have the rules that are read in from the file
-  default to having that modifier set.  For instance, "merge,-/ .excl" would
+  (above) in order to have the rules that are read in from the file
+  default to having that modifier set (except for the bf(!) modifier, which
+  would not be useful).  For instance, "merge,-/ .excl" would
   treat the contents of .excl as absolute-path excludes,
   while "dir-merge,s .filt" and ":sC" would each make all their
-  per-directory rules apply only on the sending side.
+  per-directory rules apply only on the sending side.  If the merge rule
+  specifies sides to affect (via the bf(s) or bf(r) modifier or both),
+  then the rules in the file must not specify sides (via a modifier or
+  a rule prefix such as bf(hide)).
 )
 
-The following modifiers are accepted after a "+" or "-":
-
-itemization(
-  it() A bf(/) specifies that the include/exclude rule should be matched
-  against the absolute pathname of the current item.  For example,
-  "-/ /etc/passwd" would exclude the passwd file any time the transfer
-  was sending files from the "/etc" directory, and "-/ subdir/foo"
-  would always exclude "foo" when it is in a dir named "subdir", even
-  if "foo" is at the root of the current transfer.
-  it() A bf(!) specifies that the include/exclude should take effect if
-  the pattern fails to match.  For instance, "-! */" would exclude all
-  non-directories.
-  it() A bf(C) is used to indicate that all the global CVS-exclude rules
-  should be inserted as excludes in place of the "-C".  No arg should
-  follow.
-  it() An bf(s) is used to indicate that the rule applies to the sending
-  side.  When a rule affects the sending side, it prevents files from
-  being transferred.  The default is for a rule to affect both sides
-  unless bf(--delete-excluded) was specified, in which case default rules
-  become sender-side only.  See also the hide (H) and show (S) rules,
-  which are an alternate way to specify sending-side includes/excludes.
-  it() An bf(r) is used to indicate that the rule applies to the receiving
-  side.  When a rule affects the receiving side, it prevents files from
-  being deleted.  See the bf(s) modifier for more info.  See also the
-  protect (P) and risk (R) rules, which are an alternate way to
-  specify receiver-side includes/excludes.
-  it() A bf(p) indicates that a rule is perishable, meaning that it is
-  ignored in directories that are being deleted.  For instance, the bf(-C)
-  option's default rules that exclude things like "CVS" and "*.o" are
-  marked as perishable, and will not prevent a directory that was removed
-  on the source from being deleted on the destination.
-)
+The attribute-affecting modifiers bf(m), bf(o), and bf(g) work only in client
+filters (not in daemon filters), and only the modifiers of the first matching
+rule are applied.  As an example, assuming bf(--super) is enabled, the
+rule "+o+nop()(root)g+nop()(root)m+nop()(go=) *~" would ensure that all "backup" files belong to
+root and are not accessible to anyone else.
 
 Per-directory rules are inherited in all subdirectories of the directory
 where the merge-file was found unless the 'n' modifier was used.  Each