Adding more calls to safe_fname().

[rsync/rsync.git] / rsync.yo

diff --git a/rsync.yo b/rsync.yo
index f54fd52..a37e9f7 100644 (file)
--- a/rsync.yo
+++ b/rsync.yo
@@ -785,9 +785,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,12 +1228,12 @@ 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(x [PATTERN_OR_FILE])nl()
+tt(xMODIFIERS [PATTERN_OR_FILE])nl()

 )
 
 The 'x' is a single-letter that specifies the kind of rule to create.  It
 )
 
 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
+can have trailing modifiers, and is separated from its arg by either a

 single space or an underscore (_).  Here are the available rule prefixes:
 
 quote(
 single space or an underscore (_).  Here are the available rule prefixes:
 
 quote(


@@ -1228,7 +1241,7 @@ 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(+) 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(!) clears the current include/exclude list (takes no arg) nl()

 )
 
 Note that the bf(--include)/bf(--exclude) command-line options do not allow the
 )
 
 Note that the bf(--include)/bf(--exclude) command-line options do not allow the


@@ -1251,9 +1264,11 @@ 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


@@ -1368,32 +1383,41 @@ tt(:n- .non-inherited-per-dir-excludes)nl()
 The following modifiers are accepted after a "." or ":":
 
 itemize(
 The following modifiers are accepted after a "." or ":":
 
 itemize(

-  it() A "-" specifies that the file should consist of only exclude
+  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 the list-clearing
   token ("!").

-  it() A "+" 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 ("!").
   patterns, with no other rule-parsing except for the list-clearing
   token ("!").

-  it() A "C" is a shorthand for the modifiers "sn-", which makes the
+  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.
   parsing compatible with the way CVS parses their exclude files.  If no
   filename is specified, ".cvsignore" is assumed.

-  it() A "e" will exclude the merge-file from the transfer; e.g.
+  it() A bf(e) will exclude the merge-file from the transfer; e.g.

   ":e_.rules" is like ":_.rules" and "-_.rules".
   ":e_.rules" is like ":_.rules" and "-_.rules".

-  it() An "n" specifies that the rules are not inherited by subdirectories.
-  it() An "s" specifies that the rules are split on all whitespace instead
+  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
   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 "-" or "+" was not
+  "- foo + bar" is parsed as two rules (assuming that bf(-) or bf(+) was not

   specified to turn off the parsing of prefixes).
   specified to turn off the parsing of prefixes).

+  it() You may also specify any of the modifiers for "+" or "-" to have the
+  rules that are read-in default to having that option set.  For instance,
+  ".-/_.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
 )
 
 Per-directory rules are inherited in all subdirectories of the directory


@@ -1457,7 +1481,7 @@ 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
 
 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

-":sn-_.cvsignore", and ensures that the .cvsignore file's contents are
+":nw-_.cvsignore", and ensures that the .cvsignore file's contents are

 interpreted according to the same parsing rules that CVS uses.  You can
 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
 interpreted according to the same parsing rules that CVS uses.  You can
 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


@@ -1478,10 +1502,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 +1711,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