X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/7432ccf4ed584b18d0cbed100901249b23819c6f..ef57235623e1a268ae96fe7fe772c493e06b0e36:/rsync.yo

diff --git a/rsync.yo b/rsync.yo
index d79f525a..f94d5d4a 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
@@ -563,9 +570,9 @@ dit(bf(-t, --times)) This tells rsync to transfer modification times along
 with the files and update them on the remote system.  Note that if this
 option is not used, the optimization that excludes files that have not been
 modified cannot be effective; in other words, a missing -t or -a will
-cause the next transfer to behave as if it used -I, and all files will have
-their checksums compared and show up in log messages even if they haven't
-changed.
+cause the next transfer to behave as if it used -I, causing all files to be
+updated (though the rsync algorithm will make the update fairly efficient
+if the files haven't actually changed, you're much better off using -t).
 
 dit(bf(-n, --dry-run)) This tells rsync to not do any file transfers,
 instead it will just report the actions it would have taken.
@@ -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.