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
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.
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:
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".
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
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:
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 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.
-)
+ 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