X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/7af4227ac2deb5f677b52706b0494100b3f2380e..2b284ee33d97c4414c49c45720a3566a58a93a18:/rsync.yo diff --git a/rsync.yo b/rsync.yo index acc3e9c0..ac472f50 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() @@ -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 ~ @@ -727,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 @@ -887,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 @@ -895,15 +897,60 @@ 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 two source files, one with an absolute +path of "/home/me/foo/bar", and one with a path of "/home/you/bar/baz". +Here is how the various command choices differ for a 2-source transfer: + +verb( + Example cmd: rsync -a /home/me /home/you /dest + Source root: /home (me & you are part of transfer) + +/- pattern: /me/foo/bar + +/- pattern: /you/bar/baz + Target file: /dest/me/foo/bar + Target file: /dest/you/bar/baz + + Example cmd: rsync -a /home/me/ /home/you/ /dest + Source root: /home/me (due to trailing /) + Source root: /home/you (ditto) + +/- pattern: /foo/bar (note missing "me") + +/- pattern: /bar/baz (note missing "you") + Target file: /dest/foo/bar + Target file: /dest/bar/baz + + Example cmd: rsync -a --relative /home/me/ /home/you /dest + Source root: / + +/- pattern: /home/me/foo/bar (note full path) + +/- pattern: /home/you/bar/baz (ditto) + Target file: /dest/home/me/foo/bar + Target file: /dest/home/you/bar/baz + + Example cmd: cd /home; rsync -a --relative me/foo you/ /dest + Source root: /home + +/- pattern: /me/foo/bar (starts at specified path) + +/- pattern: /you/bar/baz (ditto) + Target file: /dest/me/foo/bar + Target file: /dest/you/bar/baz +) + +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 @@ -918,16 +965,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 @@ -970,12 +1016,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 @@ -1029,11 +1075,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/ @@ -1168,6 +1214,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 an rsync server. +If neither is set, the username defaults to "nobody". dit(bf(HOME)) The HOME environment variable is used to find the user's default .cvsignore file. @@ -1224,19 +1271,13 @@ Thanks to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell and David Bell for helpful suggestions, patches and testing of rsync. I've probably missed some people, my apologies if I have. -Especial thanks also to: David Dykstra, Jos Backus, Sebastian Krahmer. - +Especial thanks also to: David Dykstra, Jos Backus, Sebastian Krahmer, +Martin Pool, Wayne Davison. manpageauthor() -rsync was written by Andrew Tridgell and Paul -Mackerras. - -rsync is now maintained by Martin Pool . +rsync was originally written by Andrew Tridgell and Paul Mackerras. +Many people have later contributed to it. Mailing lists for support and development are available at url(http://lists.samba.org)(lists.samba.org) - -If you suspect you have found a security vulnerability in rsync, -please send it directly to Martin Pool and Andrew Tridgell. For other -enquiries, please use the mailing list.