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

diff --git a/rsync.yo b/rsync.yo
index ad024e4a..f94d5d4a 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
@@ -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
@@ -487,20 +488,29 @@ from the sender.
 
 dit(bf(--inplace)) This causes rsync not to create a new copy of the file
 and then move it into place.  Instead rsync will overwrite the existing
-file, meaning that the rsync algorithm can't extract the full ammount of
+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: If the transfer is interrupted, you will have an inconsistent file
-and the transfer should be run again.
+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 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.
 
 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
@@ -560,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.
@@ -623,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
@@ -862,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.
@@ -910,12 +944,12 @@ result is an average transfer rate equaling the specified limit. A value
 of zero specifies no limit.
 
 dit(bf(--write-batch=FILE)) Record a file that can later be applied to
-anonther identical destination with --read-batch. See the "BATCH MODE"
+another identical destination with --read-batch. See the "BATCH MODE"
 section for details.
 
 dit(bf(--read-batch=FILE)) Apply all of the changes stored in FILE, a
 file previously generated by --write-batch.
-If em(FILE) is "-" the list will be read from standard input.
+If em(FILE) is "-" the batch data will be read from standard input.
 See the "BATCH MODE" section for details.
 
 dit(bf(-4, --ipv4) or bf(-6, --ipv6)) Tells rsync to prefer IPv4/IPv6
@@ -1107,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
@@ -1126,7 +1161,7 @@ using the information stored in the batch file.
 
 For convenience, one additional file is creating when the write-batch
 option is used.  This file's name is created by appending
-".rsync_argvs" to the batch filename.  The .rsync_argvs file contains
+".sh" to the batch filename.  The .sh file contains
 a command-line suitable for updating a destination tree using that
 batch file. It can be executed using a Bourne(-like) shell, optionally
 passing in an alternate destination tree pathname which is then used
@@ -1142,56 +1177,76 @@ at once, instead of sending the same data to every host individually.
 Examples:
 
 verb(
-   $ rsync --write-batch=batch -a /source/dir/ /adest/dir/
-   $ ssh remote rsync --read-batch=- -a /bdest/dir/ <batch
+   $ rsync --write-batch=foo -a host:/source/dir/ /adest/dir/
+   $ scp foo* remote:
+   $ ssh remote ./foo.sh /bdest/dir/
 )
 
 verb(
-   $ rsync --write-batch=batch -a host:/source/dir/ /adest/dir/
-   $ scp batch remote:
-   $ ssh remote rsync --read-batch=batch -a /bdest/dir/
+   $ rsync --write-batch=foo -a /source/dir/ /adest/dir/
+   $ ssh remote rsync --read-batch=- -a /bdest/dir/ <foo
 )
 
-verb(
-   $ rsync --write-batch=batch -a /source/dir/ host:/adest/dir/
-   $ scp batch* remote:
-   $ ssh remote ./batch.rsync_argvs /bdest/dir/
-)
+In these examples, rsync is used to update /adest/dir/ from /source/dir/
+and the information to repeat this operation is stored in "foo" and
+"foo.sh".  The host "remote" is then updated with the batched data going
+into the directory /bdest/dir.  The differences between the two examples
+reveals some of the flexibility you have in how you deal with batches:
+
+itemize(
 
-In these examples, rsync is used to update /adest/dir/ with /source/dir/
-and the information to repeat this operation is stored in "batch" and
-"batch.rsync_argvs".  The host "remote" is then updated with the batched
-update going into the directory /bdest/dir.  The differences between the
-three examples is in how the batch gets to the remote machine (via remote
-stdin or by being copied first), whether the initial transfer was local or
-remote, and in how the batch-reading rsync command is invoked.
+  it() The first example shows that the initial copy doesn't have to be
+  local -- you can push or pull data to/from a remote host using either the
+  remote-shell syntax or rsync daemon syntax, as desired.
+
+  it() The first example uses the created "foo.sh" file to get the right
+  rsync options when running the read-batch command on the remote host.
+
+  it() The second example reads the batch data via standard input so that
+  the batch file doesn't need to be copied to the remote machine first.
+  This example avoids the foo.sh script because it needed to use a modified
+  --read-batch option, but you could edit the script file if you wished to
+  make use of it (just be sure that no other option is trying to use
+  standard input, such as the "--exclude-from=-" option).
+
+)
 
 Caveats:
 
-The read-batch option expects the destination tree it is meant to update
+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 will 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.
 
 The rsync version used on all destinations must be at least as new as the
 one used to generate the batch file.
 
-The -n/--dryrun option does not work in batch mode and yields a runtime
+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
+shell script file.  An advanced user can use this to modify the exclude
+list if a change in what gets deleted by --delete is desired.  A normal
+user can ignore this detail and just use the shell script as an easy way
+to run the appropriate --read-batch command for the batched data.
 
 See bf(http://www.ils.unc.edu/i2dsi/unc_rsync+.html) for papers and technical
 reports.
@@ -1356,7 +1411,7 @@ and David Bell for helpful suggestions, patches and testing of rsync.
 I've probably missed some people, my apologies if I have.
 
 Especial thanks also to: David Dykstra, Jos Backus, Sebastian Krahmer,
-Martin Pool, Wayne Davison.
+Martin Pool, Wayne Davison, J.W. Schultz.
 
 manpageauthor()