Changed rule_match() to rule_strcmp(). Likewise for the

[rsync/rsync.git] / rsync.yo

diff --git a/rsync.yo b/rsync.yo
index e44e2e2..2c8f518 100644 (file)
--- a/rsync.yo
+++ b/rsync.yo
@@ -434,12 +434,13 @@ regardless of timestamp. This is useful when starting to use rsync
 after using another mirroring system which may not preserve timestamps
 exactly.
 
 after using another mirroring system which may not preserve timestamps
 exactly.
 

-dit(bf(--modify-window)) When comparing two timestamps rsync treats
-the timestamps as being equal if they are within the value of
-modify_window. This is normally zero, but you may find it useful to
-set this to a larger value in some situations. In particular, when
-transferring to Windows FAT filesystems which cannot represent times
-with a 1 second resolution bf(--modify-window=1) is useful.
+dit(bf(--modify-window)) When comparing two timestamps, rsync treats the
+timestamps as being equal if they differ by no more than the modify-window
+value.  This is normally 0 (for an exact match), but you may find it useful
+to set this to a larger value in some situations.  In particular, when
+transferring to or from an MS Windows FAT filesystem (which represents
+times with a 2-second resolution), bf(--modify-window=1) is useful
+(allowing times to differ by up to 1 second).

 
 dit(bf(-c, --checksum)) This forces the sender to checksum all files using
 a 128-bit MD4 checksum before transfer. The checksum is then
 
 dit(bf(-c, --checksum)) This forces the sender to checksum all files using
 a 128-bit MD4 checksum before transfer. The checksum is then


@@ -785,9 +786,22 @@ files listed in the CVSIGNORE environment variable (all cvsignore names
 are delimited by whitespace).
 
 Finally, any file is ignored if it is in the same directory as a
 are delimited by whitespace).
 
 Finally, any file is ignored if it is in the same directory as a

-.cvsignore file and matches one of the patterns listed therein.
+.cvsignore file and matches one of the patterns listed therein.  Unlike
+rsync's filter/exclude files, these patterns are split on whitespace.

 See the bf(cvs(1)) manual for more information.
 
 See the bf(cvs(1)) manual for more information.
 

+If you're combining bf(-C) with your own bf(--filter) rules, you should
+note that these CVS excludes are appended at the end of your own rules,
+regardless of where the -C was placed on the command-line.  This makes them
+a lower priority than any rules you specified explicitly.  If you want to
+control where these CVS excludes get inserted into your filter rules, you
+should omit the bf(-C) as a command-line option and use a combination of
+bf(--filter=:C) and bf(--filter=-C) (either on your command-line or by
+putting the ":C" and "-C" rules into a filter file with your other rules).
+The first option turns on the per-directory scanning for the .cvsignore
+file.  The second option does a one-time import of the CVS excludes
+mentioned above.
+

 dit(bf(-f, --filter=RULE)) This option allows you to add rules to selectively
 exclude certain files from the list of files to be transferred. This is
 most useful in combination with a recursive transfer.
 dit(bf(-f, --filter=RULE)) This option allows you to add rules to selectively
 exclude certain files from the list of files to be transferred. This is
 most useful in combination with a recursive transfer.


@@ -1215,45 +1229,50 @@ Rsync builds an ordered list of filter rules as specified on the
 command-line.  Filter rules have the following syntax:
 
 quote(
 command-line.  Filter rules have the following syntax:
 
 quote(

-tt(x [RULE])nl()
-tt(xMODIFIERS [RULE])nl()
+tt(RULE [PATTERN_OR_FILENAME])nl()
+tt(RULE,MODIFIERS [PATTERN_OR_FILENAME])nl()

 )
 
 )
 

-The 'x' is a single-letter that specifies the kind of rule to create.  It
-can have trailing modifiers, and is separated from the RULE by either a
-single space or an underscore (_).  Here are the available rule prefixes:
+You have your choice of using either short or long RULE names, as described
+below.  If you use a short-named rule, the ',' separating the RULE from the
+MODIFIERS is optional.  The PATTERN or FILENAME that follows (when present)
+must come after either a single space or an underscore (_).
+Here are the available rule prefixes:

 
 quote(
 
 quote(

-bf(-) specifies an exclude pattern. nl()
-bf(+) specifies an include pattern. nl()
-bf(.) specifies a merge-file to read for more rules. nl()
-bf(:) specifies a per-directory merge-file. nl()
-bf(!) clears the current include/exclude list (takes no RULE) nl()
+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(clear, !) clears the current include/exclude list (takes no arg) nl()

 )
 
 )
 

+When rules are being read from a file, empty lines are ignored, as are
+comment lines that start with a "#".
+

 Note that the bf(--include)/bf(--exclude) command-line options do not allow the
 full range of rule parsing as described above -- they only allow the
 Note that the bf(--include)/bf(--exclude) command-line options do not allow the
 full range of rule parsing as described above -- they only allow the

-specification of include/exclude patterns and the "!" token (not to
-mention the comment lines when reading rules from a file).  If a pattern
+specification of include/exclude patterns plus a "!" token to clear the
+list (and the normal comment parsing when rules are read from a file).
+If a pattern

 does not begin with "- " (dash, space) or "+ " (plus, space), then the
 rule will be interpreted as if "+ " (for an include option) or "- " (for
 an exclude option) were prefixed to the string.  A bf(--filter) option, on
 does not begin with "- " (dash, space) or "+ " (plus, space), then the
 rule will be interpreted as if "+ " (for an include option) or "- " (for
 an exclude option) were prefixed to the string.  A bf(--filter) option, on

-the other hand, must always contain one of the prefixes above.
+the other hand, must always contain either a short or long rule name at the
+start of the rule.

 
 Note also that the bf(--filter), bf(--include), and bf(--exclude) options take one
 rule/pattern each. To add multiple ones, you can repeat the options on
 the command-line, use the merge-file syntax of the bf(--filter) option, or
 the bf(--include-from)/bf(--exclude-from) options.
 
 
 Note also that the bf(--filter), bf(--include), and bf(--exclude) options take one
 rule/pattern each. To add multiple ones, you can repeat the options on
 the command-line, use the merge-file syntax of the bf(--filter) option, or
 the bf(--include-from)/bf(--exclude-from) options.
 

-When rules are being read from a file, empty lines are ignored, as are
-comment lines that start with a "#".
-

 manpagesection(INCLUDE/EXCLUDE PATTERN RULES)
 
 You can include and exclude files by specifying patterns using the "+" and
 manpagesection(INCLUDE/EXCLUDE PATTERN RULES)
 
 You can include and exclude files by specifying patterns using the "+" and

