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

diff --git a/rsync.yo b/rsync.yo
index 0f07c46b..e69ca52a 100644
--- a/rsync.yo
+++ b/rsync.yo
@@ -289,6 +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 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
@@ -484,6 +485,20 @@ dit(bf(-K, --keep-dirlinks)) On the receiving side, if a symlink is
 pointing to a directory, it will be treated as matching a directory
 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 amount of
+network reduction it might otherwise.
+
+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 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.
 
@@ -512,9 +527,9 @@ This option can be quite slow, so only use it if you need it.
 dit(bf(-W, --whole-file)) With this option the incremental rsync algorithm
 is not used and the whole file is sent as-is instead.  The transfer may be
 faster if this option is used when the bandwidth between the source and
-target machines is higher than the bandwidth to disk (especially when the
+destination machines is higher than the bandwidth to disk (especially when the
 "disk" is actually a networked filesystem).  This is the default when both
-the source and target are on the local machine.
+the source and destination are specified as local paths.
 
 dit(bf(--no-whole-file)) Turn off --whole-file, for use when it is the
 default.
@@ -686,11 +701,11 @@ See the EXCLUDE PATTERNS section for detailed information on this option.
 
 dit(bf(--include-from=FILE)) This specifies a list of include patterns
 from a file.
-If em(FILE) is bf(-) the list will be read from standard input.
+If em(FILE) is "-" the list will be read from standard input.
 
 dit(bf(--files-from=FILE)) Using this option allows you to specify the
 exact list of files to transfer (as read from the specified FILE or "-"
-for stdin).  It also tweaks the default behavior of rsync to make
+for standard input).  It also tweaks the default behavior of rsync to make
 transferring just the specified files and directories easier.  For
 instance, the --relative option is enabled by default when this option
 is used (use --no-relative if you want to turn that off), all
@@ -898,12 +913,13 @@ 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. See the "BATCH MODE"
-section for details.
+file previously generated by --write-batch.
+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
 when creating sockets.  This only affects sockets that rsync has direct
@@ -1113,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
@@ -1126,29 +1142,49 @@ updating multiple destination trees. Multicast transport protocols can
 be used to transfer the batch update files in parallel to many hosts
 at once, instead of sending the same data to every host individually.
 
-Example:
+Examples:
+
+verb(
+   $ 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 /source/dir/ /adest/dir/
-   $ rcp batch* remote:
-   $ ssh remote rsync --read-batch=batch -a /bdest/dir/
-   # or alternatively
-   $ ssh remote ./batch.rsync_argvs /bdest/dir/
+   $ rsync --write-batch=foo -a /source/dir/ /adest/dir/
+   $ ssh remote rsync --read-batch=- -a /bdest/dir/ <foo
 )
 
-In this example, 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". These files are then copied to the machine named
-"remote".  Rsync is then invoked on "remote" to update /bdest/dir/ the
-same way as /adest/dir/. The last line shows the rsync_argvs file
-being used to invoke rsync.
+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(
+
+  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.
@@ -1156,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
@@ -1170,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.
 
@@ -1333,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()