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

diff --git a/rsync.yo b/rsync.yo
index ad024e4a..e69ca52a 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
@@ -487,14 +487,17 @@ 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.
@@ -910,12 +913,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
@@ -1126,7 +1129,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,36 +1145,46 @@ 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
+is encountered the update might fail at that point, leaving the
 destination tree 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.
@@ -1179,7 +1192,7 @@ 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
@@ -1193,6 +1206,13 @@ 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.
 
+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 +1376,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()