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()
rsync [OPTION]... SRC [SRC]... rsync://[USER@]HOST[:PORT]/DEST
+rsync [OPTION]... SRC
+
rsync [OPTION]... [USER@]HOST:SRC [DEST]
rsync [OPTION]... [USER@]HOST::SRC [DEST]
"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).
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
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
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
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
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
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"
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:
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 "*")
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)
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff