X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/8a405c6ca15248347b8683184bc7e61f725ed027..58cf354711f9e7eb2ec2a54b5f623abb860dafcf:/doc/rsync.sgml
diff --git a/doc/rsync.sgml b/doc/rsync.sgml
index 48f34144..76a50c26 100644
--- a/doc/rsync.sgml
+++ b/doc/rsync.sgml
@@ -94,23 +94,258 @@
The most commonly used arguments for rsync are
-
+
+
+
+
+ Be verbose. Primarily, display the name of each file as it is copied.
+
+
+
+
+
+
+
+
+ Reproduce the structure and attributes of the origin files as exactly
+ as possible: this includes copying subdirectories, symlinks, special
+ files, ownership and permissions. (@xref{Attributes to
+ copy}.)
+
+
+
+
+
+
+
+
+
+
+ Compress network traffic, using a modified version of the
+ @command{zlib} library.
+
+
+ Display a progress indicator while files are transferred. This should
+ normally be ommitted if rsync is not run on a terminal.
+
+
+
+
+
+
+
+ Local and remote
+
+ There are six different ways of using rsync. They
+ are:
+
+
+
+
+
+
+
+ for copying local files. This is invoked when neither
+ source nor destination path contains a @code{:} separator
+
+
+
+ for copying from the local machine to a remote machine using
+ a remote shell program as the transport (such as rsh or
+ ssh). This is invoked when the destination path contains a
+ single @code{:} separator.
+
+
+
+ for copying from a remote machine to the local machine
+ using a remote shell program. This is invoked when the source
+ contains a @code{:} separator.
+
+
+
+ for copying from a remote rsync server to the local
+ machine. This is invoked when the source path contains a @code{::}
+ separator or a @code{rsync://} URL.
+
+
+
+ for copying from the local machine to a remote rsync
+ server. This is invoked when the destination path contains a @code{::}
+ separator.
+
+
+
+ for listing files on a remote machine. This is done the
+ same way as rsync transfers except that you leave off the
+ local destination.
+
+
+
+
+Note that in all cases (other than listing) at least one of the source
+and destination paths must be local.
+
+
+Any one invocation of rsync makes a copy in a single direction. rsync
+currently has no equivalent of @command{ftp}'s interactive mode.
+
+@cindex @sc{nfs}
+@cindex network filesystems
+@cindex remote filesystems
+
+
+rsync's network protocol is generally faster at copying files than
+network filesystems such as @sc{nfs} or @sc{cifs}. It is better to
+run rsync on the file server either as a daemon or over ssh than
+running rsync giving the network directory.
+
+
+
+
+
+ Frequently asked questions
+
+
+
+
+
+
+
+
+
+ Are there mailing lists for rsync?
+
+
+
+ Yes, and you can subscribe and unsubscribe through a
+ web interface at
+ http://lists.samba.org/
+
+
+
+ If you are having trouble with the mailing list, please
+ send mail to the administrator
+
+ rsync-admin@lists.samba.org
+
+ not to the list itself.
+
+
+
+ The mailing list archives are searchable. Use
+ Google and prepend
+ the search with site:lists.samba.org
+ rsync, plus relevant keywords.
+
+
+
+
+
+
+
+
+ Why is rsync so much bigger when I build it with
+ gcc?
+
+
+
+
+ On gcc, rsync builds by default with debug symbols
+ included. If you strip both executables, they should end
+ up about the same size. (Use make
+ install-strip.)
+
+
+
+
+
+
+
+ Is rsync useful for a single large file like an ISO image?
+
+
+
+ Yes, but note the following:
+
+
+ Background: A common use of rsync is to update a file (or set of files) in one location from a more
+ correct or up-to-date copy in another location, taking advantage of portions of the files that are
+ identical to speed up the process. (Note that rsync will transfer a file in its entirety if no copy
+ exists at the destination.)
+
+
+ (This discussion is written in terms of updating a local copy of a file from a correct file in a
+ remote location, although rsync can work in either direction.)
+
+
+ The file to be updated (the local file) must be in a destination directory that has enough space for
+ two copies of the file. (In addition, keep an extra copy of the file to be updated in a different
+ location for safety -- see the discussion (below) about rsync's behavior when the rsync process is
+ interrupted before completion.)
+
+
+ The local file must have the same name as the remote file being sync'd to (I think?). If you are
+ trying to upgrade an iso from, for example, beta1 to beta2, rename the local file to the same name
+ as the beta2 file. *(This is a useful thing to do -- only the changed portions will be
+ transmitted.)*
+
+
+ The extra copy of the local file kept in a different location is because of rsync's behavior if
+ interrupted before completion:
+
+
+ * If you specify the --partial option and rsync is interrupted, rsync will save the partially
+ rsync'd file and throw away the original local copy. (The partially rsync'd file is correct but
+ truncated.) If rsync is restarted, it will not have a local copy of the file to check for duplicate
+ blocks beyond the section of the file that has already been rsync'd, thus the remainder of the rsync
+ process will be a "pure transfer" of the file rather than taking advantage of the rsync algorithm.
+
+
+ * If you don't specify the --partial option and rsync is interrupted, rsync will throw away the
+ partially rsync'd file, and, when rsync is restarted starts the rsync process over from the
+ beginning.
+
+
+ Which of these is most desirable depends on the degree of commonality between the local and remote
+ copies of the file *and how much progress was made before the interruption*.
+
+
+ The ideal approach after an interruption would be to create a new file by taking the original file
+ and deleting a portion equal in size to the portion already rsync'd and then appending *the
+ remaining* portion to the portion of the file that has already been rsync'd. (There has been some
+ discussion about creating an option to do this automatically.)
+
+ The --compare-dest option is useful when transferring multiple files, but is of no benefit in
+ transferring a single file. (AFAIK)
+
+ *Other potentially useful information can be found at:
+ -[3]http://twiki.org/cgi-bin/view/Wikilearn/RsyncingALargeFile
+
+ This answer, formatted with "real" bullets, can be found at:
+ -[4]http://twiki.org/cgi-bin/view/Wikilearn/RsyncingALargeFileFAQ*
+
+
+
+
+
+
+
+
+
+ Other Resources
+
+
+
\ No newline at end of file