X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/b5accabaa7100b85c2da6b5e7fe4f267fe79aafa..be92ac6c36086f0cf04c85ec7021266b4be20b04:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 1c3ddefa..ee3474ee 100644 --- a/rsync.yo +++ b/rsync.yo @@ -1,5 +1,5 @@ mailto(rsync-bugs@samba.org) -manpage(rsync)(1)(1 Jan 2004)()() +manpage(rsync)(1)(24 Mar 2004)()() manpagename(rsync)(faster, flexible replacement for rcp) manpagesynopsis() @@ -61,11 +61,11 @@ itemize( it() for copying from a remote rsync server to the local machine. This is invoked when the source path contains a :: - separator or a rsync:// URL. + separator or an rsync:// URL. it() for copying from the local machine to a remote rsync server. This is invoked when the destination path contains a :: - separator or a rsync:// URL. + separator or an rsync:// URL. it() for copying from a remote machine using a remote shell program as the transport, using rsync server on the remote @@ -170,7 +170,7 @@ that: itemize( it() you use a double colon :: instead of a single colon to - separate the hostname from the path or a rsync:// URL. + separate the hostname from the path or an rsync:// URL. it() the remote server may print a message of the day when you connect. @@ -290,9 +290,9 @@ verb( --suffix=SUFFIX backup suffix (default ~ w/o --backup-dir) -u, --update update only (don't overwrite newer files) -l, --links copy symlinks as symlinks - -L, --copy-links copy the referent of symlinks - --copy-unsafe-links copy links outside the source tree - --safe-links ignore links outside the destination tree + -L, --copy-links copy the referent of all symlinks + --copy-unsafe-links copy the referent of "unsafe" symlinks + --safe-links ignore "unsafe" symlinks -H, --hard-links preserve hard links -p, --perms preserve permissions -o, --owner preserve owner (root only) @@ -334,7 +334,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 - --daemon run as a rsync daemon + --daemon run as an rsync daemon --no-detach do not detach from the parent --address=ADDRESS bind to the specified address --config=FILE specify alternate rsyncd.conf file @@ -458,6 +458,8 @@ very useful for incremental backups. You can additionally specify a backup suffix using the --suffix option (otherwise the files backed up in the specified directory will keep their original filenames). +If DIR is a relative path, it is relative to the destination directory +(which changes in a recursive transfer). 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 ~ @@ -471,15 +473,15 @@ dit(bf(-l, --links)) When symlinks are encountered, recreate the symlink on the destination. dit(bf(-L, --copy-links)) When symlinks are encountered, the file that -they point to is copied, rather than the symlink. +they point to (the referent) is copied, rather than the symlink. dit(bf(--copy-unsafe-links)) This tells rsync to copy the referent of -symbolic links that point outside the source tree. Absolute symlinks +symbolic links that point outside the copied tree. 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 +which point outside the copied tree. All absolute symlinks are also ignored. Using this option in conjunction with --relative may give unexpected results. @@ -512,15 +514,16 @@ other files (including updated files) retain their existing permissions dit(bf(-o, --owner)) This option causes rsync to set the owner of the 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. +only the super-user can set file ownership. By default, the preservation +is done by name, but may fall back to using the ID number in some +circumstances. See the --numeric-ids option for a full discussion. 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 program is not running as the super-user, only groups that the -receiver is a member of will be preserved (by group name, not group ID -number). +receiver is a member of will be preserved. By default, the preservation +is done by name, but may fall back to using the ID number in some +circumstances. See the --numeric-ids option for a full discussion. dit(bf(-D, --devices)) This option causes rsync to transfer character and block device information to the remote system to recreate these @@ -651,8 +654,7 @@ useful in combination with a recursive transfer. You may use as many --exclude options on the command line as you like to build up the list of files to exclude. -See the EXCLUDE PATTERNS section for information on the syntax of -this option. +See the EXCLUDE PATTERNS section for detailed information on this option. dit(bf(--exclude-from=FILE)) This option is similar to the --exclude option, but instead it adds all exclude patterns listed in the file @@ -664,8 +666,7 @@ 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 EXCLUDE PATTERNS section for information on the syntax of -this option. +See the EXCLUDE PATTERNS section for detailed information on this option. dit(bf(--include-from=FILE)) This specifies a list of include patterns from a file. @@ -728,14 +729,14 @@ 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. +to the destination directory (which changes in a recursive transfer). 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. +to the destination directory (which changes in a recursive transfer). dit(bf(-z, --compress)) With this option, rsync compresses any data from the files that it sends to the destination machine. This @@ -756,9 +757,12 @@ what ownership to give files. The special uid 0 and the special group 0 are never mapped via user/group names even if the --numeric-ids option is not specified. -If the source system is a daemon using chroot, or if a user or group -name does not exist on the destination system, then the numeric ID -from the source system is used instead. +If a user or group has no name on the source system or it has no match +on the destination system, then the numeric ID +from the source system is used instead. See also the comments on the +"use chroot" setting in the rsyncd.conf manpage for information on how +the chroot setting affects rsync's ability to look up the names of the +users and groups and what you can do about it. 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 @@ -857,7 +861,7 @@ option to make it easier. 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 +is only useful when accessing an rsync server using the built in transport, not when using a remote shell as the transport. The file must not be world readable. It should contain just the password as a single line. @@ -885,7 +889,7 @@ manpagesection(EXCLUDE PATTERNS) The exclude and include patterns specified to rsync allow for flexible selection of which files to transfer and which files to skip. -rsync builds an ordered list of include/exclude options as specified on +Rsync builds an ordered list of include/exclude options as specified on the command line. Rsync checks each file and directory name against each exclude/include pattern in turn. The first matching pattern is acted on. If it is an exclude pattern, then that file is @@ -893,15 +897,51 @@ skipped. If it is an include pattern then that filename is not skipped. If no matching include/exclude pattern is found then the filename is not skipped. -The filenames matched against the exclude/include patterns -are relative to the destination directory, or "top -directory", so patterns should not include the path elements -of the source or destination directories. The only way in -which a pattern will match the absolute path of a file or -directory is if the source path is the root directory. +The filenames matched against the exclude/include patterns are relative +to the "root of the transfer". If you think of the transfer as a +subtree of names that are being sent from sender to receiver, the root +is where the tree starts to be duplicated in the destination directory. +This root governs where patterns that start with a / match (see below). -Note that when used with -r (which is implied by -a), every subcomponent of -every path is visited from top down, so include/exclude patterns get +Because the matching is relative to the transfer-root, changing the +trailing slash on the source path or changing your use of the --relative +option affects the path you need to use in your matching (in addition to +changing how much of the file tree is duplicated on the destination +system). The following examples demonstrate this. + +Let's say that we want to match a source filename that has an absolute +path of "/home/me/foo/bar", here is how the various command choices can +differ: + +verb( + Example cmd: rsync -a /home/me /dest + Source root: /home ("me" is part of transfer) + +/- pattern: /me/foo/bar + Target file: /dest/me/foo/bar + + Example cmd: rsync -a /home/me/ /dest + Source root: /home/me (due to trailing /) + +/- pattern: /foo/bar (note missing "me") + Target file: /dest/foo/bar + + Example cmd: rsync -a --relative /home/me/ /dest + Source root: /home/me + +/- pattern: /home/me/foo/bar (note full path) + Target file: /dest/home/me/foo/bar + + Example cmd: cd /home; rsync -a --relative me/foo/ /dest + Source root: ./me/foo (source is not absolute) + +/- pattern: /me/foo/bar (only uses specified path) + Target file: /dest/me/foo/bar +) + +The easiest way to see what name you should include/exclude is to just +look at the output when using --verbose and put a / in front of the name +(use the --dry-run option if you're not yet ready to copy any files). + +Note that, when using the --recursive (-r) option (which is implied by -a), +every subcomponent of +every path is visited from the top down, so include/exclude patterns get applied recursively to each subcomponent. Note also that the --include and --exclude options take one pattern @@ -916,16 +956,15 @@ itemize( start of the filename, otherwise it is matched against the end of the filename. This is the equivalent of a leading ^ in regular expressions. - Thus "/foo" would match a file called "foo" at the top of the - transferred tree. + Thus "/foo" would match a file called "foo" at the transfer-root + (see above for how this is different from the filesystem-root). 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. it() if the pattern ends with a / then it will only match a - directory, not a file, link or device. + 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 @@ -968,12 +1007,12 @@ Here are some exclude/include examples: itemize( it() --exclude "*.o" would exclude all filenames matching *.o - it() --exclude "/foo" would exclude a file called foo in the top directory + it() --exclude "/foo" would exclude a file called foo in the transfer-root directory it() --exclude "foo/" would exclude any directory called foo it() --exclude "/foo/*/bar" would exclude any file called bar two - levels below a directory called foo in the top directory + levels below a directory called foo in the transfer-root directory it() --exclude "/foo/**/bar" would exclude any file called bar two - or more levels below a directory called foo in the top directory + or more levels below a directory called foo in the transfer-root directory it() --include "*/" --include "*.c" --exclude "*" would include all directories and C source files it() --include "foo/" --include "foo/bar.c" --exclude "*" would include @@ -1027,11 +1066,11 @@ once, instead of sending the same data to every host individually. Example: verb( -$ rsync --write-batch=pfx -a /source/dir/ /adest/dir/ -$ rcp pfx.rsync_* remote: -$ ssh remote rsync --read-batch=pfx -a /bdest/dir/ -# or alternatively -$ ssh remote ./pfx.rsync_argvs /bdest/dir/ + $ rsync --write-batch=pfx -a /source/dir/ /adest/dir/ + $ rcp pfx.rsync_* remote: + $ ssh remote rsync --read-batch=pfx -a /bdest/dir/ + # or alternatively + $ ssh remote ./pfx.rsync_argvs /bdest/dir/ ) In this example, rsync is used to update /adest/dir/ with /source/dir/ @@ -1160,12 +1199,12 @@ redirect your rsync client to use a web proxy when connecting to a rsync daemon. You should set RSYNC_PROXY to a hostname:port pair. dit(bf(RSYNC_PASSWORD)) Setting RSYNC_PASSWORD to the required -password allows you to run authenticated rsync connections to a rsync +password allows you to run authenticated rsync connections to an rsync daemon without user intervention. Note that this does not supply a 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 username sent to an rsync server. dit(bf(HOME)) The HOME environment variable is used to find the user's default .cvsignore file.