X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/3bc67f0c4f0bf0ad9a59366ea05c837fd4d0e7b1..17d31b380b7c748837b30e7e0c54ab17974f7ab6:/rsync.yo diff --git a/rsync.yo b/rsync.yo index ff0f91df..28097494 100644 --- a/rsync.yo +++ b/rsync.yo @@ -1,19 +1,19 @@ mailto(rsync-bugs@samba.org) -manpage(rsync)(1)(7 Dec 1998)()() +manpage(rsync)(1)(18 Feb 1999)()() manpagename(rsync)(faster, flexible replacement for rcp) manpagesynopsis() -rsync [options] [user@]host:path path +rsync [OPTION]... SRC [SRC]... [USER@]HOST:DEST -rsync [options] path [user@]host:path +rsync [OPTION]... [USER@]HOST:SRC DEST -rsync [options] path path +rsync [OPTION]... SRC [SRC]... DEST -rsync [options] [user@]host::module[/path] path +rsync [OPTION]... [USER@]HOST::SRC [DEST] -rsync [options] path [user@]host::module[/path] +rsync [OPTION]... SRC [SRC]... [USER@]HOST::DEST -rsync [options] rsync://[user@]host[:port]/module/path path +rsync [OPTION]... rsync://[USER@]HOST[:PORT]/SRC [DEST] manpagedescription() @@ -159,10 +159,11 @@ itemize( Some paths on the remote server may require authentication. If so then you will receive a password prompt when you connect. You can avoid the password prompt by setting the environment variable RSYNC_PASSWORD to -the password you want to use. This may be useful when scripting rsync. +the password you want to use or using the --password-file option. This +may be useful when scripting rsync. WARNING: On some systems environment variables are visible to all -users. +users. On those systems using --password-file is recommended. manpagesection(RUNNING AN RSYNC SERVER) @@ -210,23 +211,29 @@ Here is a short summary of the options available in rsync. Please refer to the detailed description below for a complete description. verb( -Usage: rsync [OPTION]... SRC [USER@]HOST:DEST +Usage: rsync [OPTION]... SRC [SRC]... [USER@]HOST:DEST or rsync [OPTION]... [USER@]HOST:SRC DEST - or rsync [OPTION]... SRC DEST + or rsync [OPTION]... SRC [SRC]... DEST or rsync [OPTION]... [USER@]HOST::SRC [DEST] - or rsync [OPTION]... SRC [USER@]HOST::DEST + or rsync [OPTION]... SRC [SRC]... [USER@]HOST::DEST or rsync [OPTION]... rsync://[USER@]HOST[:PORT]/SRC [DEST] +SRC on single-colon remote HOST will be expanded by remote shell +SRC on server remote HOST may contain shell wildcards or multiple + sources separated by space as long as they have same top-level Options -v, --verbose increase verbosity + -q, --quiet decrease verbosity -c, --checksum always checksum -a, --archive archive mode -r, --recursive recurse into directories -R, --relative use relative path names - -b, --backup make backups (default ~ extension) + -b, --backup make backups (default ~ suffix) + --suffix=SUFFIX override backup suffix -u, --update update only (don't overwrite newer files) -l, --links preserve soft links -L, --copy-links treat soft links like regular files + --copy-unsafe-links copy links outside the source tree --safe-links ignore links outside the destination tree -H, --hard-links preserve hard links -p, --perms preserve permissions @@ -238,7 +245,7 @@ Options -n, --dry-run show what would have been transferred -W, --whole-file copy whole files, no incremental checks -x, --one-file-system don't cross filesystem boundaries - -B, --block-size=SIZE checksum blocking size + -B, --block-size=SIZE checksum blocking size (default 700) -e, --rsh=COMMAND specify rsh replacement --rsync-path=PATH specify path to rsync on the remote machine -C, --cvs-exclude auto ignore files in the same way CVS does @@ -248,14 +255,14 @@ Options --numeric-ids don't map uid/gid values by user/group name --timeout=TIME set IO timeout in seconds -I, --ignore-times don't exclude files that match length and time + --size-only only use file size when determining if a file should be transferred -T --temp-dir=DIR create temporary files in directory DIR --compare-dest=DIR also compare destination files relative to DIR -z, --compress compress file data --exclude=PATTERN exclude files matching PATTERN - --exclude-from=FILE exclude files listed in FILE + --exclude-from=FILE exclude patterns listed in FILE --include=PATTERN don't exclude files matching PATTERN - --include-from=FILE don't exclude files listed in FILE - --suffix=SUFFIX override backup suffix + --include-from=FILE don't exclude patterns listed in FILE --version print version number --daemon run as a rsync daemon --config=FILE specify alternate rsyncd.conf file @@ -263,6 +270,7 @@ Options --stats give some file transfer stats --progress show progress during transfer --log-format=FORMAT log file transfers using specified format + --password-file=FILE get password from FILE -h, --help show this help screen ) @@ -271,6 +279,8 @@ manpageoptions() rsync uses the GNU long options package. Many of the command line options have two variants, one short and one long. These are shown below, separated by commas. Some options only have a long variant. +The '=' for options that take a parameter is optional; whitespace +can be used instead. startdit() dit(bf(-h, --help)) Print a short help page describing the options @@ -286,10 +296,22 @@ information on what files are being skipped and slightly more information at the end. More than two -v flags should only be used if you are debugging rsync. +dit(bf(-q, --quiet)) This option decreases the amount of information you +are given during the transfer, notably suppressing information messages +from the remote server. This flag is useful when invoking rsync from +cron. + dit(bf(-I, --ignore-times)) Normally rsync will skip any files that are already the same length and have the same time-stamp. This option turns off this behavior. +dit(bf(-I, --size-only)) Normally rsync will skip any files that are +already the same length and have the same time-stamp. With the +--size-only option files will be skipped if they have the same size, +regardless of timestamp. This is useful when starting to use rsync +after using another mirroring system which may not preserve timestamps +exactly. + dit(bf(-c, --checksum)) This forces the sender to checksum all files using a 128-bit MD4 checksum before transfer. The checksum is then explicitly checked on the receiver and any files of the same name @@ -324,6 +346,9 @@ dit(bf(-b, --backup)) With this option preexisting destination files are renamed with a ~ extension as each file is transferred. You can control the backup suffix using the --suffix option. +dit(bf(--suffix=SUFFIX)) This option allows you to override the default +backup suffix used with the -b option. The default is a ~. + 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. @@ -333,7 +358,12 @@ remote system to be the same as the local system. Without this option, all symbolic links are skipped. dit(bf(-L, --copy-links)) This tells rsync to treat symbolic links just -like ordinary files. +like ordinary files. + +dit(bf(--copy-unsafe-links)) This tells rsync to treat symbolic links that +point outside the source tree like ordinary files. Absolute symlinks are +also treated like ordinary files, and so are any symlinks in the source +path itself when --relative is used. dit(bf(--safe-links)) This tells rsync to ignore any symbolic links which point outside the destination tree. All absolute symlinks are @@ -425,16 +455,15 @@ destination. dit(bf(--force)) This options tells rsync to delete directories even if they are not empty. This applies to both the --delete option and to cases where rsync tries to copy a normal file but the destination -contains a directory of the same name. Normally rsync will refuse to -do a recursive directory deletion in such cases, by using --force -the recursive deletion will be done. +contains a directory of the same name. -Use this option with caution! +Since this option was added, deletions were reordered to be done depth-first +so it is hardly ever needed anymore except in very obscure cases. -dit(bf(-B , --block_size BLOCKSIZE)) This controls the block size used in +dit(bf(-B , --block_size=BLOCKSIZE)) This controls the block size used in the rsync algorithm. See the technical report for details. -dit(bf(-e, --rsh COMMAND)) This option allows you to choose an alternative +dit(bf(-e, --rsh=COMMAND)) This option allows you to choose an alternative remote shell program to use for communication between the local and remote copies of rsync. By default, rsync will use rsh, but you may like to instead use ssh because of its high security. @@ -442,10 +471,10 @@ like to instead use ssh because of its high security. You can also choose the remote shell program using the RSYNC_RSH environment variable. -dit(bf(--rsync-path PATH)) Use this to specify the path to the copy of +dit(bf(--rsync-path=PATH)) Use this to specify the path to the copy of rsync on the remote machine. Useful when it's not in your path. -dit(bf(--exclude pattern)) This option allows you to selectively exclude +dit(bf(--exclude=PATTERN)) This option allows you to selectively exclude certain files from the list of files to be transferred. This is most useful in combination with a recursive transfer. @@ -455,18 +484,19 @@ to build up the list of files to exclude. See the section on exclude patterns for information on the syntax of this option. -dit(bf(--exclude-from FILE)) This option is similar to the --exclude +dit(bf(--exclude-from=FILE)) This option is similar to the --exclude option, but instead it adds all filenames listed in the file FILE to -the exclude list. +the exclude list. Blank lines in FILE and lines starting with ';' or '#' +are ignored. -dit(bf(--include pattern)) This option tells rsync to not exclude the +dit(bf(--include=PATTERN)) This option tells rsync to not exclude the specified pattern of filenames. This is useful as it allows you to build up quite complex exclude/include rules. See the section of exclude patterns for information on the syntax of this option. -dit(bf(--include-from FILE)) This specifies a list of include patterns +dit(bf(--include-from=FILE)) This specifies a list of include patterns from a file. dit(bf(-C, --cvs-exclude)) This is a useful shorthand for excluding a @@ -486,10 +516,7 @@ files listed in the CVSIGNORE environment variable (space delimited). Finally in each directory any files listed in the .cvsignore file in that directory are added to the list. -dit(bf(--suffix SUFFIX)) This option allows you to override the default -backup suffix used with the -b option. The default is a ~. - -dit(bf(--csum-length LENGTH)) By default the primary checksum used in +dit(bf(--csum-length=LENGTH)) By default the primary checksum used in rsync is a very strong 16 byte MD4 checksum. In most cases you will find that a truncated version of this checksum is quite efficient, and this will decrease the size of the checksum data sent over the link, @@ -508,12 +535,12 @@ checksum length by default, using a 16 byte file checksum to determine if a 2nd pass is required with a longer block checksum. Only use this option if you have read the source code and know what you are doing. -dit(bf(-T, --temp-dir DIR)) This option instructs rsync to use DIR as a +dit(bf(-T, --temp-dir=DIR)) This option instructs rsync to use DIR as a 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 as an +dit(bf(--compare-dest=DIR)) This option instructs rsync to use DIR as an additional directory to compare destination files against when doing transfers. This is useful for doing transfers to a new destination while leaving existing files intact, and then doing a flash-cutover when all @@ -560,11 +587,11 @@ config file (/etc/rsyncd.conf) on each connect made by a client and respond to requests accordingly. See the rsyncd.conf(5) man page for more details. -dit(bf(--config FILE)) This specifies an alternate config file than +dit(bf(--config=FILE)) This specifies an alternate config file than the default /etc/rsyncd.conf. This is only relevant when --daemon is specified. -dit(bf(--port PORT)) This specifies an alternate TCP port number to use +dit(bf(--port=PORT)) This specifies an alternate TCP port number to use rather than the default port 873. dit(bf(--log-format=FORMAT)) This allows you to specify exactly what the @@ -574,13 +601,18 @@ rsyncd.conf. dit(bf(--stats)) This tells rsync to print a verbose set of statistics on the file transfer, allowing you to tell how effective the rsync -algorithm is for your data. This option only works in conjunction with -the -v (verbose) option. +algorithm is for your data. dit(bf(--progress)) This option tells rsync to print information showing the progress of the transfer. This gives a bored user something to watch. +dit(bf(--password-file)) This option allows you to provide a password +in a file for accessing a remote rsync server. Note that this option +is only useful when accessing a rsync server using the built in +transport, not when using a remote shell as the transport. The file +must not be world readable. + enddit() manpagesection(EXCLUDE PATTERNS) @@ -609,14 +641,15 @@ itemize( directory, not a file, link or device. it() if the pattern contains a wildcard character from the set - *?[ then regular expression matching is applied using the - normal shell filename matching rules. Otherwise a simple string - match is used. + *?[ then expression matching is applied using the shell filename + matching rules. Otherwise a simple string match is used. it() if the pattern contains a / (not counting a trailing /) then it is matched against the full filename, including any leading directory. If the pattern doesn't contain a / then it is matched - only against the final component of the filename. + only against the final component of the filename. Furthermore, if + the pattern includes a double asterisk "**" then all wildcards in + the pattern will match slashes, otherwise they will stop at slashes. it() if the pattern starts with "+ " (a plus followed by a space) then it is always considered an include pattern, even if specified as @@ -639,6 +672,10 @@ itemize( it() --exclude "*.o" would exclude all filenames matching *.o it() --exclude "/foo" would exclude a file in the base directory called foo it() --exclude "foo/" would exclude any directory called foo + it() --exclude "/foo/*/bar" would exclude any file called bar two + levels below a base directory called foo + it() --exclude "/foo/**/bar" would exclude any file called bar two + or more levels below a base directory called foo it() --include "*/" --include "*.c" --exclude "*" would include all directories and C source files it() --include "foo/" --include "foo/bar.c" --exclude "*" would include