Tweaked a sentence in the --size-only section.
[rsync/rsync.git] / rsync.yo
index 8b7422e..3af7e1b 100644 (file)
--- a/rsync.yo
+++ b/rsync.yo
@@ -1,5 +1,5 @@
 mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(26 Oct 2006)()()
+manpage(rsync)(1)(6 Nov 2006)()()
 manpagename(rsync)(faster, flexible replacement for rcp)
 manpagesynopsis()
 
@@ -21,7 +21,7 @@ rsync [OPTION]... rsync://[USER@]HOST[:PORT]/SRC [DEST]
 
 manpagedescription()
 
-rsync is a program that behaves in much the same way that rcp does,
+Rsync is a program that behaves in much the same way that rcp does,
 but has many more options and uses the rsync remote-update protocol to
 greatly speed up file transfers when the destination file is being
 updated.
@@ -31,6 +31,12 @@ differences between two sets of files across the network connection, using
 an efficient checksum-search algorithm described in the technical
 report that accompanies this package.
 
+Rsync finds files that need to be transferred using a "quick check" algorithm
+that looks for files that have changed in size or in last-modified time (by
+default).  Any changes in the other preserved attributes (as requested by
+options) are made on the destination file directly when the quick check
+indicates that the file's data does not need to be updated.
+
 Some of the additional features of rsync are:
 
 itemization(
@@ -301,7 +307,7 @@ to the detailed description below for a complete description.  verb(
  -q, --quiet                 suppress non-error messages
      --no-motd               suppress daemon-mode MOTD (see caveat)
  -c, --checksum              skip based on checksum, not mod-time & size
- -a, --archive               archive mode; same as -rlptgoD (no -H)
+ -a, --archive               archive mode; equals -rlptgoD (no -H,-A,-X)
      --no-OPTION             turn off an implied OPTION (e.g. --no-D)
  -r, --recursive             recurse into directories
  -R, --relative              use relative path names
@@ -323,6 +329,8 @@ to the detailed description below for a complete description.  verb(
  -p, --perms                 preserve permissions
  -E, --executability         preserve executability
      --chmod=CHMOD           affect file and/or directory permissions
+ -A, --acls                  preserve ACLs (implies -p)
+ -X, --xattrs                preserve extended attrs (implies -p)
  -o, --owner                 preserve owner (super-user only)
  -g, --group                 preserve group
      --devices               preserve device files (super-user only)
@@ -331,6 +339,7 @@ to the detailed description below for a complete description.  verb(
  -t, --times                 preserve times
  -O, --omit-dir-times        omit directories when preserving times
      --super                 receiver attempts super-user activities
+     --fake-super            store/recover privileged attrs using xattrs
  -S, --sparse                handle sparse files efficiently
  -n, --dry-run               show what would have been transferred
  -W, --whole-file            copy files whole (without rsync algorithm)
@@ -345,6 +354,7 @@ to the detailed description below for a complete description.  verb(
      --delete                delete extraneous files from dest dirs
      --delete-before         receiver deletes before transfer (default)
      --delete-during         receiver deletes during xfer, not before
+     --delete-delay          find deletions during, delete after
      --delete-after          receiver deletes after transfer, not before
      --delete-excluded       also delete excluded files from dest dirs
      --ignore-errors         delete even if there are I/O errors
@@ -391,13 +401,14 @@ to the detailed description below for a complete description.  verb(
      --out-format=FORMAT     output updates using the specified FORMAT
      --log-file=FILE         log what we're doing to the specified FILE
      --log-file-format=FMT   log updates using the specified FMT
-     --password-file=FILE    read password from FILE
+     --password-file=FILE    read daemon-access password from FILE
      --list-only             list the files instead of copying them
      --bwlimit=KBPS          limit I/O bandwidth; KBytes per second
      --write-batch=FILE      write a batched update to FILE
      --only-write-batch=FILE like --write-batch but w/o updating dest
      --read-batch=FILE       read a batched update from FILE
      --protocol=NUM          force an older protocol version to be used
+     --iconv=CONVERT_SPEC    request charset conversion of filesnames
      --checksum-seed=NUM     set block/file checksum seed (advanced)
  -4, --ipv4                  prefer IPv4
  -6, --ipv6                  prefer IPv6
@@ -463,19 +474,19 @@ by the client at the start of a daemon transfer.  This suppresses the
 message-of-the-day (MOTD) text, but it also affects the list of modules
 that the daemon sends in response to the "rsync host::" request (due to
 a limitation in the rsync protocol), so omit this option if you want to
-request the list of modules from the deamon.
+request the list of modules from the daemon.
 
 dit(bf(-I, --ignore-times)) Normally rsync will skip any files that are
-already the same size and have the same modification time-stamp.
+already the same size and have the same modification timestamp.
 This option turns off this "quick check" behavior, causing all files to
 be updated.
 
-dit(bf(--size-only)) Normally rsync will not transfer any files that are
-already the same size and have the same modification time-stamp. With the
-bf(--size-only) option, files will not be transferred if they have the same size,
-regardless of timestamp. This is useful when starting to use rsync
-after using another mirroring system which may not preserve timestamps
-exactly.
+dit(bf(--size-only)) This modifies rsync's "quick check" algorithm for
+finding files that need to be transferred, changing it from the default of
+transferring files with either a changed size or a changed last-modified
+time to just looking for files that have changed in size.  This is useful
+when starting to use rsync after using another mirroring system which may
+not preserve timestamps exactly.
 
 dit(bf(--modify-window)) When comparing two timestamps, rsync treats the
 timestamps as being equal if they differ by no more than the modify-window
@@ -485,20 +496,26 @@ transferring to or from an MS Windows FAT filesystem (which represents
 times with a 2-second resolution), bf(--modify-window=1) is useful
 (allowing times to differ by up to 1 second).
 
-dit(bf(-c, --checksum)) This forces the sender to checksum em(every)
-regular file using a 128-bit MD4 checksum.  It does this during the initial
-file-system scan as it builds the list of all available files. The receiver
-then checksums its version of each file (if it exists and it has the same
-size as its sender-side counterpart) in order to decide which files need to
-be updated: files with either a changed size or a changed checksum are
-selected for transfer.  Since this whole-file checksumming of all files on
-both sides of the connection occurs in addition to the automatic checksum
-verifications that occur during a file's transfer, this option can be quite
-slow.
-
-Note that rsync always verifies that each em(transferred) file was correctly
-reconstructed on the receiving side by checking its whole-file checksum, but
-that automatic after-the-transfer verification has nothing to do with this
+dit(bf(-c, --checksum)) This changes the way rsync checks if the files have
+been changed and are in need of a transfer.  Without this option, rsync
+uses a "quick check" that (by default) checks if each file's size and time
+of last modification match between the sender and receiver.  This option
+changes this to compare a 128-bit MD4 checksum for each file that has a
+matching size.  Generating the checksums means that both sides will expend
+a lot of disk I/O reading all the data in the files in the transfer (and
+this is prior to any reading that will be done to transfer changed files),
+so this can slow things down significantly.
+
+The sending side generates its checksums while it is doing the file-system
+scan that builds the list of the available files.  The receiver generates
+its checksums when it is scanning for changed files, and will checksum any
+file that has the same size as the corresponding sender's file:  files with
+either a changed size or a changed checksum are selected for transfer.
+
+Note that rsync always verifies that each em(transferred) file was
+correctly reconstructed on the receiving side by checking a whole-file
+checksum that is generated when as the file is transferred, but that
+automatic after-the-transfer verification has nothing to do with this
 option's before-the-transfer "Does this file need to be updated?" check.
 
 dit(bf(-a, --archive)) This is equivalent to bf(-rlptgoD). It is a quick
@@ -533,6 +550,23 @@ details).
 dit(bf(-r, --recursive)) This tells rsync to copy directories
 recursively.  See also bf(--dirs) (bf(-d)).
 
+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 (e.g. when using a fully-specified
+bf(--files-from) list).  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).
+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).
+
 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
@@ -610,7 +644,7 @@ Note that if you don't specify bf(--backup-dir), (1) the
 bf(--omit-dir-times) option will be implied, and (2) if bf(--delete) is
 also in effect (without bf(--delete-excluded)), rsync will add a "protect"
 filter-rule for the backup suffix to the end of all your existing excludes
-(e.g. -f "P *~").  This will prevent previously backed-up files from being
+(e.g. bf(-f "Pp *~")).  This will prevent previously backed-up files from being
 deleted.  Note that if you are supplying your own filter rules, you may
 need to manually insert your own exclude/protect rule somewhere higher up
 in the list so that it has a high enough priority to be effective (e.g., if
@@ -706,7 +740,7 @@ which point outside the copied tree. All absolute symlinks are
 also ignored. Using this option in conjunction with bf(--relative) may
 give unexpected results.
 
-dit(bf(-K, --copy-dirlinks)) This option causes the sending side to treat
+dit(bf(-k, --copy-dirlinks)) This option causes the sending side to treat
 a symlink to a directory as though it were a real directory.  This is
 useful if you don't want symlinks to non-directories to be affected, as
 they would be using bf(--copy-links).
@@ -753,7 +787,9 @@ quote(itemization(
   permissions, though the bf(--executability) option might change just
   the execute permission for the file.
   it() New files get their "normal" permission bits set to the source
-  file's permissions masked with the receiving end's umask setting, and
+  file's permissions masked with the receiving directory's default
+  permissions (either the receiving process's umask, or the permissions
+  specified via the destination directory's default ACL), and
   their special permission bits disabled except in the case where a new
   directory inherits a setgid bit from its parent directory.
 ))
@@ -784,9 +820,11 @@ The preservation of the destination's setgid bit on newly-created
 directories when bf(--perms) is off was added in rsync 2.6.7.  Older rsync
 versions erroneously preserved the three special permission bits for
 newly-created files when bf(--perms) was off, while overriding the
-destination's setgid bit setting on a newly-created directory.  (Keep in
-mind that it is the version of the receiving rsync that affects this
-behavior.)
+destination's setgid bit setting on a newly-created directory.  Default ACL
+observance was added to the ACL patch for rsync 2.6.7, so older (or
+non-ACL-enabled) rsyncs use the umask even if default ACLs are present.
+(Keep in mind that it is the version of the receiving rsync that affects
+these behaviors.)
 
 dit(bf(-E, --executability)) This option causes rsync to preserve the
 executability (or non-executability) of regular files when bf(--perms) is
@@ -804,6 +842,15 @@ quote(itemization(
 
 If bf(--perms) is enabled, this option is ignored.
 
+dit(bf(-A, --acls)) This option causes rsync to update the destination
+ACLs to be the same as the source ACLs.  This nonstandard option only
+works if the remote rsync also supports it.  bf(--acls) implies bf(--perms).
+
+dit(bf(-X, --xattrs)) This option causes rsync to update the remote
+extended attributes to be the same as the local ones.  This will work
+only if the remote machine's rsync supports this option also. This is
+a non-standard option.
+
 dit(bf(--chmod)) This option tells rsync to apply one or more
 comma-separated "chmod" strings to the permission of the files in the
 transfer.  The resulting value is treated as though it was the permissions
@@ -826,7 +873,7 @@ permission value can be applied to the files in the transfer.
 dit(bf(-o, --owner)) This option causes rsync to set the owner of the
 destination file to be the same as the source file, but only if the
 receiving rsync is being run as the super-user (see also the bf(--super)
-option to force rsync to attempt super-user activities).
+and bf(--fake-super) options).
 Without this option, the owner is set to the invoking user on the
 receiving side.
 
@@ -849,7 +896,7 @@ default, but may fall back to using the ID number in some circumstances
 dit(bf(--devices)) This option causes rsync to transfer character and
 block device files to the remote system to recreate these devices.
 This option has no effect if the receiving rsync is not run as the
-super-user and bf(--super) is not specified.
+super-user (see also the bf(--super) and bf(--fake-super) options).
 
 dit(bf(--specials)) This option causes rsync to transfer special files
 such as named sockets and fifos.
@@ -879,6 +926,34 @@ also for ensuring that you will get errors if the receiving side isn't
 being running as the super-user.  To turn off super-user activities, the
 super-user can use bf(--no-super).
 
+dit(bf(--fake-super)) When this option is enabled, rsync simulates
+super-user activities by saving/restoring the privileged attributes via a
+special extended attribute that is attached to each file (as needed).  This
+includes the file's owner and group (if it is not the default), the file's
+device info (device & special files are created as empty text files), and
+any permission bits that we won't allow to be set on the real file (e.g.
+the real file gets u-s,g-s,o-t for safety) or that would limit the owner's
+access (since the real super-user can always access/change a file or
+directory, the files we create can always be accessed/changed by the
+creating user).
+
+The bf(--fake-super) option only affects the side where the option is used.
+To affect the remote side of a remote-shell connection, specify an rsync
+path:
+
+quote(tt(  rsync -av --rsync-path="rsync --fake-super" /src/ host:/dest/))
+
+Since there is only one "side" in a local copy, this option affects both
+the sending and recieving of files.  You'll need to specify a copy using
+"localhost" if you need to avoid this.  Note, however, that it is always
+safe to copy from some non-fake-super files into some fake-super files
+using a local bf(--fake-super) command because the non-fake source files
+will just have their normal attributes.
+
+This option is overridden by both bf(--super) and bf(--no-super).
+
+See also the "fake super" setting in the daemon's rsyncd.conf file.
+
 dit(bf(-S, --sparse)) Try to handle sparse files efficiently so they take
 up less space on the destination.  Conflicts with bf(--inplace) because it's
 not possible to overwrite data in a sparse fashion.
@@ -923,7 +998,7 @@ combined with the bf(--ignore-existing) option, no files will be updated
 
 dit(bf(--ignore-existing)) This tells rsync to skip updating files that
 already exist on the destination (this does em(not) ignore existing
-directores, or nothing would get done).  See also bf(--existing).
+directories, or nothing would get done).  See also bf(--existing).
 
 dit(bf(--remove-source-files)) This tells rsync to remove from the sending
 side the files (meaning non-directories) that are a part of the transfer
@@ -941,8 +1016,8 @@ option or mark the rules as only matching on the sending side (see the
 include/exclude modifiers in the FILTER RULES section).
 
 Prior to rsync 2.6.7, this option would have no effect unless bf(--recursive)
-was in effect.  Beginning with 2.6.7, deletions will also occur when bf(--dirs)
-(bf(-d)) is in effect, but only for directories whose contents are being copied.
+was enabled.  Beginning with 2.6.7, deletions will also occur when bf(--dirs)
+(bf(-d)) is enabled, but only for directories whose contents are being copied.
 
 This option can be dangerous if used incorrectly!  It is a very good idea
 to run first using the bf(--dry-run) option (bf(-n)) to see what files would be
@@ -956,20 +1031,22 @@ destination.  You can override this with the bf(--ignore-errors) option.
 
 The bf(--delete) option may be combined with one of the --delete-WHEN options
 without conflict, as well as bf(--delete-excluded).  However, if none of the
---delete-WHEN options are specified, rsync will currently choose the
-bf(--delete-before) algorithm.  A future version may change this to choose the
-bf(--delete-during) algorithm.  See also bf(--delete-after).
+--delete-WHEN options are specified, rsync will choose the
+bf(--delete-during) algorithm when talking to an rsync 3.0.0 or newer, and
+the bf(--delete-before) algorithm when talking to an older rsync.  See also
+bf(--delete-delay) and bf(--delete-after).
 
 dit(bf(--delete-before)) Request that the file-deletions on the receiving
-side be done before the transfer starts.  This is the default if bf(--delete)
-or bf(--delete-excluded) is specified without one of the --delete-WHEN options.
+side be done before the transfer starts.
 See bf(--delete) (which is implied) for more details on file-deletion.
 
 Deleting before the transfer is helpful if the filesystem is tight for space
 and removing extraneous files would help to make the transfer possible.
 However, it does introduce a delay before the start of the transfer,
 and this delay might cause the transfer to timeout (if bf(--timeout) was
-specified).
+specified).  It also forces rsync to use the old, non-incremental recursion
+algorithm that requires rsync to scan all the files in the transfer into
+memory at once (see bf(--recursive)).
 
 dit(bf(--delete-during, --del)) Request that the file-deletions on the
 receiving side be done incrementally as the transfer happens.  This is
@@ -977,11 +1054,22 @@ a faster method than choosing the before- or after-transfer algorithm,
 but it is only supported beginning with rsync version 2.6.4.
 See bf(--delete) (which is implied) for more details on file-deletion.
 
+dit(bf(--delete-delay)) Request that the file-deletions on the receiving
+side be computed during the transfer, and then removed after the transfer
+completes.  If the number of removed files overflows an internal buffer, a
+temporary file will be created on the receiving side to hold the names (it
+is removed while open, so you shouldn't see it during the transfer).  If
+the creation of the temporary file fails, rsync will try to fall back to
+using bf(--delete-after) (which it cannot do if bf(--recursive) is doing an
+incremental scan).
+
 dit(bf(--delete-after)) Request that the file-deletions on the receiving
 side be done after the transfer has completed.  This is useful if you
 are sending new per-directory merge files as a part of the transfer and
 you want their exclusions to take effect for the delete phase of the
-current transfer.
+current transfer.  It also forces rsync to use the old, non-incremental
+recursion algorithm that requires rsync to scan all the files in the
+transfer into memory at once (see bf(--recursive)).
 See bf(--delete) (which is implied) for more details on file-deletion.
 
 dit(bf(--delete-excluded)) In addition to deleting the files on the
@@ -1004,7 +1092,12 @@ using bf(--delete-after), and it used to be non-functional unless the
 bf(--recursive) option was also enabled.
 
 dit(bf(--max-delete=NUM)) This tells rsync not to delete more than NUM
-files or directories (NUM must be non-zero).
+files or directories.
+Beginning with version 3.0.0, you may specify bf(--max-delete=0) to
+be warned about any extraneous files in the destination, but be very
+careful to never specify a 0 value to an older rsync client, or the
+option will be silently ignored.  (A 3.0.0 client will die with an
+error if the remote rsync is not new enough to handle the situation.)
 This is useful when mirroring very large trees to prevent disasters.
 
 dit(bf(--max-size=SIZE)) This tells rsync to avoid transferring any
@@ -1077,20 +1170,21 @@ communicate.
 One tricky example is to set a different default directory on the remote
 machine for use with the bf(--relative) option.  For instance:
 
-quote(tt(    rsync -avR --rsync-path="cd /a/b && rsync" hst:c/d /e/))
+quote(tt(    rsync -avR --rsync-path="cd /a/b && rsync" host:c/d /e/))
 
 dit(bf(-C, --cvs-exclude)) This is a useful shorthand for excluding a
 broad range of files that you often don't want to transfer between
-systems. It uses the same algorithm that CVS uses to determine if
+systems. It uses a similar algorithm to CVS to determine if
 a file should be ignored.
 
-The exclude list is initialized to:
+The exclude list is initialized to exclude the following items (these
+initial items are marked as perishable -- see the FILTER RULES section):
 
 quote(quote(tt(RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state
 .nse_depinfo *~ #* .#* ,* _$* *$ *.old *.bak *.BAK *.orig *.rej
-.del-* *.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln core .svn/)))
+.del-* *.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln core .svn/ .bzr/)))
 
-then files listed in a $HOME/.cvsignore are added to the list and any
+then, files listed in a $HOME/.cvsignore are added to the list and any
 files listed in the CVSIGNORE environment variable (all cvsignore names
 are delimited by whitespace).
 
@@ -1309,6 +1403,12 @@ and the attributes updated.
 If a match is not found, a basis file from one of the em(DIR)s will be
 selected to try to speed up the transfer.
 
+This option works best when copying into an empty destination hierarchy, as
+rsync treats existing files as definitive (so it never looks in the link-dest
+dirs when a destination file already exists), and as malleable (so it might
+change the attributes of a destination file, which affects all the hard-linked
+versions).
+
 Note that if you combine this option with bf(--ignore-times), rsync will not
 link any files together because it only links identical files together as a
 substitute for transferring the file, never as an additional check after the
@@ -1389,8 +1489,8 @@ if the receiving rsync is at least version 2.6.7 (you can use bf(-vv)
 with older versions of rsync, but that also turns on the output of other
 verbose messages).
 
-The "%i" escape has a cryptic output that is 9 letters long.  The general
-format is like the string bf(YXcstpogz), where bf(Y) is replaced by the
+The "%i" escape has a cryptic output that is 11 letters long.  The general
+format is like the string bf(YXcstpoguax), where bf(Y) is replaced by the
 type of update being done, bf(X) is replaced by the file-type, and the
 other letters represent attributes that may be output if they are being
 modified.
