X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/d91de04671de9138da2c918357f1fdc199d25304..ed243f8c29926327d901adbfeec8cf25947cc88d:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 48ba5f2d..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 @@ -1010,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: @@ -1035,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". @@ -1051,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 @@ -1074,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: @@ -1327,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: @@ -1397,7 +1409,7 @@ itemize( 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 @@ -1406,7 +1418,7 @@ itemize( 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. ) @@ -1415,7 +1427,7 @@ 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 @@ -1423,7 +1435,7 @@ itemize( 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