mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(24 Mar 2004)()()
+manpage(rsync)(1)(29 Apr 2004)()()
manpagename(rsync)(faster, flexible replacement for rcp)
manpagesynopsis()
already the same size and have the same modification time-stamp.
This option turns off this "quick check" behavior.
-dit(bf(--size-only)) Normally rsync will skip any files that are
+dit(bf(--size-only)) Normally rsync will not transfer any files that are
already the same size and have the same modification time-stamp. With the
---size-only option files will be skipped if they have the same size,
+--size-only option, files will not be transferred 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.
a 128-bit MD4 checksum before transfer. The checksum is then
explicitly checked on the receiver and any files of the same name
which already exist and have the same checksum and size on the
-receiver are skipped. This option can be quite slow.
+receiver are not transferred. This option can be quite slow.
dit(bf(-a, --archive)) This is equivalent to -rlptgoD. It is a quick
way of saying you want recursion and want to preserve almost
destination file already exists and has a date later than the source
file.
+In the currently implementation, a difference of file format 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
+regardless of the timestamps. This might change in the future (feel
+free to comment on this on the mailing list if you have an opinion).
+
dit(bf(-l, --links)) When symlinks are encountered, recreate the
symlink on the destination.
The exclude list is initialized to:
-quote(RCS/ SCCS/ CVS/ .svn/ CVS.adm RCSLOG cvslog.* tags TAGS .make.state
-.nse_depinfo *~ #* .#* ,* *.old *.bak *.BAK *.orig *.rej .del-*
-*.a *.o *.obj *.so *.Z *.elc *.ln core)
+quote(RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state
+.nse_depinfo *~ #* .#* ,* _$* *$ *.old *.bak *.BAK *.orig *.rej
+.del-* *.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln core .svn/)
then files listed in a $HOME/.cvsignore are added to the list and any
-files listed in the CVSIGNORE environment variable (space delimited).
+files listed in the CVSIGNORE environment variable (all cvsignore names
+are delimited by whitespace).
Finally, any file is ignored if it is in the same directory as a
-.cvsignore file and matches one of the patterns listed therein. See
-the bf(cvs(1)) manual for more information.
+.cvsignore file and matches one of the patterns listed therein.
+See the bf(cvs(1)) manual for more information.
dit(bf(--exclude=PATTERN)) This option allows you to selectively exclude
certain files from the list of files to be transferred. This is most
dit(bf(-0, --from0)) This tells rsync that the filenames it reads from a
file are terminated by a null ('\0') character, not a NL, CR, or CR+LF.
This affects --exclude-from, --include-from, and --files-from.
+It does not affect --cvs-exclude (since all names read from a .cvsignore
+file are split on whitespace).
dit(bf(-T, --temp-dir=DIR)) This option instructs rsync to use DIR as a
scratch directory when creating temporary copies of the files
linked.
Like bf(--compare-dest) if DIR is a relative path, it is relative
to the destination directory (which changes in a recursive transfer).
+An example:
+
+verb(
+ rsync -av --link-dest=$PWD/prior_dir host:src_dir/ new_dir/
+)
dit(bf(-z, --compress)) With this option, rsync compresses any data from
the files that it sends to the destination machine. This
This root governs where patterns that start with a / match (see below).
Because the matching is relative to the transfer-root, changing the
-trailing slash on the source path or changing your use of the --relative
+trailing slash on a 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.
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
every subcomponent of
every path is visited from the top down, so include/exclude patterns get
applied recursively to each subcomponent.
+The exclude patterns actually short-circuit the directory traversal stage
+when rsync finds the files to send. If a pattern excludes a particular
+parent directory, it can render a deeper include pattern ineffectual
+because rsync did not descend through that excluded section of the
+hierarchy.
Note also that the --include and --exclude options take one pattern
each. To add multiple patterns use the --include-from and
it() if the pattern starts with "+ " (a plus followed by a space)
then it is always considered an include pattern, even if specified as
- part of an exclude option. The "+ " part is discarded before matching.
+ part of an exclude option. The prefix is discarded before matching.
it() if the pattern starts with "- " (a minus followed by a space)
then it is always considered an exclude pattern, even if specified as
- part of an include option. The "- " part is discarded before matching.
+ part of an include option. The prefix is discarded before matching.
it() if the pattern is a single exclamation mark ! then the current
include/exclude list is reset, removing all previously defined patterns.
The +/- rules are most useful in a list that was read from a file, allowing
you to have a single exclude list that contains both include and exclude
-options.
+options in the proper order.
+
+Remember that the matching occurs at every step in the traversal of the
+directory hierarchy, so you must be sure that all the parent directories of
+the files you want to include are not excluded. This is particularly
+important when using a trailing '*' rule. For instance, this won't work:
-If you end an exclude list with --exclude '*', note that since the
-algorithm is applied recursively that unless you explicitly include
-parent directories of files you want to include then the algorithm
-will stop at the parent directories and never see the files below
-them. To include all directories, use --include '*/' before the
---exclude '*'.
+verb(
+ + /some/path/this-file-will-not-be-found
+ + /file-is-included
+ - *
+)
+
+This fails because the parent directory "some" is excluded by the '*' rule,
+so rsync never visits any of the files in the "some" or "some/path"
+directories. One solution is to ask for all directories in the hierarchy
+to be included by using a single rule: --include='*/' (put it somewhere
+before the --excludde='*' rule). Another solution is to add specific
+include rules for all the parent dirs that need to be visited. For
+instance, this set of rules works fine:
+
+verb(
+ + /some/
+ + /some/path/
+ + /some/path/this-file-is-found
+ + /file-also-included
+ - *
+)
-Here are some exclude/include examples:
+Here are some examples of exclude/include matching:
itemize(
it() --exclude "*.o" would exclude all filenames matching *.o
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff