If ignore_perishable is set, increment a count of all excluded

[rsync/rsync.git] / rsync.yo

diff --git a/rsync.yo b/rsync.yo
index 2d0fb5d..2a266d7 100644 (file)
--- a/rsync.yo
+++ b/rsync.yo
@@ -1,5 +1,5 @@
 mailto(rsync-bugs@samba.org)
 mailto(rsync-bugs@samba.org)

-manpage(rsync)(1)(22 Apr 2006)()()
+manpage(rsync)(1)(6 Nov 2006)()()

 manpagename(rsync)(faster, flexible replacement for rcp)
 manpagesynopsis()
 
 manpagename(rsync)(faster, flexible replacement for rcp)
 manpagesynopsis()
 


@@ -33,7 +33,7 @@ report that accompanies this package.
 
 Some of the additional features of rsync are:
 
 
 Some of the additional features of rsync are:
 

-itemize(
+itemization(

   it() support for copying links, devices, owners, groups, and permissions
   it() exclude and exclude-from options similar to GNU tar
   it() a CVS exclude mode for ignoring the same files that CVS would ignore
   it() support for copying links, devices, owners, groups, and permissions
   it() exclude and exclude-from options similar to GNU tar
   it() a CVS exclude mode for ignoring the same files that CVS would ignore


@@ -182,7 +182,7 @@ CONNECTIONS section below for information on that.)
 Using rsync in this way is the same as using it with a remote shell except
 that:
 
 Using rsync in this way is the same as using it with a remote shell except
 that:
 

-itemize(
+itemization(

        it() you either use a double colon :: instead of a single colon to
        separate the hostname from the path, or you use an rsync:// URL.
        it() the first word of the "path" is actually a module name.
        it() you either use a double colon :: instead of a single colon to
        separate the hostname from the path, or you use an rsync:// URL.
        it() the first word of the "path" is actually a module name.


@@ -299,6 +299,7 @@ Here is a short summary of the options available in rsync. Please refer
 to the detailed description below for a complete description.  verb(
  -v, --verbose               increase verbosity
  -q, --quiet                 suppress non-error messages
 to the detailed description below for a complete description.  verb(
  -v, --verbose               increase verbosity
  -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)
      --no-OPTION             turn off an implied OPTION (e.g. --no-D)
  -c, --checksum              skip based on checksum, not mod-time & size
  -a, --archive               archive mode; same as -rlptgoD (no -H)
      --no-OPTION             turn off an implied OPTION (e.g. --no-D)


@@ -321,7 +322,7 @@ to the detailed description below for a complete description.  verb(
  -H, --hard-links            preserve hard links
  -p, --perms                 preserve permissions
  -E, --executability         preserve executability
  -H, --hard-links            preserve hard links
  -p, --perms                 preserve permissions
  -E, --executability         preserve executability

-     --chmod=CHMOD           change destination permissions
+     --chmod=CHMOD           affect file and/or directory permissions

  -o, --owner                 preserve owner (super-user only)
  -g, --group                 preserve group
      --devices               preserve device files (super-user only)
  -o, --owner                 preserve owner (super-user only)
  -g, --group                 preserve group
      --devices               preserve device files (super-user only)


@@ -339,7 +340,7 @@ to the detailed description below for a complete description.  verb(
      --rsync-path=PROGRAM    specify the rsync to run on remote machine
      --existing              skip creating new files on receiver
      --ignore-existing       skip updating files that exist on receiver
      --rsync-path=PROGRAM    specify the rsync to run on remote machine
      --existing              skip creating new files on receiver
      --ignore-existing       skip updating files that exist on receiver

-     --remove-sender-files   sender removes synchronized files (non-dir)
+     --remove-source-files   sender removes synchronized files (non-dir)

      --del                   an alias for --delete-during
      --delete                delete extraneous files from dest dirs
      --delete-before         receiver deletes before transfer (default)
      --del                   an alias for --delete-during
      --delete                delete extraneous files from dest dirs
      --delete-before         receiver deletes before transfer (default)


@@ -401,8 +402,7 @@ to the detailed description below for a complete description.  verb(
  -4, --ipv4                  prefer IPv4
  -6, --ipv6                  prefer IPv6
      --version               print version number
  -4, --ipv4                  prefer IPv4
  -6, --ipv6                  prefer IPv6
      --version               print version number

-(-h) --help                  show this help (see below for -h comment)
-)
+(-h) --help                  show this help (see below for -h comment))

 
 Rsync can also be run as a daemon, in which case the following options are
 accepted: verb(
 
 Rsync can also be run as a daemon, in which case the following options are
 accepted: verb(


@@ -418,8 +418,7 @@ accepted: verb(
  -v, --verbose               increase verbosity
  -4, --ipv4                  prefer IPv4
  -6, --ipv6                  prefer IPv6
  -v, --verbose               increase verbosity
  -4, --ipv4                  prefer IPv4
  -6, --ipv6                  prefer IPv6

- -h, --help                  show this help (if used after --daemon)
-)
+ -h, --help                  show this help (if used after --daemon))

 
 manpageoptions()
 
 
 manpageoptions()
 


@@ -459,9 +458,17 @@ are given during the transfer, notably suppressing information messages
 from the remote server. This flag is useful when invoking rsync from
 cron.
 
 from the remote server. This flag is useful when invoking rsync from
 cron.
 

+dit(bf(--no-motd)) This option affects the information that is output
+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.
+

 dit(bf(-I, --ignore-times)) Normally rsync will skip any files that are
 already the same size and have the same modification time-stamp.
 dit(bf(-I, --ignore-times)) Normally rsync will skip any files that are
 already the same size and have the same modification time-stamp.

-This option turns off this "quick check" behavior.
+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
 
 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


@@ -611,8 +618,8 @@ your rules specify a trailing inclusion/exclusion of '*', the auto-added
 rule would never be reached).
 
 dit(bf(--backup-dir=DIR)) In combination with the bf(--backup) option, this
 rule would never be reached).
 
 dit(bf(--backup-dir=DIR)) In combination with the bf(--backup) option, this

-tells rsync to store all backups in the specified directory. This is
-very useful for incremental backups.  You can additionally
+tells rsync to store all backups in the specified directory on the receiving
+side.  This can be used for incremental backups.  You can additionally

 specify a backup suffix using the bf(--suffix) option
 (otherwise the files backed up in the specified directory
 will keep their original filenames).
 specify a backup suffix using the bf(--suffix) option
 (otherwise the files backed up in the specified directory
 will keep their original filenames).


@@ -741,7 +748,7 @@ be the source permissions.)
 
 When this option is em(off), permissions are set as follows:
 
 
 When this option is em(off), permissions are set as follows:
 

-quote(itemize(
+quote(itemization(

   it() Existing files (including updated files) retain their existing
   permissions, though the bf(--executability) option might change just
   the execute permission for the file.
   it() Existing files (including updated files) retain their existing
   permissions, though the bf(--executability) option might change just
   the execute permission for the file.


@@ -788,7 +795,7 @@ not enabled.  A regular file is considered to be executable if at least one
 executability differs from that of the corresponding source file, rsync
 modifies the destination file's permissions as follows:
 
 executability differs from that of the corresponding source file, rsync
 modifies the destination file's permissions as follows:
 

-quote(itemize(
+quote(itemization(

   it() To make a file non-executable, rsync turns off all its 'x'
   permissions.
   it() To make a file executable, rsync turns on each 'x' permission that
   it() To make a file non-executable, rsync turns off all its 'x'
   permissions.
   it() To make a file executable, rsync turns on each 'x' permission that


@@ -918,7 +925,7 @@ 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).
 
 already exist on the destination (this does em(not) ignore existing
 directores, or nothing would get done).  See also bf(--existing).
 

-dit(bf(--remove-sender-files)) This tells rsync to remove from the sending
+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
 and have been successfully duplicated on the receiving side.
 
 side the files (meaning non-directories) that are a part of the transfer
 and have been successfully duplicated on the receiving side.
 


@@ -997,7 +1004,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
 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
 This is useful when mirroring very large trees to prevent disasters.
 
 dit(bf(--max-size=SIZE)) This tells rsync to avoid transferring any


@@ -1157,7 +1169,7 @@ exact list of files to transfer (as read from the specified FILE or bf(-)
 for standard input).  It also tweaks the default behavior of rsync to make
 transferring just the specified files and directories easier:
 
 for standard input).  It also tweaks the default behavior of rsync to make
 transferring just the specified files and directories easier:
 

-quote(itemize(
+quote(itemization(

   it() The bf(--relative) (bf(-R)) option is implied, which preserves the path
   information that is specified for each item in the file (use
   bf(--no-relative) or bf(--no-R) if you want to turn that off).
   it() The bf(--relative) (bf(-R)) option is implied, which preserves the path
   information that is specified for each item in the file (use
   bf(--no-relative) or bf(--no-R) if you want to turn that off).


@@ -1302,6 +1314,11 @@ 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.
 
 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.
 

+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
+file is updated.
+

 If em(DIR) is a relative path, it is relative to the destination directory.
 See also bf(--compare-dest) and bf(--copy-dest).
 
 If em(DIR) is a relative path, it is relative to the destination directory.
 See also bf(--compare-dest) and bf(--copy-dest).
 


@@ -1385,7 +1402,7 @@ modified.
 
 The update types that replace the bf(Y) are as follows:
 
 
 The update types that replace the bf(Y) are as follows:
 

-quote(itemize(
+quote(itemization(

   it() A bf(<) means that a file is being transferred to the remote host
   (sent).
   it() A bf(>) means that a file is being transferred to the local host
   it() A bf(<) means that a file is being transferred to the remote host
   (sent).
   it() A bf(>) means that a file is being transferred to the local host


@@ -1411,7 +1428,7 @@ a "?" (this can happen when talking to an older rsync).
 
 The attribute that is associated with each letter is as follows:
 
 
 The attribute that is associated with each letter is as follows:
 

-quote(itemize(
+quote(itemization(

   it() A bf(c) means the checksum of the file is different and will be
   updated by the file transfer (requires bf(--checksum)).
   it() A bf(s) means the size of the file is different and will be updated
   it() A bf(c) means the checksum of the file is different and will be
   updated by the file transfer (requires bf(--checksum)).
   it() A bf(s) means the size of the file is different and will be updated


@@ -1486,7 +1503,7 @@ 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.
 
 on the file transfer, allowing you to tell how effective the rsync
 algorithm is for your data.
 

-The current statistics are as follows: quote(itemize(
+The current statistics are as follows: quote(itemization(

   it() bf(Number of files) is the count of all "files" (in the generic
   sense), which includes directories, symlinks, etc.
   it() bf(Number of files transferred) is the count of normal files that
   it() bf(Number of files) is the count of all "files" (in the generic
   sense), which includes directories, symlinks, etc.
   it() bf(Number of files transferred) is the count of normal files that


@@ -1659,24 +1676,34 @@ showing the progress of the transfer. This gives a bored user
 something to watch.
 Implies bf(--verbose) if it wasn't already specified.
 
 something to watch.
 Implies bf(--verbose) if it wasn't already specified.
 

-When the file is transferring, the data looks like this:
+While rsync is transferring a regular file, it updates a progress line that
+looks like this:

 
 verb(      782448  63%  110.64kB/s    0:00:04)
 
 
 verb(      782448  63%  110.64kB/s    0:00:04)
 

-This tells you the current file size, the percentage of the transfer that
-is complete, the current calculated file-completion rate (including both
-data over the wire and data being matched locally), and the estimated time
-remaining in this transfer.
+In this example, the receiver has reconstructed 782448 bytes or 63% of the
+sender's file, which is being reconstructed at a rate of 110.64 kilobytes
+per second, and the transfer will finish in 4 seconds if the current rate
+is maintained until the end.

 
 

-After a file is complete, the data looks like this:
+These statistics can be misleading if the incremental transfer algorithm is
+in use.  For example, if the sender's file consists of the basis file
+followed by additional data, the reported rate will probably drop
+dramatically when the receiver gets to the literal data, and the transfer
+will probably take much longer to finish than the receiver estimated as it
+was finishing the matched part of the file.

 
 

-verb(     1238099 100%  146.38kB/s    0:00:08  (5, 57.1% of 396))
+When the file transfer finishes, rsync replaces the progress line with a
+summary line that looks like this:

 
 

-This tells you the final file size, that it's 100% complete, the final
-transfer rate for the file, the amount of elapsed time it took to transfer
-the file, and the addition of a total-transfer summary in parentheses.
-These additional numbers tell you how many files have been updated, and
-what percent of the total number of files has been scanned.
+verb(     1238099 100%  146.38kB/s    0:00:08  (xfer#5, to-check=169/396))
+
+In this example, the file was 1238099 bytes long in total, the average rate
+of transfer for the whole file was 146.38 kilobytes per second over the 8
+seconds that it took to complete, it was the 5th transfer of a regular file
+during the current rsync session, and there are 169 more files for the
+receiver to check (to see if they are up-to-date or not) remaining out of
+the 396 total files in the file-list.

 
 dit(bf(-P)) The bf(-P) option is equivalent to bf(--partial) bf(--progress).  Its
 purpose is to make it much easier to specify these two options for a long
 
 dit(bf(-P)) The bf(-P) option is equivalent to bf(--partial) bf(--progress).  Its
 purpose is to make it much easier to specify these two options for a long


@@ -1903,7 +1930,7 @@ The include/exclude rules each specify a pattern that is matched against
 the names of the files that are going to be transferred.  These patterns
 can take several forms:
 
 the names of the files that are going to be transferred.  These patterns
 can take several forms:
 

-itemize(
+itemization(

   it() if the pattern starts with a / then it is anchored to a
   particular spot in the hierarchy of files, otherwise it is matched
   against the end of the pathname.  This is similar to a leading ^ in
   it() if the pattern starts with a / then it is anchored to a
   particular spot in the hierarchy of files, otherwise it is matched
   against the end of the pathname.  This is similar to a leading ^ in


@@ -1981,7 +2008,7 @@ tt(- *)nl()
 
 Here are some examples of exclude/include matching:
 
 
 Here are some examples of exclude/include matching:
 

-itemize(
+itemization(

   it() "- *.o" would exclude all filenames matching *.o
   it() "- /foo" would exclude a file (or directory) named foo in the
   transfer-root directory
   it() "- *.o" would exclude all filenames matching *.o
   it() "- /foo" would exclude a file (or directory) named foo in the
   transfer-root directory


@@ -2028,7 +2055,7 @@ tt(:n- .non-inherited-per-dir-excludes)nl()
 
 The following modifiers are accepted after a merge or dir-merge rule:
 
 
 The following modifiers are accepted after a merge or dir-merge rule:
 

-itemize(
+itemization(

   it() A bf(-) specifies that the file should consist of only exclude
   patterns, with no other rule-parsing except for in-file comments.
   it() A bf(+) specifies that the file should consist of only include
   it() A bf(-) specifies that the file should consist of only exclude
   patterns, with no other rule-parsing except for in-file comments.
   it() A bf(+) specifies that the file should consist of only include


@@ -2055,7 +2082,7 @@ itemize(
 
 The following modifiers are accepted after a "+" or "-":
 
 
 The following modifiers are accepted after a "+" or "-":
 

-itemize(
+itemization(

   it() A "/" 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
   it() A "/" 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


@@ -2330,7 +2357,7 @@ and the information to repeat this operation is stored in "foo" and
 into the directory /bdest/dir.  The differences between the two examples
 reveals some of the flexibility you have in how you deal with batches:
 
 into the directory /bdest/dir.  The differences between the two examples
 reveals some of the flexibility you have in how you deal with batches:
 

-itemize(
+itemization(

   it() The first example shows that the initial copy doesn't have to be
   local -- you can push or pull data to/from a remote host using either the
   remote-shell syntax or rsync daemon syntax, as desired.
   it() The first example shows that the initial copy doesn't have to be
   local -- you can push or pull data to/from a remote host using either the
   remote-shell syntax or rsync daemon syntax, as desired.


@@ -2534,7 +2561,17 @@ url(http://rsync.samba.org/)(http://rsync.samba.org/)
 
 manpagesection(VERSION)
 
 
 manpagesection(VERSION)
 

-This man page is current for version 2.6.8 of rsync.
+This man page is current for version 2.6.9 of rsync.
+
+manpagesection(INTERNAL OPTIONS)
+
+The options bf(--server) and bf(--sender) are used internally by rsync,
+and should never be typed by a user under normal circumstances.  Some
+awareness of these options may be needed in certain scenarios, such as
+when setting up a login that can only run an rsync command.  For instance,
+the support directory of the rsync distribution has an example script
+named rrsync (for restricted rsync) that can be used with a restricted
+ssh login.

 
 manpagesection(CREDITS)
 
 
 manpagesection(CREDITS)