X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/75b243a51decc0da36e13499d0e8c89c62e7bc6b..6558854dbe14f62cb3713da897b55b9dbaac43eb:/rsync.yo

diff --git a/rsync.yo b/rsync.yo
index e69ca52a..583c0109 100644
--- a/rsync.yo
+++ b/rsync.yo
@@ -306,7 +306,7 @@ verb(
  -W, --whole-file            copy whole files, no incremental checks
      --no-whole-file         turn off --whole-file
  -x, --one-file-system       don't cross filesystem boundaries
- -B, --block-size=SIZE       checksum blocking size (default 700)
+ -B, --block-size=SIZE       force a fixed checksum block-size
  -e, --rsh=COMMAND           specify the remote shell
      --rsync-path=PATH       specify path to rsync on the remote machine
      --existing              only update files that already exist
@@ -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
@@ -503,7 +504,13 @@ dit(bf(-l, --links)) When symlinks are encountered, recreate the
 symlink on the destination.
 
 dit(bf(-L, --copy-links)) When symlinks are encountered, the file that
-they point to (the referent) is copied, rather than the symlink.
+they point to (the referent) is copied, rather than the symlink.  In older
+versions of rsync, this option also had the side-effect of telling the
+receiving side to follow symlinks, such as symlinks to directories.  In a
+modern rsync such as this one, you'll need to specify --keep-dirlinks (-K)
+to get this extra behavior.  The only exception is when sending files to
+an rsync that is too old to understand -K -- in that case, the -L option
+will still have the side-effect of -K on that older receiving rsync.
 
 dit(bf(--copy-unsafe-links)) This tells rsync to copy the referent of
 symbolic links that point outside the copied tree.  Absolute symlinks
@@ -626,8 +633,9 @@ they are not empty when they are to be replaced by non-directories.  This
 is only relevant without --delete because deletions are now done depth-first.
 Requires the --recursive option (which is implied by -a) to have any effect.
 
-dit(bf(-B, --block-size=BLOCKSIZE)) This controls the block size used in
-the rsync algorithm. See the technical report for details.
+dit(bf(-B, --block-size=BLOCKSIZE)) This forces the block size used in
+the rsync algorithm to a fixed value.  It is normally selected based on
+the size of each file being updated.  See the technical report for details.
 
 dit(bf(-e, --rsh=COMMAND)) This option allows you to choose an alternative
 remote shell program to use for communication between the local and
@@ -865,6 +873,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 +1141,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 +1216,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 +1233,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