X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/98f51bfb567c794959e41e101842e098f712eb92..bb6721dce6bac8ff2374609bf5f99ea7e6fe2c70:/rsync.yo diff --git a/rsync.yo b/rsync.yo index c48505a4..ec76d7d9 100644 --- a/rsync.yo +++ b/rsync.yo @@ -289,7 +289,7 @@ verb( --backup-dir make backups into this directory --suffix=SUFFIX backup suffix (default ~ w/o --backup-dir) -u, --update update only (don't overwrite newer files) - --inplace update the destination file inplace + --inplace update the destination files inplace -K, --keep-dirlinks treat symlinked dir on receiver as dir -l, --links copy symlinks as symlinks -L, --copy-links copy the referent of all symlinks @@ -317,6 +317,7 @@ verb( --ignore-errors delete even if there are I/O errors --max-delete=NUM don't delete more than NUM files --partial keep partially transferred files + --partial-dir=DIR put a partially transferred file into DIR --force force deletion of dirs even if not empty --numeric-ids don't map uid/gid values by user/group name --timeout=TIME set I/O timeout in seconds @@ -490,14 +491,14 @@ and then move it into place. Instead rsync will overwrite the existing file, meaning that the rsync algorithm can't extract the full amount of network reduction it might otherwise. -This option is useful for transfer of large files with block based changes -and also on systems that are disk bound not network bound. +This option is useful for transfer of large files with block-based change +or appended data, and also on systems that are disk bound not network bound. WARNING: The file's data will be in an inconsistent state during the transfer (and possibly afterward if the transfer gets interrupted), so you should not use this option to update files that are in use. Also note that -rsync will not update a file inplace that is not writable by the receiving -user. +rsync will be unable to update a file inplace that is not writable by the +receiving user. dit(bf(-l, --links)) When symlinks are encountered, recreate the symlink on the destination. @@ -865,6 +866,29 @@ it is more desirable to keep partially transferred files. Using the --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 --partial mode, but tells rsync to +put a partially transferred file into 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. + +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 +"--partial-dir=.rsync-partial") to have rsync create the partial-directory +in the destination file's directory (rsync will also try to remove the DIR +if a partial file was found to exist at the start of the transfer and the +DIR was specified as a relative path). + +If you are deleting files on the destination and your partial-dir is +inside the destination hierarchy, make sure you specify an exclude to +prevent the partial file from being deleted (it could get deleted at the +end of the transfer when using --delete-after, or at the beginning of the +transfer when using --delete). E.g. "--exclude=.rsync-partial/". + +IMPORTANT: the --partial-dir should not be writable by other users to +avoid a security risk. E.g. AVOID "/tmp". + dit(bf(--progress)) This option tells rsync to print information showing the progress of the transfer. This gives a bored user something to watch. @@ -1110,7 +1134,8 @@ itemize( manpagesection(BATCH MODE) bf(Note:) Batch mode should be considered experimental in this version -of rsync. The interface or behavior may change before it stabilizes. +of rsync. The interface and behavior have now stabilized, though, so +feel free to try this out. Batch mode can be used to apply the same set of updates to many identical systems. Suppose one has a tree which is replicated on a @@ -1184,8 +1209,14 @@ Caveats: The read-batch option expects the destination tree that it is updating to be identical to the destination tree that was used to create the batch update fileset. When a difference between the destination trees -is encountered the update might fail at that point, leaving the -destination tree in a partially updated state. In that case, rsync can +is encountered the update might be discarded with no error (if the file +appears to be up-to-date already) or the file-update may be attempted +and then, if the file fails to verify, the update discarded with an +error. This means that it should be safe to re-run a read-batch operation +if the command got updated. If you wish to force the batched-update to +always be attempted regardless of the file's size and date, use the -I +option. If an error occurs, the destination tree will probably be in a +partially updated state. In that case, rsync can be used in its regular (non-batch) mode of operation to fix up the destination tree. @@ -1195,16 +1226,13 @@ one used to generate the batch file. The --dry-run (-n) option does not work in batch mode and yields a runtime error. -You should use an equivalent set of options when reading a batch file that -you used when generating it with a few exceptions. For instance +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 --write-batch changes to --read-batch, --files-from is dropped, and the --include/--exclude options are not needed unless --delete is specified -without --delete-excluded. Other options that affect how the update -happens should generally remain the same as it is possible to confuse rsync -into expecting a different data stream than the one that is contained in -the batch file. For example, it would not work to change the setting of -the -H or -c option, but it would work to add or remove the --delete -option. +without --delete-excluded. The code that creates the BATCH.sh file transforms any include/exclude options into a single list that is appended as a "here" document to the