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.
+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.
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(
-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
-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
-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.
-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
-"-" 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
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
Some examples:
quote(
+tt(merge /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()
)
-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
- 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
- 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
- "- 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 modifiers are accepted after a "+" or "-":
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
-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
-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.
-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"
-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(
-tt(. /home/user/.global-filter)nl()
+tt(merge /home/user/.global-filter)nl()
tt(- *.gz)nl()
-tt(: .rules)nl()
+tt(dir-merge .rules)nl()
tt(+ *.[ch])nl()
tt(- *.o)nl()
)
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
-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
-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:
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)
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
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff