Mention that the -e COMMAND can contain options.

[rsync/rsync.git] / rsync.yo

diff --git a/rsync.yo b/rsync.yo
index 017fb26..1aed899 100644 (file)
--- a/rsync.yo
+++ b/rsync.yo
@@ -77,11 +77,13 @@ manpagesection(SETUP)
 
 See the file README for installation instructions.
 
-Once installed you can use rsync to any machine that you can use rsh
-to.  rsync uses rsh for its communications, unless both the source and
-destination are local.
+Once installed, you can use rsync to any machine that you can access via
+a remote shell (as well as some that you can access using the rsync
+daemon-mode protocol).  For remote transfers, rsync typically uses rsh
+for its communications, but it may have been configured to use a
+different remote shell by default, such as ssh.
 
-You can also specify an alternative to rsh, either by using the -e
+You can also specify any remote shell you like, either by using the -e
 command line option, or by setting the RSYNC_RSH environment variable.
 
 One common substitute is to use ssh, which offers a high degree of
@@ -135,7 +137,7 @@ somehost.mydomain.com.  (See the following section for more details.)
 
 manpagesection(CONNECTING TO AN RSYNC SERVER)
 
-It is also possible to use rsync without using rsh or ssh as the
+It is also possible to use rsync without a remote shell as the
 transport. In this case you will connect to a remote rsync server
 running on TCP port 873. 
 
@@ -144,7 +146,7 @@ environment variable RSYNC_PROXY to a hostname:port pair pointing to
 your web proxy.  Note that your web proxy's configuration must allow
 proxying to port 873.
 
-Using rsync in this way is the same as using it with rsh or ssh except
+Using rsync in this way is the same as using it with a remote shell except
 that:
 
 itemize(
@@ -224,7 +226,7 @@ verb(
  -R, --relative              use relative path names
  -b, --backup                make backups (default ~ suffix)
      --backup-dir            make backups into this directory
-     --suffix=SUFFIX         override backup suffix
+     --suffix=SUFFIX         define backup suffix
  -u, --update                update only (don't overwrite newer files)
  -l, --links                 copy symlinks as symlinks
  -L, --copy-links            copy the referent of symlinks
@@ -242,7 +244,7 @@ verb(
      --no-whole-file         turn off --whole-file
  -x, --one-file-system       don't cross filesystem boundaries
  -B, --block-size=SIZE       checksum blocking size (default 700)
- -e, --rsh=COMMAND           specify rsh replacement
+ -e, --rsh=COMMAND           specify the remote shell to use
      --rsync-path=PATH       specify path to rsync on the remote machine
  -C, --cvs-exclude           auto ignore files in the same way CVS does
      --existing              only update files that already exist
@@ -372,10 +374,15 @@ control the backup suffix using the --suffix option.
 
 dit(bf(--backup-dir=DIR)) In combination with the --backup option, this
 tells rsync to store all backups in the specified directory. This is
-very useful for incremental backups.
+very useful for incremental backups.  You can additionally
+specify a backup suffix using the --suffix option
+(otherwise the files backed up in the specified directory
+will keep their original filenames).
 
 dit(bf(--suffix=SUFFIX)) This option allows you to override the default
 backup suffix used with the -b option. The default is a ~.
+If --backup-dir and --suffix are both specified,
+the SUFFIX is appended to the filename even in the backup directory.
 
 dit(bf(-u, --update)) This forces rsync to skip any files for which the
 destination file already exists and has a date later than the source
@@ -505,8 +512,15 @@ the rsync algorithm. See the technical report for details.
 
 dit(bf(-e, --rsh=COMMAND)) This option allows you to choose an alternative
 remote shell program to use for communication between the local and
-remote copies of rsync. By default, rsync will use rsh, but you may
-like to instead use ssh because of its high security.
+remote copies of rsync. Typically, rsync is configured to use rsh by
+default, but you may prefer to use ssh because of its high security.
+
+Feel free to include options in the COMMAND.  For instance:
+
+quote(-e "ssh -1 -l joe")
+
+(Note that ssh users can alternately customize site-specific connect
+options in their .ssh/config file.)
 
 You can also choose the remote shell program using the RSYNC_RSH
 environment variable.
@@ -661,7 +675,8 @@ dit(bf(--blocking-io)) This tells rsync to use blocking IO when launching
 a remote shell transport.  If -e or --rsh are not specified or are set to
 the default "rsh", this defaults to blocking IO, otherwise it defaults to
 non-blocking IO.  You may find the --blocking-io option is needed for some
-remote shells that can't handle non-blocking IO.  Ssh prefers blocking IO.
+remote shells that can't handle non-blocking IO.  (Note that ssh prefers
+non-blocking IO.)
 
 dit(bf(--no-blocking-io)) Turn off --blocking-io, for use when it is the
 default.