@@ -1439,7 +1539,11 @@ quote(itemization(
   sender's value (requires bf(--owner) and super-user privileges).
   it() A bf(g) means the group is different and is being updated to the
   sender's value (requires bf(--group) and the authority to set the group).
-  it() The bf(z) slot is reserved for future use.
+  it() The bf(u) slot is reserved for reporting update (access) time changes
+  (a feature that is not yet released).
+  it() The bf(a) means that the ACL information changed.
+  it() The bf(x) slot is reserved for reporting extended attribute changes
+  (a feature that is not yet released).
 ))
 
 One other output is possible:  when deleting files, the "%i" will output
@@ -1576,7 +1680,7 @@ rule at the end of all your existing excludes.  This will prevent the
 sending of any partial-dir files that may exist on the sending side, and
 will also prevent the untimely deletion of partial-dir items on the
 receiving side.  An example: the above bf(--partial-dir) option would add
-the equivalent of "bf(--exclude=.rsync-partial/)" at the end of any other
+the equivalent of "bf(-f '-p .rsync-partial/')" at the end of any other
 filter rules.
 
 If you are supplying your own exclude rules, you may need to add your own
@@ -1618,7 +1722,7 @@ each file's destination directory, but if you've specified the
 bf(--partial-dir) option, that directory will be used instead.  See the
 comments in the bf(--partial-dir) section for a discussion of how this
 ".~tmp~" dir will be excluded from the transfer, and what you can do if
