X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/44d60d5f83da9595a93a6acdb3fd770d249381a4..0f7e31f7d71e55e5d3bc809e58dbc045a72c4baf:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 1f6a41cc..48ba5f2d 100644 --- 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 -.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. @@ -1215,45 +1228,50 @@ Rsync builds an ordered list of filter rules as specified on the 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 @@ -1342,8 +1360,8 @@ itemize( 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 @@ -1360,31 +1378,36 @@ below). 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 "-": @@ -1397,30 +1420,33 @@ itemize( 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() ) @@ -1459,13 +1485,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, -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: @@ -1481,10 +1506,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 -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) @@ -1689,10 +1715,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. -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