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:
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:
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".
+ "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
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
+ default to having that modifier set. For instance, "merge,-/ .excl" would
treat the contents of .excl as absolute-path excludes.
)
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
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