One last change to make the --checksum distinction very clear.

[rsync/rsync.git] / rsync.yo

diff --git a/rsync.yo b/rsync.yo
index 61f3158..770832d 100644 (file)
--- a/rsync.yo
+++ b/rsync.yo
@@ -470,11 +470,20 @@ 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).
 
 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 every file using
+a 128-bit MD4 checksum before the transfer (during the initial file-system
+scan). The receiver then checksums every existing file that has the same
+size as its sender-side counterpart in order to decide which files need to
+be transferred: files with either a changed size or 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 and after 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 using a whole-file checksum,
+but that after-transfer check has nothing to do with this option's
+before-transfer "Does the 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
 
 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 +525,12 @@ example, if you used this command:
 
 quote(tt(   rsync -av /foo/bar/baz.c remote:/tmp/))
 
 
 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/))
 
 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
 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


@@ -1397,6 +1406,38 @@ 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: itemize(
+  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
+  were updated via the rsync algorithm, which does not include created
+  dirs, symlinks, etc.
+  it() bf(Total file size) is the total sum of all file sizes in the transfer.
+  This does not count any size for directories or special files, but does
+  include the size of symlinks.
+  it() bf(Total transferred file size) is the total sum of all files sizes
+  for just the transferred files.
+  it() bf(Literal data) is how much unmatched file-update data we had to
+  send to the receiver for it to recreate the updated files.
+  it() bf(Matched data) is how much data the receiver got locally when
+  recreating the updated files.
+  it() bf(File list size) is how big the file-list data was when the sender
+  sent it to the receiver.  This is smaller than the in-memory size for the
+  file list due to some compressing of duplicated data when rsync sends the
+  list.
+  it() bf(File list generation time) is the number of seconds that the
+  sender spent creating the file list.  This requires a modern rsync on the
+  sending side for this to be present.
+  it() bf(File list transfer time) is the number of seconds that the sender
+  spent sending the file list to the receiver.
+  it() bf(Total bytes sent) is the count of all the bytes that rsync sent
+  from the client side to the server side.
+  it() bf(Total bytes received) is the count of all non-message bytes that
+  rsync received by the client side from the server side.  "Non-message"
+  bytes means that we don't count the bytes for a verbose message that the
+  server sent to us, which makes the stats more consistent.
+)
+

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


@@ -1527,7 +1568,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):
 
 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
 
 If you didn't want to remove superfluous destination files, the more
 time-honored options of "--include='*/' --exclude='*'" would work fine


@@ -1773,7 +1814,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.
   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"
   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"


@@ -1832,7 +1873,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, 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:
 
 the parent dirs that need to be visited.  For instance, this set of rules
 works fine:
 


@@ -1848,14 +1890,16 @@ Here are some examples of exclude/include matching:
 
 itemize(
   it() "- *.o" would exclude all filenames matching *.o
 
 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
   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 "*")
   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 "*")