Updated exit codes as Jon Jensen and J.W. suggested.

[rsync/rsync.git] / rsync.yo

diff --git a/rsync.yo b/rsync.yo
index 9b74edb..f116976 100644 (file)
--- a/rsync.yo
+++ b/rsync.yo
@@ -115,7 +115,7 @@ Perhaps the best way to explain the syntax is some examples:
 
 quote(rsync *.c foo:src/)
 
 
 quote(rsync *.c foo:src/)
 

-this would transfer all files matching the pattern *.c from the
+This would transfer all files matching the pattern *.c from the

 current directory to the directory src on the machine foo. If any of
 the files already exist on the remote system then the rsync
 remote-update protocol is used to update the file by sending only the
 current directory to the directory src on the machine foo. If any of
 the files already exist on the remote system then the rsync
 remote-update protocol is used to update the file by sending only the


@@ -123,7 +123,7 @@ differences. See the tech report for details.
 
 quote(rsync -avz foo:src/bar /data/tmp)
 
 
 quote(rsync -avz foo:src/bar /data/tmp)
 

-this would recursively transfer all files from the directory src/bar on the
+This would recursively transfer all files from the directory src/bar on the

 machine foo into the /data/tmp/bar directory on the local machine. The
 files are transferred in "archive" mode, which ensures that symbolic
 links, devices, attributes, permissions, ownerships etc are preserved
 machine foo into the /data/tmp/bar directory on the local machine. The
 files are transferred in "archive" mode, which ensures that symbolic
 links, devices, attributes, permissions, ownerships etc are preserved


@@ -132,12 +132,17 @@ size of data portions of the transfer.
 
 quote(rsync -avz foo:src/bar/ /data/tmp)
 
 
 quote(rsync -avz foo:src/bar/ /data/tmp)
 

-a trailing slash on the source changes this behavior to transfer
-all files from the directory src/bar on the machine foo into the
-/data/tmp/.  A trailing / on a source name means "copy the
-contents of this directory".  Without a trailing slash it means "copy
-the directory". This difference becomes particularly important when
-using the --delete option.
+A trailing slash on the source changes this behavior to avoid creating an
+additional directory level at the destination.  You can think of a trailing
+/ on a source as meaning "copy the contents of this directory" as opposed
+to "copy the directory by name", but in both cases the attributes of the
+containing directory are transferred to the containing directory on the
+destination.  In other words, each of the following commands copies the
+files in the same way, including their setting of the attributes of
+/dest/foo:
+
+quote(rsync -avz /src/foo /dest)
+quote(rsync -avz /src/foo/ /dest/foo)

 
 You can also use rsync in local-only mode, where both the source and
 destination don't have a ':' in the name. In this case it behaves like
 
 You can also use rsync in local-only mode, where both the source and
 destination don't have a ':' in the name. In this case it behaves like


@@ -145,7 +150,7 @@ an improved copy command.
 
 quote(rsync somehost.mydomain.com::)
 
 
 quote(rsync somehost.mydomain.com::)
 

-this would list all the anonymous rsync modules available on the host
+This would list all the anonymous rsync modules available on the host

 somehost.mydomain.com.  (See the following section for more details.)
 
 
 somehost.mydomain.com.  (See the following section for more details.)
 
 


