Documented the change in the --human-readable option.

[rsync/rsync.git] / rsync.yo

diff --git a/rsync.yo b/rsync.yo
index ac83d3a..4e61ea6 100644 (file)
--- a/rsync.yo
+++ b/rsync.yo
@@ -378,8 +378,8 @@ to the detailed description below for a complete description.  verb(
      --sockopts=OPTIONS      specify custom TCP options
      --blocking-io           use blocking I/O for the remote shell
      --stats                 give some file-transfer stats
+ -8, --8-bit-output          leave high-bit chars unescaped in output
  -h, --human-readable        output numbers in a human-readable format
-     --si                    like human-readable, but use powers of 1000
      --progress              show progress during transfer
  -P                          same as --partial --progress
  -i, --itemize-changes       output a change-summary for all updates
@@ -706,14 +706,18 @@ permissions (while leaving existing files unchanged), make sure that the
 bf(--perms) option is off and use bf(--chmod=ugo=rwX) (which ensures that
 all non-masked bits get enabled).  If you'd care to make this latter
 behavior easier to type, you could define a popt alias for it, such as
-putting this line in the file ~/.popt (this defines the bf(-s) option):
+putting this line in the file ~/.popt (this defines the bf(-s) option,
+and includes --no-g to use the default group of the destination dir):
 
-quote(tt(   rsync alias -s --no-p --chmod=ugo=rwX))
+quote(tt(   rsync alias -s --no-p --no-g --chmod=ugo=rwX))
 
 You could then use this new option in a command such as this one:
 
 quote(tt(   rsync -asv src/ dest/))
 
+(Caveat: make sure that bf(-a) does not follow bf(-s), or it will re-enable
+the "--no-*" options.)
+
 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
@@ -1390,12 +1394,22 @@ dit(bf(--stats)) This tells rsync to print a verbose set of statistics
 on the file transfer, allowing you to tell how effective the rsync
 algorithm is for your data.
 
-dit(bf(-h, --human-readable)) Output numbers in a more human-readable format.
-Large numbers may be output in larger units, with a K (1024), M (1024*1024),
-or G (1024*1024*1024) suffix.
+dit(bf(-8, --8-bit-output)) This tells rsync to leave all high-bit characters
+unescaped in the output instead of trying to test them to see if they're
+valid in the current locale and escaping the invalid ones.  All control
+characters (but never tabs) are always escaped, regardless of this option's
+setting.
 
-dit(bf(--si)) Similar to the bf(--human-readable) option, but using powers
-of 1000 instead of 1024.
+The escape idiom that started in 2.6.7 is to output a literal backslash (\)
+and a hash (#), followed by exactly 3 octal digits.  For example, a newline
+would output as "\#012".  A literal backslash that is in a filename is not
+escaped unless it is followed by a hash and 3 digits (0-9).
+
+dit(bf(-h, --human-readable)) Output numbers in a more human-readable format.
+This makes big numbers output using larger units, with a K, M, or G suffix.  If
+this option was specified once, these units are K (1000), M (1000*1000), and
+G (1000*1000*1000); if the option is repeated, the units are powers of 1024
+instead of 1000.
 
 dit(bf(--partial)) By default, rsync will delete any partially
 transferred file if the transfer is interrupted. In some circumstances