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 ~
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
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
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
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
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
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/
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 <tridge@samba.org> and Paul
-Mackerras.
-
-rsync is now maintained by Martin Pool <mbp@samba.org>.
+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.
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff