rsync.yo doc patch
Aaron S. Hawley
Aaron.Hawley at uvm.edu
Fri Jan 23 00:00:17 GMT 2004
Patch includes fixes to man page including:
- Typos/Spelling
- Clarity
- Special characters.
- Moved around text explaining example.
Make sure I didn't confuse the exclude list/file paragraph (line ~961
after applying the patch), I haven't used the feature and the motive of
that paragraph is a tad unclear.
Hope the patch is helpful.
Never had used yodl before.
Thanks for rsync.
/a
http://www.uvm.edu/~ashawley/rsync/rsync.yo-ashawley.diff-u
Index: rsync.yo
===================================================================
RCS file: /cvsroot/rsync/rsync.yo,v
retrieving revision 1.139
diff -u -r1.139 rsync.yo
--- rsync.yo 15 Jan 2004 17:45:53 -0000 1.139
+++ rsync.yo 22 Jan 2004 23:52:11 -0000
@@ -48,36 +48,36 @@
itemize(
it() for copying local files. This is invoked when neither
- source nor destination path contains a : separator
+ source nor destination path contains a single colon (":") separator
it() for copying from the local machine to a remote machine using
a remote shell program as the transport (such as ssh or
rsh). This is invoked when the destination path contains a
- single : separator.
+ single colon (":") separator.
it() for copying from a remote machine to the local machine
using a remote shell program. This is invoked when the source
- contains a : separator.
+ contains a single colon (":") separator.
it() for copying from a remote rsync server to the local
- machine. This is invoked when the source path contains a ::
+ machine. This is invoked when the source path contains a double colon ("::")
separator or a rsync:// URL.
it() for copying from the local machine to a remote rsync
- server. This is invoked when the destination path contains a ::
+ server. This is invoked when the destination path contains a double colon ("::")
separator or a rsync:// URL.
it() for copying from a remote machine using a remote shell
program as the transport, using rsync server on the remote
- machine. This is invoked when the source path contains a ::
+ machine. This is invoked when the source path contains a double colon ("::")
separator and the --rsh=COMMAND (aka "-e COMMAND") option is
also provided.
it() for copying from the local machine to a remote machine
using a remote shell program as the transport, using rsync
server on the remote machine. This is invoked when the
- destination path contains a :: separator and the
- --rsh=COMMMAND option is also provided.
+ destination path contains a double colon ("::") separator and the
+ --rsh=COMMAND option is also provided.
it() for listing files on a remote machine. This is done the
same way as rsync transfers except that you leave off the
@@ -111,7 +111,7 @@
You use rsync in the same way you use rcp. You must specify a source
and a destination, one of which may be remote.
-Perhaps the best way to explain the syntax is some examples:
+Perhaps the best way to explain the syntax is with some examples:
quote(rsync *.c foo:src/)
@@ -121,38 +121,39 @@
remote-update protocol is used to update the file by sending only the
differences. See the tech report for details.
+This would recursively transfer all files from the directory src/bar on the
+machine foo into the /data/tmp/bar directory on the local machine.
+
quote(rsync -avz foo:src/bar /data/tmp)
-This would recursively transfer all files from the directory src/bar on the
-machine foo into the /data/tmp/bar directory on the local machine. The
-files are transferred in "archive" mode, which ensures that symbolic
-links, devices, attributes, permissions, ownerships etc are preserved
-in the transfer. Additionally, compression will be used to reduce the
-size of data portions of the transfer.
+The files are transferred in "archive" mode, which ensures that
+symbolic links, devices, attributes, permissions, ownerships etc are
+preserved in the transfer. Additionally, compression will be used to
+reduce the size of data portions of the transfer.
+
+A trailing slash on the source changes this behavior to avoid creating an
+additional directory level at the destination.
quote(rsync -avz foo:src/bar/ /data/tmp)
-A trailing slash on the source changes this behavior to avoid creating an
-additional directory level at the destination. You can think of a trailing
-/ on a source as meaning "copy the contents of this directory" as opposed
-to "copy the directory by name", but in both cases the attributes of the
-containing directory are transferred to the containing directory on the
-destination. In other words, each of the following commands copies the
-files in the same way, including their setting of the attributes of
-/dest/foo:
+You can think of a trailing slash ("/") on a source as meaning "copy the
+contents of this directory" as opposed to "copy the directory by
+name", but in both cases the attributes of the containing directory
+are transferred to the containing directory on the destination. In
+other words, each of the following commands copies the files in the
+same way, including their setting of the attributes of /dest/foo:
quote(rsync -avz /src/foo /dest)
quote(rsync -avz /src/foo/ /dest/foo)
You can also use rsync in local-only mode, where both the source and
-destination don't have a ':' in the name. In this case it behaves like
-an improved copy command.
-
-quote(rsync somehost.mydomain.com::)
+destination don't have a colon (":") in the name. This behaves like an
+improved copy command.
This would list all the anonymous rsync modules available on the host
somehost.mydomain.com. (See the following section for more details.)
+quote(rsync somehost.mydomain.com::)
manpagesection(CONNECTING TO AN RSYNC SERVER)
@@ -163,14 +164,14 @@
You may establish the connection via a web proxy by setting the
environment variable RSYNC_PROXY to a hostname:port pair pointing to
your web proxy. Note that your web proxy's configuration must allow
-proxying to port 873.
+proxy connections to port 873.
Using rsync in this way is the same as using it with a remote shell except
that:
itemize(
- it() you use a double colon :: instead of a single colon to
- separate the hostname from the path or a rsync:// URL.
+ it() you use a double colon ("::") instead of a single colon
+ (":") to separate the hostname from the path or a rsync:// URL.
it() the remote server may print a message of the day when you
connect.
@@ -217,7 +218,7 @@
manpagesection(RUNNING AN RSYNC SERVER)
-An rsync server is configured using a config file. Please see the
+An rsync server is configured using a configuration file. Please see the
rsyncd.conf(5) man page for more information. By default the configuration
file is called /etc/rsyncd.conf, unless rsync is running over a remote
shell program and is not running as root; in that case, the default name
@@ -261,10 +262,10 @@
sync: get put)
this allows me to sync with a CVS directory at the other end of the
-connection. I then do cvs operations on the remote machine, which saves a
-lot of time as the remote cvs protocol isn't very efficient.
+connection. I then do CVS operations on the remote machine, which saves a
+lot of time as the remote CVS protocol isn't very efficient.
-I mirror a directory between my "old" and "new" ftp sites with the
+I mirror a directory between my "old" and "new" FTP sites with the
command
quote(rsync -az -e ssh --delete ~ftp/pub/samba/ nimbus:"~ftp/pub/tridge/samba")
@@ -395,7 +396,7 @@
the timestamps as being equal if they are within the value of
modify_window. This is normally zero, but you may find it useful to
set this to a larger value in some situations. In particular, when
-transferring to Windows FAT filesystems which cannot represent times
+transferring to Windows FAT file systems which cannot represent times
with a 1 second resolution --modify-window=1 is useful.
dit(bf(-c, --checksum)) This forces the sender to checksum all files using
@@ -514,7 +515,7 @@
destination file to be the same as the source file. On most systems,
only the super-user can set file ownership. Note that if the remote system
is a daemon using chroot, the --numeric-ids option is implied because the
-remote system cannot get access to the usernames from /etc/passwd.
+remote system cannot get access to the user names from /etc/passwd.
dit(bf(-g, --group)) This option causes rsync to set the group of the
destination file to be the same as the source file. If the receiving
@@ -602,7 +603,7 @@
default, but you may prefer to use rsh on a local network.
If this option is used with bf([user@]host::module/path), then the
-remote shell em(COMMMAND) will be used to run an rsync server on the
+remote shell em(COMMAND) will be used to run an rsync server on the
remote host, and all data will be transmitted through that remote
shell connection, rather than through a direct socket connection to a
running rsync server on the remote host. See the section "CONNECTING
@@ -672,35 +673,36 @@
If em(FILE) is bf(-) the list will be read from standard input.
dit(bf(--files-from=FILE)) Using this option allows you to specify the
-exact list of files to transfer (as read from the specified FILE or "-"
-for stdin). It also tweaks the default behavior of rsync to make
-transferring just the specified files and directories easier. For
-instance, the --relative option is enabled by default when this option
-is used (use --no-relative if you want to turn that off), all
-directories specified in the list are created on the destination (rather
-than being noisily skipped without -r), and the -a (--archive) option's
-behavior does not imply -r (--recursive) -- specify it explicitly, if
-you want it.
+exact list of files to transfer as read from the specified FILE or if
+a dash ("-") from standard input (stdin). It also tweaks the default
+behavior of rsync to make transferring just the specified files and
+directories easier. For instance, the --relative option is enabled by
+default when this option is used (use --no-relative if you want to
+turn that off), all directories specified in the list are created on
+the destination (rather than being noisily skipped without -r), and
+the -a (--archive) option's behavior does not imply -r (--recursive)
+-- specify it explicitly, if you want it.
The file names that are read from the FILE are all relative to the
-source dir -- any leading slashes are removed and no ".." references are
-allowed to go higher than the source dir. For example, take this
-command:
+source directory -- any leading slashes are removed and no parent
+directory ("..") references are allowed to go higher than the source
+directory. For example, take this command:
quote(rsync -a --files-from=/tmp/foo /usr remote:/backup)
If /tmp/foo contains the string "bin" (or even "/bin"), the /usr/bin
directory will be created as /backup/bin on the remote host (but the
-contents of the /usr/bin dir would not be sent unless you specified -r
-or the names were explicitly listed in /tmp/foo). Also keep in mind
-that the effect of the (enabled by default) --relative option is to
-duplicate only the path info that is read from the file -- it does not
-force the duplication of the source-spec path (/usr in this case).
+contents of the /usr/bin directory would not be sent unless you
+specified -r or the names were explicitly listed in /tmp/foo). Also
+keep in mind that the effect of the (enabled by default) --relative
+option is to duplicate only the path info that is read from the file
+-- it does not force the duplication of the source-spec path (/usr in
+this case).
In addition, the --files-from file can be read from the remote host
instead of the local host if you specify a "host:" in front of the file
(the host must match one end of the transfer). As a short-cut, you can
-specify just a prefix of ":" to mean "use the remote end of the
+specify just a prefix of colon (":") to mean "use the remote end of the
transfer". For example:
quote(rsync -a --files-from=:/path/file-list src:/ /tmp/copy)
@@ -867,7 +869,7 @@
using rsync with large files (several megabytes and up). Due to the nature
of rsync transfers, blocks of data are sent, then if rsync determines the
transfer was too fast, it will wait before sending the next data block. The
-result is an average transfer rate equalling the specified limit. A value
+result is an average transfer rate equaling the specified limit. A value
of zero specifies no limit.
dit(bf(--write-batch=PREFIX)) Generate a set of files that can be
@@ -912,50 +914,53 @@
itemize(
- it() if the pattern starts with a / then it is matched against the
- start of the filename, otherwise it is matched against the end of
- the filename.
- This is the equivalent of a leading ^ in regular expressions.
+ it() if the pattern starts with a slash ("/") then it is matched
+ against the start of the filename, otherwise it is matched against
+ the end of the filename.
+ This is the equivalent of a leading caret ("^") in regular expressions.
Thus "/foo" would match a file called "foo" at the top of the
transferred tree.
On the other hand, "foo" would match any file called "foo"
anywhere in the tree because the algorithm is applied recursively from
top down; it behaves as if each path component gets a turn at being the
end of the file name.
- The leading / does not make the pattern an absolute pathname.
+ The leading slash ("/") does not make the pattern an absolute pathname.
- it() if the pattern ends with a / then it will only match a
+ it() if the pattern ends with a slash ("/") then it will only match a
directory, not a file, link or device.
it() if the pattern contains a wildcard character from the set
- *?[ then expression matching is applied using the shell filename
+ "*?[" then expression matching is applied using the shell filename
matching rules. Otherwise a simple string match is used.
- it() the double asterisk pattern "**" will match slashes while a
- single asterisk pattern "*" will stop at slashes.
+ it() the double asterisk pattern ("**") will match slashes while a
+ single asterisk pattern ("*") will stop at slashes.
- it() if the pattern contains a / (not counting a trailing /) or a "**"
- then it is matched against the full filename, including any leading
- directory. If the pattern doesn't contain a / or a "**", then it is
+ it() if the pattern contains a slash ("/") (not counting a trailing
+ slash) or a double asterisk ("**") then it is matched against the full
+ filename, including any leading directory. If the pattern doesn't
+ contain a slash ("/") or a double asterisk ("**"), then it is
matched only against the final component of the filename. Again,
remember that the algorithm is applied recursively so "full filename" can
actually be any portion of a path below the starting directory.
- it() if the pattern starts with "+ " (a plus followed by a space)
- then it is always considered an include pattern, even if specified as
- part of an exclude option. The "+ " part is discarded before matching.
-
- it() if the pattern starts with "- " (a minus followed by a space)
- then it is always considered an exclude pattern, even if specified as
- part of an include option. The "- " part is discarded before matching.
+ it() if the pattern starts with plus-space ("+ ")--a plus followed
+ by a space--then it is always considered an include pattern, even if
+ specified as part of an exclude option. The plus-space ("+ ") part
+ is discarded before matching.
+
+ it() if the pattern starts with minus-space ("- ")--a minus followed
+ by a space--then it is always considered an exclude pattern, even if
+ specified as part of an include option. The "- " part is discarded
+ before matching.
- it() if the pattern is a single exclamation mark ! then the current
+ it() if the pattern is a single exclamation mark ("!") then the current
include/exclude list is reset, removing all previously defined patterns.
)
-The +/- rules are most useful in a list that was read from a file, allowing
-you to have a single exclude list that contains both include and exclude
-options.
+The plus-space ("+ ") and minus-space ("- ") rules are most useful in
+a list that was read from a file, allowing you to have a single
+exclude list that contains both include and exclude options.
If you end an exclude list with --exclude '*', note that since the
algorithm is applied recursively that unless you explicitly include
@@ -1085,11 +1090,12 @@
bf(/etc/passwd) in the public section of the site. Using
bf(--copy-unsafe-links) will cause any links to be copied as the file
they point to on the destination. Using bf(--safe-links) will cause
-unsafe links to be ommitted altogether.
+unsafe links to be omitted altogether.
Symbolic links are considered unsafe if they are absolute symlinks
-(start with bf(/)), empty, or if they contain enough bf("..")
-components to ascend from the directory being copied.
+(start with a slash ("bf(/)")), empty, or if they contain enough
+parent directory (bf("..")) components to ascend from the directory
+being copied.
manpagesection(DIAGNOSTICS)
@@ -1124,10 +1130,10 @@
dit(bf(0)) Success
dit(bf(1)) Syntax or usage error
dit(bf(2)) Protocol incompatibility
-dit(bf(3)) Errors selecting input/output files, dirs
+dit(bf(3)) Errors selecting input/output files, directories
dit(bf(4)) Requested action not supported: an attempt
was made to manipulate 64-bit files on a platform that cannot support
-them; or an option was speciifed that is supported by the client and
+them; or an option was specified that is supported by the client and
not by the server.
dit(bf(5)) Error starting client-server protocol
dit(bf(10)) Error in socket IO
@@ -1165,7 +1171,7 @@
password to a shell transport such as ssh.
dit(bf(USER) or bf(LOGNAME)) The USER or LOGNAME environment variables
-are used to determine the default username sent to a rsync server.
+are used to determine the default user name sent to a rsync server.
dit(bf(HOME)) The HOME environment variable is used to find the user's
default .cvsignore file.
@@ -1186,7 +1192,7 @@
times are transferred as unix time_t values
-When transferring to FAT filesystmes rsync may resync
+When transferring to FAT file systems rsync may resync
unmodified files.
See the comments on the --modify-window option.
@@ -1195,7 +1201,7 @@
see also the comments on the --delete option
-Please report bugs! See the website at
+Please report bugs! See the web site at
url(http://rsync.samba.org/)(http://rsync.samba.org/)
manpagesection(CREDITS)
@@ -1208,7 +1214,7 @@
includes an FAQ-O-Matic which may cover questions unanswered by this
manual page.
-The primary ftp site for rsync is
+The primary FTP site for rsync is
url(ftp://rsync.samba.org/pub/rsync)(ftp://rsync.samba.org/pub/rsync).
We would be delighted to hear from you if you like this program.
More information about the rsync
mailing list