X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/fb72aaba486c6a630011db58cf96063fc1d0f21e..a0d9819f8c6ba64930d3858f7b01e4d9250d5369:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 6ddfe221..2cff1350 100644 --- a/rsync.yo +++ b/rsync.yo @@ -349,7 +349,7 @@ to the detailed description below for a complete description. verb( --partial keep partially transferred files --partial-dir=DIR put a partially transferred file into DIR --delay-updates put all updated files into place at end - -k, --skip-empty-dirs skip empty directory chains + -m, --prune-empty-dirs prune empty directory chains from file-list --numeric-ids don't map uid/gid values by user/group name --timeout=TIME set I/O timeout in seconds -I, --ignore-times don't skip files that match size and time @@ -498,7 +498,7 @@ could specify bf(-a --no-o) (or bf(-a --no-owner)). The order of the options is important: if you specify bf(--no-r -a), the bf(-r) option would end up being turned on, the opposite of bf(-a --no-r). Note also that the side-effects of the bf(--files-from) option are NOT -positional, as it affects the default state of several options and sligntly +positional, as it affects the default state of several options and slightly changes the meaning of bf(-a) (see the bf(--files-from) option for more details). @@ -1074,9 +1074,36 @@ It does not affect bf(--cvs-exclude) (since all names read from a .cvsignore file are split on whitespace). dit(bf(-T, --temp-dir=DIR)) This option instructs rsync to use DIR as a -scratch directory when creating temporary copies of the files -transferred on the receiving side. The default behavior is to create -the temporary files in the receiving directory. +scratch directory when creating temporary copies of the files transferred +on the receiving side. The default behavior is to create each temporary +file in the same directory as the associated destination file. + +This option is most often used when the receiving disk partition does not +have enough free space to hold a copy of the largest file in the transfer. +In this case (i.e. when the scratch directory in on a different disk +partition), rsync will not be able to rename each received temporary file +over the top of the associated destination file, but instead must copy it +into place. Rsync does this by copying the file over the top of the +destination file, which means that the destination file will contain +truncated data during this copy. If this were not done this way (even if +the destination file were first removed, the data locally copied to a +temporary file in the destination directory, and then renamed into place) +it would be possible for the old file to continue taking up disk space (if +someone had it open), and thus there might not be enough room to fit the +new version on the disk at the same time. + +If you are using this option for reasons other than a shortage of disk +space, you may wish to combine it with the bf(--delay-updates) option, +which will ensure that all copied files get put into subdirectories in the +destination hierarchy, awaiting the end of the transfer. If you don't +have enough room to duplicate all the arriving files on the destination +partition, another way to tell rsync that you aren't overly concerned +about disk space is to use the bf(--partial-dir) option with a relative +path; because this tells rsync that it is OK to stash off a copy of a +single file in a subdir in the destination hierarchy, rsync will use the +partial-dir as a staging area to bring over the copied file, and then +rename it into place from there. (Specifying a bf(--partial-dir) with +an absolute path does not have this side-effect.) dit(bf(-y, --fuzzy)) This option tells rsync that it should look for a basis file for any destination file that is missing. The current algorithm @@ -1286,7 +1313,7 @@ item that is changed in any way (as long as the receiving side is at least output of "%i". The bf(--verbose) option implies a format of "%n%L", but you can use -bf(--log-format) without bv(--verbose) if you like, or you can override +bf(--log-format) without bf(--verbose) if you like, or you can override the format of its per-file output using this option. Rsync will output the log-format string prior to a file's transfer unless @@ -1317,8 +1344,9 @@ 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 +dir as data to speed up the resumption of the transfer and then delete 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 @@ -1351,9 +1379,9 @@ enabled, but rather it effects where partial files go when bf(--partial) is specified. For instance, instead of using bf(--partial-dir=.rsync-tmp) along with bf(--progress), you could set RSYNC_PARTIAL_DIR=.rsync-tmp in your environment and then just use the bf(-P) option to turn on the use of the -.rsync-tmp dir for partial transfers. The only time that the bf(--partial) -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 +.rsync-tmp dir for partial transfers. The only times that the bf(--partial) +option does not look for this environment value are (1) when bf(--inplace) was +specified (since bf(--inplace) conflicts with bf(--partial-dir)), and (2) when bf(--delay-updates) was specified (see below). For the purposes of the daemon-config's "refuse options" setting, @@ -1386,21 +1414,35 @@ See also the "atomic-rsync" perl script in the "support" subdir for an update algorithm that is even more atomic (it uses bf(--link-dest) and a parallel hierarchy of files). -dit(bf(-k, --skip-empty-dirs)) This option tells the receiving rsync to get +dit(bf(-m, --prune-empty-dirs)) This option tells the receiving rsync to get rid of empty directories from the file-list, including nested directories that have no non-directory children. This is useful for avoiding the creation of a bunch of useless directories when the sending rsync is recursively scanning a hierarchy of files using include/exclude/filter -directives. This also affects what directories get deleted when a delete -option was specified (but keep in mind that excluded files are also -protected from deletion). +rules. + +Because the file-list is actually being pruned, this option also affects +what directories get deleted when a delete is active. However, keep in +mind that excluded files and directories can prevent existing items from +being deleted (because an exclude hides source files and protects +destination files). + +You can prevent the pruning of certain empty directories from the file-list +by using a global "protect" filter. For instance, this option would ensure +that the directory "emptydir" was kept in the file-list: + +quote( --filter 'protect emptydir/') Here's an example that copies all .pdf files in a hierarchy, only creating the necessary destination directories to hold the .pdf files, and ensures that any superfluous files and directories in the destination are removed -(due to a hide filter on non-directories being used instead of an exclude): +(note the hide filter of non-directories being used instead of an exclude): + +quote( rsync -avm --del --include='*.pdf' -f 'hide! */' src/ dest) -quote( rsync -avk --del --include='*.pdf' -f 'hide! */' src/ dest) +If you didn't want to remove superfluous destination files, the more +time-honored options of "--include='*/' --exclude='*'" would work fine +in place of the hide-filter (if that is more natural to you). dit(bf(--progress)) This option tells rsync to print information showing the progress of the transfer. This gives a bored user