From: Andrew Tridgell Date: Fri, 5 Jun 2026 00:51:06 +0000 (+1000) Subject: Remove obsolete DocBook manual X-Git-Url: http://git.ipfire.org/gitweb/index.cgi?a=commitdiff_plain;h=5de07c13c1898af71f03b14a1b8074f7c45cb87f;p=thirdparty%2Frsync.git Remove obsolete DocBook manual doc/rsync.sgml is a 1996-2002 DocBook user manual (with README-SGML describing the docbook-utils build) that was long ago superseded by the markdown man pages. It is unmaintained and referenced by nothing in the build. This empties doc/. --- diff --git a/doc/README-SGML b/doc/README-SGML deleted file mode 100644 index ce5a8e18..00000000 --- a/doc/README-SGML +++ /dev/null @@ -1,20 +0,0 @@ -Handling the rsync SGML documentation - -rsync documentation is now primarily in Docbook format. Docbook is an -SGML/XML documentation format that is becoming standard on free -operating systems. It's also used for Samba documentation. - -The SGML files are source code that can be translated into various -useful output formats, primarily PDF, HTML, Postscript and plain text. - -To do this transformation on Debian, you should install the -docbook-utils package. Having done that, you can say - - docbook2pdf rsync.sgml - -and so on. - -On other systems you probably need James Clark's "sp" and "JadeTeX" -packages. Work it out for yourself and send a note to the mailing -list. - diff --git a/doc/rsync.sgml b/doc/rsync.sgml deleted file mode 100644 index 0f900590..00000000 --- a/doc/rsync.sgml +++ /dev/null @@ -1,351 +0,0 @@ - - - - rsync - - 1996 -- 2002 - Martin Pool - Andrew Tridgell - - - Martin - Pool - - - - - Introduction - - rsync is a flexible program for efficiently copying files or - directory trees. - - rsync has many options to select which files will be copied - and how they are to be transferred. It may be used as an - alternative to ftp, http, scp or rcp. - - The rsync remote-update protocol allows rsync to transfer just - the differences between two sets of files across the network link, - using an efficient checksum-search algorithm described in the - technical report that accompanies this package. - - Some of the additional features of rsync are: - - - - - support for copying links, devices, owners, groups and - permissions - - - - - - exclude and exclude-from options similar to GNU tar - - - - - - a CVS exclude mode for ignoring the same files that CVS would ignore - - - - - can use any transparent remote shell, including rsh or ssh - - - - - does not require root privileges - - - - - pipelining of file transfers to minimize latency costs - - - - - support for anonymous or authenticated rsync servers (ideal for - mirroring) - - - - - - - - - Using rsync -
- - Introductory example - - - - Probably the most common case of rsync usage is to copy files - to or from a remote machine using - ssh as a network transport. In - this situation rsync is a good alternative to - scp. - - - - 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 omitted 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 - - - -