-"-" filter rules (as introduced in the FILTER RULES section above).  These
-rules specify a pattern that is matched against the names of the files
-that are going to be transferred.  These patterns can take several forms:
+"-" filter rules (as introduced in the FILTER RULES section above).
+The include/exclude rules each specify a pattern that is matched against
+the names of the files that are going to be transferred.  These patterns
+can take several forms:

 
 itemize(
   it() if the pattern starts with a / then it is anchored to a
 
 itemize(
   it() if the pattern starts with a / then it is anchored to a


@@ -1342,8 +1361,8 @@ itemize(
 manpagesection(MERGE-FILE FILTER RULES)
 
 You can merge whole files into your filter rules by specifying either a
 manpagesection(MERGE-FILE FILTER RULES)
 
 You can merge whole files into your filter rules by specifying either a

-"." or a ":" filter rule (as introduced in the FILTER RULES section
-above).
+merge (.) or a dir-merge (:) filter rule (as introduced in the FILTER RULES
+section above).

 
 There are two kinds of merged files -- single-instance ('.') and
 per-directory (':').  A single-instance merge file is read one time, and
 
 There are two kinds of merged files -- single-instance ('.') and
 per-directory (':').  A single-instance merge file is read one time, and


@@ -1360,64 +1379,75 @@ below).
 Some examples:
 
 quote(
 Some examples:
 
 quote(

+tt(merge /etc/rsync/default.rules)nl()

 tt(. /etc/rsync/default.rules)nl()
 tt(. /etc/rsync/default.rules)nl()

-tt(: .per-dir-filter)nl()
+tt(dir-merge .per-dir-filter)nl()
+tt(dir-merge,n- .non-inherited-per-dir-excludes)nl()

 tt(:n- .non-inherited-per-dir-excludes)nl()
 )
 
 tt(:n- .non-inherited-per-dir-excludes)nl()
 )
 

-The following modifiers are accepted after a "." or ":":
+The following modifiers are accepted after a merge or dir-merge rule:

 
 itemize(
   it() A bf(-) specifies that the file should consist of only exclude
 
 itemize(
   it() A bf(-) specifies that the file should consist of only exclude

-  patterns, with no other rule-parsing except for the list-clearing
-  token ("!").
+  patterns, with no other rule-parsing except for in-file comments.

   it() A bf(+) specifies that the file should consist of only include
   it() A bf(+) specifies that the file should consist of only include

-  patterns, with no other rule-parsing except for the list-clearing
-  token ("!").
-  it() A bf(C) is a shorthand for the modifiers bf(nw-), which makes the
-  parsing compatible with the way CVS parses their exclude files.  If no
-  filename is specified, ".cvsignore" is assumed.
-  it() A bf(e) will exclude the merge-file from the transfer; e.g.
-  ":e_.rules" is like ":_.rules" and "-_.rules".
+  patterns, with no other rule-parsing except for in-file comments.
+  it() A bf(C) is a way to specify that the file should be read in a
+  CVS-compatible manner.  This turns on 'n', 'w', and '-', but also
+  allows the list-clearing token (!) to be specified.  If no filename is
+  provided, ".cvsignore" is assumed.
+  it() A bf(e) will exclude the merge-file name from the transfer; e.g.
+  "dir-merge,e_.rules" is like "dir-merge,_.rules" and "-_.rules".

   it() An bf(n) specifies that the rules are not inherited by subdirectories.
   it() A bf(w) specifies that the rules are word-split on whitespace instead
   of the normal line-splitting.  This also turns off comments.  Note: the
   space that separates the prefix from the rule is treated specially, so
   it() An bf(n) specifies that the rules are not inherited by subdirectories.
   it() A bf(w) specifies that the rules are word-split on whitespace instead
   of the normal line-splitting.  This also turns off comments.  Note: the
   space that separates the prefix from the rule is treated specially, so

-  "- foo + bar" is parsed as two rules (assuming that bf(-) or bf(+) was not
-  specified to turn off the parsing of prefixes).
+  "- 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
+  treat the contents of .excl as absolute-path excludes.

 )
 
 )
 

-The following modifier is accepted after a "+" or "-":
+The following modifiers are accepted after a "+" or "-":

 
 itemize(
   it() A "/" specifies that the include/exclude should be treated as an
   absolute path, relative to the root of the filesystem.  For example,
   "-/_/etc/passwd" would exclude the passwd file any time the transfer
   was sending files from the "/etc" directory.
 
 itemize(
   it() A "/" specifies that the include/exclude should be treated as an
   absolute path, relative to the root of the filesystem.  For example,
   "-/_/etc/passwd" would exclude the passwd file any time the transfer
   was sending files from the "/etc" directory.

+  it() A "!" 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.

 )
 
 Per-directory rules are inherited in all subdirectories of the directory
 where the merge-file was found unless the 'n' modifier was used.  Each
 subdirectory's rules are prefixed to the inherited per-directory rules
 from its parents, which gives the newest rules a higher priority than the
 )
 
 Per-directory rules are inherited in all subdirectories of the directory
 where the merge-file was found unless the 'n' modifier was used.  Each
 subdirectory's rules are prefixed to the inherited per-directory rules
 from its parents, which gives the newest rules a higher priority than the

-inherited rules.  The entire set of per-dir rules is grouped together in
+inherited rules.  The entire set of dir-merge rules are grouped together in

 the spot where the merge-file was specified, so it is possible to override
 the spot where the merge-file was specified, so it is possible to override

-per-dir rules via a rule that got specified earlier in the list of global
+dir-merge rules via a rule that got specified earlier in the list of global

 rules.  When the list-clearing rule ("!") is read from a per-directory
 file, it only clears the inherited rules for the current merge file.
 
 rules.  When the list-clearing rule ("!") is read from a per-directory
 file, it only clears the inherited rules for the current merge file.
 

-Another way to prevent a single per-dir rule from being inherited is to
+Another way to prevent a single rule from a dir-merge file from being inherited is to

 anchor it with a leading slash.  Anchored rules in a per-directory
 merge-file are relative to the merge-file's directory, so a pattern "/foo"
 anchor it with a leading slash.  Anchored rules in a per-directory
 merge-file are relative to the merge-file's directory, so a pattern "/foo"

-would only match the file "foo" in the directory where the per-dir filter
+would only match the file "foo" in the directory where the dir-merge filter

 file was found.
 
 Here's an example filter file which you'd specify via bf(--filter=". file":)
 
 quote(
 file was found.
 
 Here's an example filter file which you'd specify via bf(--filter=". file":)
 
 quote(

-tt(. /home/user/.global-filter)nl()
+tt(merge /home/user/.global-filter)nl()

 tt(- *.gz)nl()
 tt(- *.gz)nl()

-tt(: .rules)nl()
+tt(dir-merge .rules)nl()

 tt(+ *.[ch])nl()
 tt(- *.o)nl()
 )
 tt(+ *.[ch])nl()
 tt(- *.o)nl()
 )


@@ -1456,13 +1486,12 @@ and only looks for the ".rsync-filter" files in each directory that is
 a part of the transfer.
 
 If you want to include the contents of a ".cvsignore" in your patterns,
 a part of the transfer.
 
 If you want to include the contents of a ".cvsignore" in your patterns,

-you should use the rule ":C" -- this is a short-hand for the rule
-":nw-_.cvsignore", and ensures that the .cvsignore file's contents are
-interpreted according to the same parsing rules that CVS uses.  You can
+you should use the rule ":C", which creates a dir-merge of the .cvsignore
+file, but parsed in a CVS-compatible manner.  You can

 use this to affect where the bf(--cvs-exclude) (bf(-C)) option's inclusion of the
 use this to affect where the bf(--cvs-exclude) (bf(-C)) option's inclusion of the

-per-directory .cvsignore file gets placed into your rules by putting a
+per-directory .cvsignore file gets placed into your rules by putting the

 ":C" wherever you like in your filter rules.  Without this, rsync would
 ":C" wherever you like in your filter rules.  Without this, rsync would

-add the per-dir rule for the .cvsignore file at the end of all your other
+add the dir-merge rule for the .cvsignore file at the end of all your other

 rules (giving it a lower priority than your command-line rules).  For
 example:
 
 rules (giving it a lower priority than your command-line rules).  For
 example:
 


@@ -1478,10 +1507,11 @@ tt(rsync -avC --include=foo.o -f :C --exclude='*.old' a/ b)nl()
 Both of the above rsync commands are identical.  Each one will merge all
 the per-directory .cvsignore rules in the middle of the list rather than
 at the end.  This allows their dir-specific rules to supersede the rules
 Both of the above rsync commands are identical.  Each one will merge all
 the per-directory .cvsignore rules in the middle of the list rather than
 at the end.  This allows their dir-specific rules to supersede the rules

-that follow the :C instead of being subservient to all your rules.  (The
-global rules taken from the $HOME/.cvsignore file and from $CVSIGNORE are
-not repositioned from their spot at the end of your rules, however -- feel
-free to manually include $HOME/.cvsignore elsewhere in your rules.)
+that follow the :C instead of being subservient to all your rules.  To
+affect the other CVS exclude rules (i.e. the default list of exclusions,
+the contents of $HOME/.cvsignore, and the value of $CVSIGNORE) you should
+omit the bf(-C) command-line option and instead insert a "-C" rule into
+your filter rules; e.g. "--filter=-C".

 
 manpagesection(LIST-CLEARING FILTER RULE)
 
 
 manpagesection(LIST-CLEARING FILTER RULE)
 


@@ -1686,10 +1716,10 @@ error.
 When reading a batch file, rsync will force the value of certain options
 to match the data in the batch file if you didn't set them to the same
 as the batch-writing command.  Other options can (and should) be changed.
 When reading a batch file, rsync will force the value of certain options
 to match the data in the batch file if you didn't set them to the same
 as the batch-writing command.  Other options can (and should) be changed.

-For instance
-bf(--write-batch) changes to bf(--read-batch), bf(--files-from) is dropped, and the
-bf(--filter)/bf(--include)/bf(--exclude) options are not needed unless one of the
-bf(--delete) options is specified without bf(--delete-excluded).
+For instance bf(--write-batch) changes to bf(--read-batch),
+bf(--files-from) is dropped, and the
+bf(--filter)/bf(--include)/bf(--exclude) options are not needed unless
+one of the bf(--delete) options is specified.

 
 The code that creates the BATCH.sh file transforms any filter/include/exclude
 options into a single list that is appended as a "here" document to the
 
 The code that creates the BATCH.sh file transforms any filter/include/exclude
 options into a single list that is appended as a "here" document to the