X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/24d677fc16b62a3b6c320e3edb5016b5fa193e8b..27999abab48979c7306a1c335f8e264c6c200457:/rsync.yo

diff --git a/rsync.yo b/rsync.yo
index 7fccd1db..a98d1eab 100644
--- a/rsync.yo
+++ b/rsync.yo
@@ -333,6 +333,7 @@ to the detailed description below for a complete description.  verb(
  -u, --update                skip files that are newer on the receiver
      --inplace               update destination files in-place
      --append                append data onto shorter files
+     --append-verify         --append w/old data in file cheksum
  -d, --dirs                  transfer directories without recursing
  -l, --links                 copy symlinks as symlinks
  -L, --copy-links            transform symlink into referent file/dir
@@ -404,6 +405,7 @@ to the detailed description below for a complete description.  verb(
      --include-from=FILE     read include patterns from FILE
      --files-from=FILE       read list of source-file names from FILE
  -0, --from0                 all *from/filter files are delimited by 0s
+ -s, --protect-args          no space-splitting; wildcard chars only
      --address=ADDRESS       bind address for outgoing socket to daemon
      --port=PORT             specify double-colon alternate port number
      --sockopts=OPTIONS      specify custom TCP options
@@ -570,19 +572,21 @@ Beginning with rsync 3.0.0, the recursive algorithm used is now an
 incremental scan that uses much less memory than before and begins the
 transfer after the scanning of the first few directories have been
 completed.  This incremental scan only affects our recursion algorithm, and
-does not change a non-recursive transfer.
-It is also only possible when both ends of the
-transfer are at least version 3.0.0.
+does not change a non-recursive transfer.  It is also only possible when
+both ends of the transfer are at least version 3.0.0.
 
 Some options require rsync to know the full file list, so these options
 disable the incremental recursion mode.  These include: bf(--delete-before),
-bf(--delete-after), bf(--prune-empty-dirs), bf(--delay-updates), and bf(--hard-links).
+bf(--delete-after), bf(--prune-empty-dirs), and bf(--delay-updates).
 Because of this, the default delete mode when you specify bf(--delete) is now
 bf(--delete-during) when both ends of the connection are at least 3.0.0
 (use bf(--del) or bf(--delete-during) to request this improved deletion mode
 explicitly).  See also the bf(--delete-delay) option that is a better choice
 than using bf(--delete-after).
 
+Incremental recursion can be disabled using the bf(--no-inc-recursive)
+option or its shorter bf(--no-i-r) alias.
+
 dit(bf(-R, --relative)) Use relative paths. This means that the full path
 names specified on the command line are sent to the server rather than
 just the last parts of the filenames. This is particularly useful when
@@ -716,13 +720,22 @@ receiving user.
 dit(bf(--append)) This causes rsync to update a file by appending data onto
 the end of the file, which presumes that the data that already exists on
 the receiving side is identical with the start of the file on the sending
-side.  If that is not true, the file will fail the checksum test, and the
-resend will do a normal bf(--inplace) update to correct the mismatched data.
-Only files on the receiving side that are shorter than the corresponding
-file on the sending side (as well as new files) are transferred.
-Implies bf(--inplace), but does not conflict with bf(--sparse) (though the
-bf(--sparse) option will be auto-disabled if a resend of the already-existing
-data is required).
+side.  Any files that are the same size or shorter on the receiving size
+are skipped.  Files that do not yet exist on the receiving side are also
+sent, since they are considered to have 0 length.  Implies bf(--inplace),
+but does not conflict with bf(--sparse) (since it is always extending a
+file's length).
+
+dit(bf(--append-verify)) This works just like the bf(--append) option, but
+the existing data on the receiving side is included in the full-file
+checksum verification step, which will cause a file to be resent if the
+final verification step fails (rsync uses a normal, non-appending
+bf(--inplace) transfer for the resend).
+
+Note: prior to rsync 3.0.0, the bf(--append) option worked like
+bf(--append-verify), so if you are interacting with an older rsync (or the
+transfer is using a protocol prior to 30), specifying either append option
+will initiate an bf(--append-verify) transfer.
 
 dit(bf(-d, --dirs)) Tell the sending side to include any directories that
 are encountered.  Unlike bf(--recursive), a directory's contents are not copied
@@ -790,6 +803,12 @@ as though they were separate files.
 Note that rsync can only detect hard links if both parts of the link
 are in the list of files being sent.
 
+If incremental recursion is active (see bf(--recursive)), rsync may transfer
+a missing hard-linked file before it finds that another link for the file
+exists elsewhere in the hierarchy.  This does not affect the accuracy of
+the transfer, just its efficiency.  One way to avoid this is to disable
+incremental recursion using the bf(--no-inc-recursive) option.
+
 dit(bf(-p, --perms)) This option causes the receiving rsync to set the
 destination permissions to be the same as the source permissions.  (See
 also the bf(--chmod) option for a way to modify what rsync considers to
@@ -1334,6 +1353,21 @@ merged files specified in a bf(--filter) rule.
 It does not affect bf(--cvs-exclude) (since all names read from a .cvsignore
 file are split on whitespace).
 
+If the bf(--iconv) and bf(--protect-args) options are specified and the
+bf(--files-from) filenames are being sent from one host to another, the
+filenames will be translated from the sending host's charset to the
+receiving host's charset.
+
+dit(bf(-s, --protect-args)) This option sends all filenames and some options to
+the remote rsync without allowing the remote shell to interpret them.  This
+means that spaces are not split in names, and any non-wildcard special
+characters are not translated (such as ~, $, ;, &, etc.).  Wildcards are
+expanded on the remote host by rsync (instead of the shell doing it).
+
+If you use this option with bf(--iconv), the args will also be translated
+from the local to the remote character set.  The translation happens before
+wild-cards are expanded.  See also the bf(--files-from) option.
+
 dit(bf(-T, --temp-dir=DIR)) This option instructs rsync to use DIR as a
 scratch directory when creating temporary copies of the files transferred
 on the receiving side.  The default behavior is to create each temporary
@@ -1935,14 +1969,15 @@ Finally, you can specify a CONVERT_SPEC of "-" to turn off any conversion.
 The default setting of this option is site-specific, and can also be
 affected via the RSYNC_ICONV environment variable.
 
+If you specify the bf(--protect-args) option (bf(-s)), rsync will translate
+the filenames you specify on the command-line that are being sent to the
+remote host.  See also the bf(--files-from) option.
+
 Note that rsync does not do any conversion of names in filter files
-(including include/exclude files), in a files-from file, nor those
-specified on the command line.  It is up to you to ensure that you're
-requesting the right names from a remote server, and you can specify
-extra include/exclude rules if there are filename differences on the
-two sides that need to be accounted for.  (In the future there may be
-a way to specify a UTF-8 filter rule that gets auto-converted to the
-local side's character set.)
+(including include/exclude files).  It is up to you to ensure that you're
+specifying matching rules that can match on both sides of the transfer.
+For instance, you can specify extra include/exclude rules if there are
+filename differences on the two sides that need to be accounted for.
 
 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