X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/d0bc3520de9ef1decf9ec1e41b7c64e2af034ec9..42afed9c1ac7e54a0dd233ba1b22faaafccb683b:/rsync.yo diff --git a/rsync.yo b/rsync.yo index f94d5d4a..b7574891 100644 --- a/rsync.yo +++ b/rsync.yo @@ -1,5 +1,5 @@ mailto(rsync-bugs@samba.org) -manpage(rsync)(1)(30 Apr 2004)()() +manpage(rsync)(1)(21 Sep 2004)()() manpagename(rsync)(faster, flexible replacement for rcp) manpagesynopsis() @@ -21,8 +21,8 @@ manpagedescription() rsync is a program that behaves in much the same way that rcp does, but has many more options and uses the rsync remote-update protocol to -greatly speed up file transfers when the destination file already -exists. +greatly speed up file transfers when the destination file is being +updated. The rsync remote-update protocol allows rsync to transfer just the differences between two sets of files across the network connection, using @@ -113,7 +113,7 @@ and a destination, one of which may be remote. Perhaps the best way to explain the syntax is with some examples: -quote(rsync *.c foo:src/) +quote(rsync -t *.c foo:src/) This would transfer all files matching the pattern *.c from the current directory to the directory src on the machine foo. If any of @@ -141,8 +141,8 @@ 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) +quote(rsync -av /src/foo /dest) +quote(rsync -av /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 @@ -154,6 +154,35 @@ This would list all the anonymous rsync modules available on the host somehost.mydomain.com. (See the following section for more details.) +manpagesection(ADVANCED USAGE) + +The syntax for requesting multiple files from a remote host involves using +quoted spaces in the SRC. Some examples: + +quote(rsync host::'modname/dir1/file1 modname/dir2/file2' /dest) + +This would copy file1 and file2 into /dest from an rsync daemon. Each +additional arg must include the same "modname/" prefix as the first one, +and must be preceded by a single space. All other spaces are assumed +to be a part of the filenames. + +quote(rsync -av host:'dir1/file1 dir2/file2' /dest) + +This would copy file1 and file2 into /dest using a remote shell. This +word-splitting is done by the remote shell, so if it doesn't work it means +that the remote shell isn't configured to split its args based on +whitespace (a very rare setting, but not unknown). If you need to transfer +a filename that contains whitespace, you'll need to either escape the +whitespace in a way that the remote shell will understand, or use wildcards +in place of the spaces. Two examples of this are: + +quote(rsync -av host:'file\ name\ with\ spaces' /dest) +quote(rsync -av host:file?name?with?spaces /dest) + +This latter example assumes that your shell passes through unmatched +wildcards. If it complains about "no match", put the name in quotes. + + manpagesection(CONNECTING TO AN RSYNC SERVER) It is also possible to use rsync without a remote shell as the @@ -770,20 +799,25 @@ although this skips files that haven't changed; see also --link-dest). This option increases the usefulness of --partial because partially transferred files will remain in the new temporary destination until they have a chance to be completed. If DIR is a relative path, it is relative -to the destination directory (which changes in a recursive transfer). +to the destination directory. dit(bf(--link-dest=DIR)) This option behaves like bf(--compare-dest) but also will create hard links from em(DIR) to the destination directory for unchanged files. Files with changed ownership or permissions will not be linked. -Like bf(--compare-dest) if DIR is a relative path, it is relative -to the destination directory (which changes in a recursive transfer). An example: verb( rsync -av --link-dest=$PWD/prior_dir host:src_dir/ new_dir/ ) +Like bf(--compare-dest) if DIR is a relative path, it is relative to the +destination directory. +Note that rsync versions prior to 2.6.1 had a bug that could prevent +--link-dest from working properly for a non-root user when -o was specified +(or implied by -a). If the receiving rsync is not new enough, you can work +around this bug by avoiding the -o option. + dit(bf(-z, --compress)) With this option, rsync compresses any data from the files that it sends to the destination machine. This option is useful on slow connections. The compression method used is the @@ -878,7 +912,9 @@ put a partially transferred file into DIR instead of writing out the file to the destination dir. Rsync will also use a file found in this dir as data to speed up the transfer (i.e. when you redo the send after rsync creates a partial file) and delete such a file after it has served -its purpose. +its purpose. Note that if --whole-file is specified (or implied) that an +existing partial-dir file will not be used to speedup the transfer (since +rsync is sending files without using the incremental rsync algorithm). Rsync will create the dir if it is missing (just the last dir -- not the whole path). This makes it easy to use a relative path (such as @@ -893,8 +929,18 @@ prevent the partial file from being deleted (it could get deleted at the end of the transfer when using --delete-after, or at the beginning of the transfer when using --delete). E.g. "--exclude=.rsync-partial/". -IMPORTANT: the --partial-dir should not be writable by other users to -avoid a security risk. E.g. AVOID "/tmp". +IMPORTANT: the --partial-dir should not be writable by other users or it +is a security risk. E.g. AVOID "/tmp". + +You can also set the partial-dir value the RSYNC_PARTIAL_DIR environment +variable. Setting this in the environment does not force --partial to be +enabled, but rather it effects where partial files go when --partial (or +-P) is used. For instance, instead of specifying --partial-dir=.rsync-tmp +along with --progress, you could set RSYNC_PARTIAL_DIR=.rsync-tmp in your +environment and then just use the -P option to turn on the use of the +.rsync-tmp dir for partial transfers. The only time the --partial option +does not look for this environment value is when --inplace was also +specified (since --inplace conflicts with --partial-dir). dit(bf(--progress)) This option tells rsync to print information showing the progress of the transfer. This gives a bored user @@ -1220,15 +1266,18 @@ is encountered the update might be discarded with no error (if the file appears to be up-to-date already) or the file-update may be attempted and then, if the file fails to verify, the update discarded with an error. This means that it should be safe to re-run a read-batch operation -if the command got updated. If you wish to force the batched-update to +if the command got interrupted. If you wish to force the batched-update to always be attempted regardless of the file's size and date, use the -I -option. If an error occurs, the destination tree will probably be in a +option (when reading the batch). +If an error occurs, the destination tree will probably be in a partially updated state. In that case, rsync can be used in its regular (non-batch) mode of operation to fix up the destination tree. The rsync version used on all destinations must be at least as new as the -one used to generate the batch file. +one used to generate the batch file. Rsync will die with an error if the +protocol version in the batch file is too new for the batch-reading rsync +to handle. The --dry-run (-n) option does not work in batch mode and yields a runtime error. @@ -1248,8 +1297,8 @@ list if a change in what gets deleted by --delete is desired. A normal user can ignore this detail and just use the shell script as an easy way to run the appropriate --read-batch command for the batched data. -See bf(http://www.ils.unc.edu/i2dsi/unc_rsync+.html) for papers and technical -reports. +The original batch mode in rsync was based on "rsync+", but the latest +version uses a new implementation. manpagesection(SYMBOLIC LINKS)