X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/1f69bec48061b42c6515bbd4e5fbd1b6e7544a1d..4ce838e1f107239f1b18f3f8cd7c7fbab65e0bd5:/rsync.yo diff --git a/rsync.yo b/rsync.yo index de1af7f8..589545ac 100644 --- a/rsync.yo +++ b/rsync.yo @@ -356,7 +356,8 @@ verb( --modify-window=NUM compare mod times with reduced accuracy -T --temp-dir=DIR create temporary files in directory DIR --compare-dest=DIR also compare received files relative to DIR - --link-dest=DIR create hardlinks to DIR for unchanged files + --copy-dest=DIR ... and include copies of unchanged files + --link-dest=DIR hardlink to files in DIR when unchanged -P equivalent to --partial --progress -z, --compress compress file data -C, --cvs-exclude auto ignore files in the same way CVS does @@ -367,6 +368,7 @@ verb( --files-from=FILE read FILE for list of source-file names -0 --from0 all file lists are delimited by nulls --version print version number + --port=PORT specify double-colon alternate port number --blocking-io use blocking I/O for the remote shell --no-blocking-io turn off --blocking-io --stats give some file transfer stats @@ -390,7 +392,7 @@ verb( --bwlimit=KBPS limit I/O bandwidth, KBytes per second --config=FILE specify alternate rsyncd.conf file --no-detach do not detach from the parent - --port=PORT specify alternate rsyncd port number + --port=PORT listen on alternate port number -4 --ipv4 prefer IPv4 -6 --ipv6 prefer IPv6 -h, --help show this help screen @@ -465,15 +467,21 @@ just the last parts of the filenames. This is particularly useful when you want to send several different directories at the same time. For example, if you used the command -verb(rsync foo/bar/foo.c remote:/tmp/) +verb(rsync /foo/bar/foo.c remote:/tmp/) then this would create a file called foo.c in /tmp/ on the remote machine. If instead you used -verb(rsync -R foo/bar/foo.c remote:/tmp/) +verb(rsync -R /foo/bar/foo.c remote:/tmp/) then a file called /tmp/foo/bar/foo.c would be created on the remote -machine -- the full path name is preserved. +machine -- the full path name is preserved. To limit the amount of +path information that is sent, do something like this: + +verb(cd /foo +rsync -R bar/foo.c remote:/tmp/) + +That would create /tmp/bar/foo.c on the remote machine. dit(bf(--no-relative)) Turn off the --relative option. This is only needed if you want to use --files-from without its implied --relative @@ -508,11 +516,13 @@ dit(bf(--suffix=SUFFIX)) This option allows you to override the default backup suffix used with the --backup (-b) option. The default suffix is a ~ if no --backup-dir was specified, otherwise it is an empty string. -dit(bf(-u, --update)) This forces rsync to skip any files for which the -destination file already exists and has a date later than the source -file. +dit(bf(-u, --update)) This forces rsync to skip any files which exist on +the destination and have a modified time that is newer than the source +file. (If an existing destination file has a modify time equal to the +source file's, it will be updated if the sizes are different.) -In the currently implementation, a difference of file format is always +In the current implementation of --update, a difference of file format +between the sender and receiver is always considered to be important enough for an update, no matter what date is on the objects. In other words, if the source has a directory or a symlink where the destination has a file, the transfer would occur @@ -534,9 +544,9 @@ or appended data, and also on systems that are disk bound, not network bound. The option implies --partial (since an interrupted transfer does not delete -the file), but conflicts with --partial-dir, --compare-dest, and +the file), but conflicts with --partial-dir, --compare-dest, --copy-dest, and --link-dest (a future rsync version will hopefully update the protocol to -remove these restrictions). +remove some of these restrictions). WARNING: The file's data will be in an inconsistent state during the transfer (and possibly afterward if the transfer gets interrupted), so you @@ -648,17 +658,22 @@ file that is larger than the specified SIZE. The SIZE value can be suffixed with a letter to indicate a size multiplier (K, M, or G) and may be a fractional value (e.g. "--max-size=1.5m"). -dit(bf(--delete)) This tells rsync to delete any files on the receiving -side that aren't on the sending side. Files that are excluded from -transfer are excluded from being deleted unless you use --delete-excluded. +dit(bf(--delete)) This tells rsync to delete extraneous files from the +receiving side (ones that aren't on the sending side), but only for the +directories that are being synchronized. You must have asked rsync to +send the whole directory (e.g. "dir" or "dir/") without using a wildcard +for the directory's contents (e.g. "dir/*") since the wildcard is expanded +by the shell and rsync thus gets a request to transfer those files, not +the files' parent directory. Files that are excluded from transfer are +excluded from being deleted unless you use --delete-excluded. This option has no effect if directory recursion is not selected. This option can be dangerous if used incorrectly! It is a very good idea -to run first using the dry run option (-n) to see what files would be +to run first using the --dry-run option (-n) to see what files would be deleted to make sure important files aren't listed. -If the sending side detects any I/O errors then the deletion of any +If the sending side detects any I/O errors, then the deletion of any files at the destination will be automatically disabled. This is to prevent temporary filesystem failures (such as NFS errors) on the sending side causing a massive deletion of files on the @@ -674,6 +689,10 @@ receiving side before transferring files to try to ensure that there is sufficient space on the receiving filesystem. If you want to delete after transferring, use the --delete-after switch. Implies --delete. +One reason to use --delete-after is to avoid a delay before the start of +the transfer (while the receiving side is scanned for deletions) as this +delay might cause the transfer to timeout. + dit(bf(--ignore-errors)) Tells --delete to go ahead and delete files even when there are I/O errors. @@ -808,31 +827,50 @@ scratch directory when creating temporary copies of the files transferred on the receiving side. The default behavior is to create the temporary files in the receiving directory. -dit(bf(--compare-dest=DIR)) This option instructs rsync to use DIR on -the destination machine as an additional directory to compare destination -files against when doing transfers if the files are missing in the -destination directory. This is useful for doing transfers to a new -destination while leaving existing files intact, and then doing a -flash-cutover when all files have been successfully transferred (for -example by moving directories around and removing the old directory, -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. - -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. +dit(bf(--compare-dest=DIR)) This option instructs rsync to use em(DIR) on +the destination machine as an additional hierarchy to compare destination +files against doing transfers (if the files are missing in the destination +directory). If a file is found in em(DIR) that is identical to the +sender's file, the file will NOT be transferred to the destination +directory. This is useful for creating a sparse backup of just files that +have changed from an earlier backup. + +Beginning in version 2.6.4, multiple --compare-dest directories may be +provided and rsync will search the list in the order specified until it +finds an existing file. That first discovery is used as the basis file, +and also determines if the transfer needs to happen. + +If em(DIR) is a relative path, it is relative to the destination directory. +See also --copy-dest and --link-dest. + +dit(bf(--copy-dest=DIR)) This option behaves like bf(--compare-dest), but +rsync will also copy unchanged files found in em(DIR) to the destination +directory (using the data in the em(DIR) for an efficient copy). This is +useful for doing transfers to a new destination while leaving existing +files intact, and then doing a flash-cutover when all files have been +successfully transferred. + +If em(DIR) is a relative path, it is relative to the destination directory. +See also --compare-dest and --link-dest. + +dit(bf(--link-dest=DIR)) This option behaves like bf(--copy-dest), but +unchanged files are hard linked from em(DIR) to the destination directory. +The files must be identical in all preserved attributes (e.g. permissions, +possibly ownership) in order for the files to be linked together. 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. +Beginning with version 2.6.4, if more than one --link-dest option is +specified, rsync will try to find an exact match to link with (searching +the list in the order specified), and if not found, a basis file from one +of the em(DIR)s will be selected to try to speed up the transfer. + +If em(DIR) is a relative path, it is relative to the destination directory. +See also --compare-dest and --copy-dest. + 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 @@ -868,6 +906,12 @@ dit(bf(--timeout=TIMEOUT)) This option allows you to set a maximum I/O timeout in seconds. If no data is transferred for the specified time then rsync will exit. The default is 0, which means no timeout. +dit(bf(--port=PORT)) This specifies an alternate TCP port number to use +rather than the default of 873. This is only needed if you are using the +double-colon (::) syntax to connect with an rsync daemon (since the URL +syntax has a way to specify the port as a part of the URL). See also this +option in the --daemon mode section. + dit(bf(--blocking-io)) This tells rsync to use blocking I/O when launching a remote shell transport. If the remote shell is either rsh or remsh, rsync defaults to using @@ -893,7 +937,7 @@ it is more desirable to keep partially transferred files. Using the make a subsequent transfer of the rest of the file much faster. dit(bf(--partial-dir=DIR)) Turns on --partial mode, but tells rsync to -put a partially transferred file into DIR instead of writing out the +put a partially transferred file into em(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 @@ -904,7 +948,7 @@ 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 "--partial-dir=.rsync-partial") to have rsync create the partial-directory -in the destination file's directory (rsync will also try to remove the DIR +in the destination file's directory (rsync will also try to remove the em(DIR) if a partial file was found to exist at the start of the transfer and the DIR was specified as a relative path). @@ -948,7 +992,7 @@ is complete, the current calculated file-completion rate (including both data over the wire and data being matched locally), and the estimated time remaining in this transfer. -After the a file is complete, it the data looks like this: +After a file is complete, the data looks like this: verb( 1238099 100% 146.38kB/s 0:00:08 (5, 57.1% of 396) @@ -991,7 +1035,7 @@ See the "BATCH MODE" section for details. dit(bf(-4, --ipv4) or bf(-6, --ipv6)) Tells rsync to prefer IPv4/IPv6 when creating sockets. This only affects sockets that rsync has direct control over, such as the outgoing socket when directly contacting an -rsync daemon (see also these options in the --daemon mode section). +rsync daemon. See also these options in the --daemon mode section. dit(bf(--checksum-seed=NUM)) Set the MD4 checksum seed to the integer NUM. This 4 byte checksum seed is included in each block and file @@ -1024,7 +1068,8 @@ dit(bf(--address)) By default rsync will bind to the wildcard address when run as a daemon with the --daemon option or when connecting to a rsync server. The --address option allows you to specify a specific IP address (or hostname) to bind to. This makes virtual hosting possible -in conjunction with the --config option. +in conjunction with the --config option. See also the "address" global +option in the rsyncd.conf manpage. dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum transfer rate in kilobytes per second for the data the daemon sends. @@ -1047,8 +1092,9 @@ bf(--no-detach) is also recommended when rsync is run under a debugger. This option has no effect if rsync is run from inetd or sshd. -dit(bf(--port=PORT)) This specifies an alternate TCP port number to use -rather than the default port 873. +dit(bf(--port=PORT)) This specifies an alternate TCP port number for the +daemon to listen on rather than the default of 873. See also the "port" +global option in the rsyncd.conf manpage. dit(bf(-4, --ipv4) or bf(-6, --ipv6)) Tells rsync to prefer IPv4/IPv6 when creating the incoming sockets that the rsync daemon will use to