X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/7b13ff9704641f33dbc700c7aba30c3d92ca59ff..c897f7119adf97e8d4759462a6dd25a4d4fe636a:/rsync.yo

diff --git a/rsync.yo b/rsync.yo
index 8ec4fa8f..06cdc61a 100644
--- a/rsync.yo
+++ b/rsync.yo
@@ -1,5 +1,5 @@
 mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(8 Feb 2006)()()
+manpage(rsync)(1)(19 Feb 2006)()()
 manpagename(rsync)(faster, flexible replacement for rcp)
 manpagesynopsis()
 
@@ -11,6 +11,8 @@ rsync [OPTION]... SRC [SRC]... [USER@]HOST::DEST
 
 rsync [OPTION]... SRC [SRC]... rsync://[USER@]HOST[:PORT]/DEST
 
+rsync [OPTION]... SRC
+
 rsync [OPTION]... [USER@]HOST:SRC [DEST]
 
 rsync [OPTION]... [USER@]HOST::SRC [DEST]
@@ -57,8 +59,8 @@ host specification, OR when an rsync:// URL is specified (see also the
 "USING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION" section for
 an exception to this latter rule).
 
-As a special case, if a remote source is specified without a destination,
-the remote files are listed in an output format similar to "ls -l".
+As a special case, if a single source arg is specified without a
+destination, the files are listed in an output format similar to "ls -l".
 
 As expected, if neither the source or destination path specify a remote
 host, the copy occurs locally (see also the bf(--list-only) option).
@@ -470,11 +472,21 @@ 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 all files using
-a 128-bit MD4 checksum before transfer. The checksum is then
-explicitly checked on the receiver and any files of the same name
-which already exist and have the same checksum and size on the
-receiver are not transferred.  This option can be quite slow.
+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
+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
 way of saying you want recursion and want to preserve almost
@@ -516,12 +528,12 @@ example, if you used this command:
 
 quote(tt(   rsync -av /foo/bar/baz.c remote:/tmp/))
 
-... this would create a file called baz.c in /tmp/ on the remote
+... this would create a file named baz.c in /tmp/ on the remote
 machine. If instead you used
 
 quote(tt(   rsync -avR /foo/bar/baz.c remote:/tmp/))
 
-then a file called /tmp/foo/bar/baz.c would be created on the remote
+then a file named /tmp/foo/bar/baz.c would be created on the remote
 machine -- the full path name is preserved.  To limit the amount of
 path information that is sent, you have a couple options:  (1) With
 a modern rsync on the sending side (beginning with 2.6.7), you can
@@ -1559,7 +1571,7 @@ the necessary destination directories to hold the .pdf files, and ensures
 that any superfluous files and directories in the destination are removed
 (note the hide filter of non-directories being used instead of an exclude):
 
-quote(     rsync -avm --del --include='*.pdf' -f 'hide! */' src/ dest)
+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
@@ -1602,12 +1614,12 @@ single line.
 
 dit(bf(--list-only)) This option will cause the source files to be listed
 instead of transferred.  This option is inferred if there is no destination
-specified, so you don't usually need to use it explicitly.  However, it can
-come in handy for a user that wants to avoid the "bf(-r --exclude='/*/*')"
-options that rsync might use as a compatibility kluge when generating a
-non-recursive listing, or to list the files that are involved in a local
-copy (since the destination path is not optional for a local copy, you
-must specify this option explicitly and still include a destination).
+specified, so its main uses are: (1) to turn a copy command that includes a
+destination arg into a file-listing command, (2) to be able to specify more
+than one local source arg (note: be sure to include the destination), or
+(3) to avoid the automatically added "bf(-r --exclude='/*/*')" options that
+rsync usually uses as a compatibility kluge when generating a non-recursive
+listing.
 
 dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum
 transfer rate in kilobytes per second. This option is most effective when
@@ -1805,7 +1817,7 @@ itemize(
   particular spot in the hierarchy of files, otherwise it is matched
   against the end of the pathname.  This is similar to a leading ^ in
   regular expressions.
-  Thus "/foo" would match a file called "foo" at either the "root of the
+  Thus "/foo" would match a file named "foo" at either the "root of the
   transfer" (for a global rule) or in the merge-file's directory (for a
   per-directory rule).
   An unqualified "foo" would match any file or directory named "foo"
@@ -1864,7 +1876,8 @@ This fails because the parent directory "some" is excluded by the '*'
 rule, so rsync never visits any of the files in the "some" or "some/path"
 directories.  One solution is to ask for all directories in the hierarchy
 to be included by using a single rule: "+ */" (put it somewhere before the
-"- *" rule).  Another solution is to add specific include rules for all
+"- *" rule), and perhaps use the bf(--prune-empty-dirs) option.  Another
+solution is to add specific include rules for all
 the parent dirs that need to be visited.  For instance, this set of rules
 works fine:
 
@@ -1880,14 +1893,16 @@ Here are some examples of exclude/include matching:
 
 itemize(
   it() "- *.o" would exclude all filenames matching *.o
-  it() "- /foo" would exclude a file called foo in the transfer-root directory
-  it() "- foo/" would exclude any directory called foo
-  it() "- /foo/*/bar" would exclude any file called bar two
-  levels below a directory called foo in the transfer-root directory
-  it() "- /foo/**/bar" would exclude any file called bar two
-  or more levels below a directory called foo in the transfer-root directory
+  it() "- /foo" would exclude a file (or directory) named foo in the
+  transfer-root directory
+  it() "- foo/" would exclude any directory named foo
+  it() "- /foo/*/bar" would exclude any file named bar which is at two
+  levels below a directory named foo in the transfer-root directory
+  it() "- /foo/**/bar" would exclude any file named bar two
+  or more levels below a directory named foo in the transfer-root directory
   it() The combination of "+ */", "+ *.c", and "- *" would include all
-  directories and C source files but nothing else.
+  directories and C source files but nothing else (see also the
+  bf(--prune-empty-dirs) option)
   it() The combination of "+ foo/", "+ foo/bar.c", and "- *" would include
   only the foo directory and foo/bar.c (the foo directory must be
   explicitly included or it would be excluded by the "*")
@@ -2428,7 +2443,7 @@ url(http://rsync.samba.org/)(http://rsync.samba.org/)
 
 manpagesection(VERSION)
 
-This man page is current for version 2.6.7pre1 of rsync.
+This man page is current for version 2.6.7pre2 of rsync.
 
 manpagesection(CREDITS)