X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/44d60d5f83da9595a93a6acdb3fd770d249381a4..ed243f8c29926327d901adbfeec8cf25947cc88d:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 1f6a41cc..34541606 100644 --- 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. -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 @@ -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 -.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. @@ -997,23 +1011,24 @@ it is more desirable to keep partially transferred files. Using the bf(--partial) option tells rsync to keep the partial file which should make a subsequent transfer of the rest of the file much faster. -dit(bf(--partial-dir=DIR)) Turns on bf(--partial) mode, but tells rsync to -put a partially transferred file into em(DIR) instead of writing out the -file to the destination dir. Rsync will also use a file found in this -dir as data to speed up the transfer (i.e. when you redo the send after -rsync creates a partial file) and delete such a file after it has served -its purpose. Note that if bf(--whole-file) is specified (or implied) that an -existing partial-dir file will not be used to speedup the transfer (since +dit(bf(--partial-dir=DIR)) A better way to keep partial files than the +bf(--partial) option is to specify a em(DIR) that will be used to hold the +partial data (instead of writing it out to the destination file). +On the next transfer, rsync will use a file found in this +dir as data to speed up the resumption of the transfer and then deletes it +after it has served its purpose. +Note that if bf(--whole-file) is specified (or implied), any partial-dir +file that is found for a file that is being updated will simply be removed +(since rsync is sending files without using the incremental rsync algorithm). -Rsync will create the dir if it is missing (just the last dir -- not the -whole path). This makes it easy to use a relative path (such as -"bf(--partial-dir=.rsync-partial)") to have rsync create the partial-directory -in the destination file's directory (rsync will also try to remove the em(DIR) -if a partial file was found to exist at the start of the transfer and the -DIR was specified as a relative path). +Rsync will create the em(DIR) if it is missing (just the last dir -- not +the whole path). This makes it easy to use a relative path (such as +"bf(--partial-dir=.rsync-partial)") to have rsync create the +partial-directory in the destination file's directory when needed, and then +remove it again when the partial file is deleted. -If the partial-dir value is not an absolute path, rsync will also add an +If the partial-dir value is not an absolute path, rsync will also add a directory bf(--exclude) of this value at the end of all your existing excludes. This will prevent partial-dir files from being transferred and also prevent the untimely deletion of partial-dir items on the receiving side. An example: @@ -1022,7 +1037,8 @@ rule at the end of any other filter rules. Note that if you are supplying your own filter rules, you may need to manually insert a rule for this directory exclusion somewhere higher up in the list so that it has a high enough priority to be effective (e.g., if your rules specify -a trailing bf(--exclude='*') rule, the auto-added rule will be ineffective). +a trailing bf(--exclude='*') rule, the auto-added rule would never be +reached). IMPORTANT: the bf(--partial-dir) should not be writable by other users or it is a security risk. E.g. AVOID "/tmp". @@ -1038,13 +1054,22 @@ option does not look for this environment value is (1) when bf(--inplace) was specified (since bf(--inplace) conflicts with bf(--partial-dir)), or (2) when bf(--delay-updates) was specified (see below). +For the purposes of the server-config's "refuse options" setting, +bf(--partial-dir) does em(not) imply bf(--partial). This is so that a +refusal of the bf(--partial) option can be used to disallow the overwriting +of destination files with a partial transfer, while still allowing the +safer idiom provided by bf(--partial-dir). + dit(bf(--delay-updates)) This option puts the temporary file from each -updated file into the file's partial-dir (see above) until the end of the +updated file into a holding directory until the end of the transfer, at which time all the files are renamed into place in rapid succession. This attempts to make the updating of the files a little more -atomic. If you don't specify the bf(--partial-dir) option, this option will -cause it to default to ".~tmp~" (RSYNC_PARTIAL_DIR is not consulted for -this value). Conflicts with bf(--inplace). +atomic. By default the files are placed into a directory named ".~tmp~" in +each file's destination directory, but you can override this by specifying +the bf(--partial-dir) option. (Note that RSYNC_PARTIAL_DIR has no effect +on this value, nor is bf(--partial-dir) considered to be implied for the +purposes of the server-config's "refuse options" setting.) +Conflicts with bf(--inplace). This option uses more memory on the receiving side (one bit per file transferred) and also requires enough free disk space on the receiving @@ -1061,7 +1086,7 @@ parallel hierarchy of files). dit(bf(--progress)) This option tells rsync to print information showing the progress of the transfer. This gives a bored user something to watch. -Implies bf(--verbose) without incrementing verbosity. +Implies bf(--verbose) if it wasn't already specified. When the file is transferring, the data looks like this: @@ -1215,45 +1240,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 @@ -1309,8 +1339,8 @@ tt(- *)nl() This fails because the parent directory "some" is excluded by the '*' rule, so rsync never visits any of the files in the "some" or "some/path" directories. One solution is to ask for all directories in the hierarchy -to be included by using a single rule: "+_*/" (put it somewhere before the -"-_*" rule). Another solution is to add specific include rules for all +to be included by using a single rule: "+ */" (put it somewhere before the +"- *" rule). Another solution is to add specific include rules for all the parent dirs that need to be visited. For instance, this set of rules works fine: @@ -1342,8 +1372,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 +1390,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 "-": @@ -1392,35 +1427,38 @@ 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 + "-/ /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 -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 +1497,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 +1518,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 +1727,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