-you wnat rsync to cleanup old ".~tmp~" dirs that might be lying around.
+you want rsync to cleanup old ".~tmp~" dirs that might be lying around.
 Conflicts with bf(--inplace) and bf(--append).
 
 This option uses more memory on the receiving side (one bit per file
@@ -1663,7 +1767,7 @@ that any superfluous files and directories in the destination are removed
 quote(     rsync -avm --del --include='*.pdf' -f 'hide,! */' src/ dest)
 
 If you didn't want to remove superfluous destination files, the more
-time-honored options of "--include='*/' --exclude='*'" would work fine
+time-honored options of "bf(--include='*/' --exclude='*')" would work fine
 in place of the hide-filter (if that is more natural to you).
 
 dit(bf(--progress)) This option tells rsync to print information
@@ -1704,12 +1808,14 @@ dit(bf(-P)) The bf(-P) option is equivalent to bf(--partial) bf(--progress).  It
 purpose is to make it much easier to specify these two options for a long
 transfer that may be interrupted.
 
-dit(bf(--password-file)) This option allows you to provide a password
-in a file for accessing a remote rsync daemon. Note that this option
-is only useful when accessing an rsync daemon using the built in
-transport, not when using a remote shell as the transport. The file
-must not be world readable. It should contain just the password as a
-single line.
+dit(bf(--password-file)) This option allows you to provide a password in a
+file for accessing an rsync daemon.  The file must not be world readable.
+It should contain just the password as a single line.
+
+When accessing an rsync daemon using a remote shell as the transport, this
+option only comes into effect after the remote shell finishes its
+authentication (i.e. if you have also specified a password in the daemon's
+config file).
 
 dit(bf(--list-only)) This option will cause the source files to be listed
 instead of transferred.  This option is inferred if there is a single source
@@ -1767,6 +1873,24 @@ bf(--read-batch) option, you should use "--protocol=28" when creating the
 batch file to force the older protocol version to be used in the batch
 file (assuming you can't upgrade the rsync on the reading system).
 
+dit(bf(--iconv=CONVERT_SPEC)) Rsync can convert filenames between character
+sets using this option.  Using a CONVERT_SPEC of "." tells rsync to look up
+the default character-set via the locale setting.  Alternately, you can
+fully specify what conversion to do by giving a local and a remote charset
+separated by a comma (local first), e.g. bf(--iconv=utf8,iso88591).
+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.
+
+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.)
+
 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
 control over, such as the outgoing socket when directly contacting an
@@ -1962,8 +2086,8 @@ itemization(
   down.)
   it() a trailing "dir_name/***" will match both the directory (as if
   "dir_name/" had been specified) and all the files in the directory
-  (as if "dir_name/**" had been specified).  (This behavior is new for
-  version 2.6.7.)
+  (as if "dir_name/**" had been specified).  This behavior was added in
+  version 2.6.7.
 )
 
 Note that, when using the bf(--recursive) (bf(-r)) option (which is implied by
@@ -2078,13 +2202,13 @@ itemization(
 The following modifiers are accepted after a "+" or "-":
 
 itemization(
-  it() A "/" specifies that the include/exclude rule should be matched
+  it() A bf(/) specifies that the include/exclude rule should be matched
   against the absolute pathname of the current item.  For example,
   "-/ /etc/passwd" would exclude the passwd file any time the transfer
   was sending files from the "/etc" directory, and "-/ subdir/foo"
   would always exclude "foo" when it is in a dir named "subdir", even
   if "foo" is at the root of the current transfer.
-  it() A "!" specifies that the include/exclude should take effect if
+  it() A bf(!) specifies that the include/exclude should take effect if
   the pattern fails to match.  For instance, "-! */" would exclude all
   non-directories.
   it() A bf(C) is used to indicate that all the global CVS-exclude rules
@@ -2101,6 +2225,11 @@ itemization(
   being deleted.  See the bf(s) modifier for more info.  See also the
   protect (P) and risk (R) rules, which are an alternate way to
   specify receiver-side includes/excludes.
+  it() A bf(p) indicates that a rule is perishable, meaning that it is
+  ignored in directories that are being deleted.  For instance, the bf(-C)
+  option's default rules that exclude things like "CVS" and "*.o" are
+  marked as perishable, and will not prevent a directory that was removed
+  on the source from being deleted on the destination.
 )
 
 Per-directory rules are inherited in all subdirectories of the directory
@@ -2188,7 +2317,7 @@ that follow the :C instead of being subservient to all your rules.  To
 affect the other CVS exclude rules (i.e. the default list of exclusions,
 the contents of $HOME/.cvsignore, and the value of $CVSIGNORE) you should
 omit the bf(-C) command-line option and instead insert a "-C" rule into
-your filter rules; e.g. "--filter=-C".
+your filter rules; e.g. "bf(--filter=-C)".
 
 manpagesection(LIST-CLEARING FILTER RULE)
 
@@ -2434,7 +2563,7 @@ unsafe links to be omitted altogether.  (Note that you must specify
 bf(--links) for bf(--safe-links) to have any effect.)
 
 Symbolic links are considered unsafe if they are absolute symlinks
-(start with bf(/)), empty, or if they contain enough bf("..")
+(start with bf(/)), empty, or if they contain enough ".."
 components to ascend from the directory being copied.
 
 Here's a summary of how the symlink options are interpreted.  The list is
@@ -2513,6 +2642,8 @@ startdit()
 dit(bf(CVSIGNORE)) The CVSIGNORE environment variable supplements any
 ignore patterns in .cvsignore files. See the bf(--cvs-exclude) option for
 more details.
+dit(bf(RSYNC_ICONV)) Specify a default bf(--iconv) setting using this
+environment variable.
 dit(bf(RSYNC_RSH)) The RSYNC_RSH environment variable allows you to
 override the default shell used as the transport for rsync.  Command line
 options are permitted after the command name, just as in the bf(-e) option.
@@ -2556,7 +2687,7 @@ url(http://rsync.samba.org/)(http://rsync.samba.org/)
 
 manpagesection(VERSION)
 
-This man page is current for version 2.6.9pre3 of rsync.
+This man page is current for version 2.6.9 of rsync.
 
 manpagesection(INTERNAL OPTIONS)