@@ -290,9 +295,9 @@ verb(
  -R, --relative              use relative path names
      --no-relative           turn off --relative
      --no-implied-dirs       don't send implied dirs with -R
  -R, --relative              use relative path names
      --no-relative           turn off --relative
      --no-implied-dirs       don't send implied dirs with -R

- -b, --backup                make backups (default ~ suffix)
+ -b, --backup                make backups (see --suffix)

      --backup-dir            make backups into this directory
      --backup-dir            make backups into this directory

-     --suffix=SUFFIX         define backup suffix
+     --suffix=SUFFIX         define backup suffix (default ~ w/o --backup-dir)

  -u, --update                update only (don't overwrite newer files)
  -l, --links                 copy symlinks as symlinks
  -L, --copy-links            copy the referent of symlinks
  -u, --update                update only (don't overwrite newer files)
  -l, --links                 copy symlinks as symlinks
  -L, --copy-links            copy the referent of symlinks


@@ -452,9 +457,10 @@ the --no-implied-dirs option would omit both of these implied dirs,
 which means that if "/path" was a real directory on one machine and a
 symlink of the other machine, rsync would not try to change this.
 
 which means that if "/path" was a real directory on one machine and a
 symlink of the other machine, rsync would not try to change this.
 

-dit(bf(-b, --backup)) With this option preexisting destination files are
-renamed with a ~ extension as each file is transferred.  You can
-control the backup suffix using the --suffix option.
+dit(bf(-b, --backup)) With this option, preexisting destination files are
+renamed as each file is transferred or deleted.  You can control where the
+backup file goes and what (if any) suffix gets appended using the
+--backup-dir and --suffix options.

 
 dit(bf(--backup-dir=DIR)) In combination with the --backup option, this
 tells rsync to store all backups in the specified directory. This is
 
 dit(bf(--backup-dir=DIR)) In combination with the --backup option, this
 tells rsync to store all backups in the specified directory. This is


@@ -464,9 +470,8 @@ specify a backup suffix using the --suffix option
 will keep their original filenames).
 
 dit(bf(--suffix=SUFFIX)) This option allows you to override the default
 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.
+backup suffix used with the --backup (-b) option. The default suffix is a ~
+if no --backup-dir was specified, otherwise it is an empty string.

 
 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
 
 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


@@ -832,9 +837,7 @@ make a subsequent transfer of the rest of the file much faster.
 dit(bf(--progress)) This option tells rsync to print information
 showing the progress of the transfer. This gives a bored user
 something to watch.
 dit(bf(--progress)) This option tells rsync to print information
 showing the progress of the transfer. This gives a bored user
 something to watch.

-
-This option is normally combined with -v. Using this option without
-the -v option will produce weird results on your display.
+Implies --verbose without incrementing verbosity.

 
 dit(bf(-P)) The -P option is equivalent to --partial --progress. I
 found myself typing that combination quite often so I created an
 
 dit(bf(-P)) The -P option is equivalent to --partial --progress. I
 found myself typing that combination quite often so I created an


@@ -916,15 +919,15 @@ itemize(
   *?[ then expression matching is applied using the shell filename
   matching rules. Otherwise a simple string match is used.
 
   *?[ then expression matching is applied using the shell filename
   matching rules. Otherwise a simple string match is used.
 

-  it() if the pattern includes a double asterisk "**" then all wildcards in
-  the pattern will match slashes, otherwise they will stop at slashes.
+  it() the double asterisk pattern "**" will match slashes while a
+  single asterisk pattern "*" will stop at slashes.

 
   it() if the pattern contains a / (not counting a trailing /) or a "**"
   then it is matched against the full filename, including any leading
   directory. If the pattern doesn't contain a / or a "**", then it is
   matched only against the final component of the filename.  Again,
   remember that the algorithm is applied recursively so "full filename" can
 
   it() if the pattern contains a / (not counting a trailing /) or a "**"
   then it is matched against the full filename, including any leading
   directory. If the pattern doesn't contain a / or a "**", then it is
   matched only against the final component of the filename.  Again,
   remember that the algorithm is applied recursively so "full filename" can

-  actually be any portion of a path.
+  actually be any portion of a path below the starting directory.

 
   it() if the pattern starts with "+ " (a plus followed by a space)
   then it is always considered an include pattern, even if specified as
 
   it() if the pattern starts with "+ " (a plus followed by a space)
   then it is always considered an include pattern, even if specified as


@@ -1012,9 +1015,9 @@ once, instead of sending the same data to every host individually.
 Example:
 
 verb(
 Example:
 
 verb(

-$ rsync --write_batch=pfx -a /source/dir/ /adest/dir/
+$ rsync --write-batch=pfx -a /source/dir/ /adest/dir/

 $ rcp pfx.rsync_* remote:
 $ rcp pfx.rsync_* remote:

-$ rsh remote rsync --read_batch=pfx -a /bdest/dir/
+$ rsh remote rsync --read-batch=pfx -a /bdest/dir/

 # or alternatively
 $ rsh remote ./pfx.rsync_argvs /bdest/dir/
 )
 # or alternatively
 $ rsh remote ./pfx.rsync_argvs /bdest/dir/
 )


@@ -1106,24 +1109,26 @@ show why each individual file is included or excluded.
 manpagesection(EXIT VALUES)
 
 startdit()
 manpagesection(EXIT VALUES)
 
 startdit()

-dit(bf(RERR_SYNTAX     1))       Syntax or usage error 
-dit(bf(RERR_PROTOCOL   2))       Protocol incompatibility 
-dit(bf(RERR_FILESELECT 3))       Errors selecting input/output files, dirs
+dit(bf(1))  Syntax or usage error 
+dit(bf(2))  Protocol incompatibility 
+dit(bf(3))  Errors selecting input/output files, dirs

 
 

-dit(bf(RERR_UNSUPPORTED 4)) Requested action not supported: an attempt
+dit(bf(4))  Requested action not supported: an attempt

 was made to manipulate 64-bit files on a platform that cannot support
 them; or an option was speciifed that is supported by the client and
 not by the server.
 
 was made to manipulate 64-bit files on a platform that cannot support
 them; or an option was speciifed that is supported by the client and
 not by the server.
 

-dit(bf(RERR_SOCKETIO   10))      Error in socket IO 
-dit(bf(RERR_FILEIO     11))      Error in file IO 
-dit(bf(RERR_STREAMIO   12))      Error in rsync protocol data stream 
-dit(bf(RERR_MESSAGEIO  13))      Errors with program diagnostics 
-dit(bf(RERR_IPC        14))      Error in IPC code 
-dit(bf(RERR_SIGNAL     20))      Received SIGUSR1 or SIGINT 
-dit(bf(RERR_WAITCHILD  21))      Some error returned by waitpid() 
-dit(bf(RERR_MALLOC     22))      Error allocating core memory buffers 
-dit(bf(RERR_TIMEOUT    30))      Timeout in data send/receive 
+dit(bf(5))   Error starting client-server protocol
+dit(bf(10))  Error in socket IO 
+dit(bf(11))  Error in file IO 
+dit(bf(12))  Error in rsync protocol data stream 
+dit(bf(13))  Errors with program diagnostics 
+dit(bf(14))  Error in IPC code 
+dit(bf(20))  Received SIGUSR1 or SIGINT 
+dit(bf(21))  Some error returned by waitpid() 
+dit(bf(22))  Error allocating core memory buffers 
+dit(bf(23))  Partial transfer
+dit(bf(30))  Timeout in data send/receive 

 enddit()
 
 manpagesection(ENVIRONMENT VARIABLES)
 enddit()
 
 manpagesection(ENVIRONMENT VARIABLES)