exists.
The rsync remote-update protocol allows rsync to transfer just the
-differences between two sets of files across the network link, using
+differences between two sets of files across the network connection, using
an efficient checksum-search algorithm described in the technical
report that accompanies this package.
quote(rsync -Cavz . arvidsjaur:backup)
-each night over a PPP link to a duplicate directory on my machine
+each night over a PPP connection to a duplicate directory on my machine
"arvidsjaur".
To synchronize my samba source trees I use the following Makefile
sync: get put)
this allows me to sync with a CVS directory at the other end of the
-link. I then do cvs operations on the remote machine, which saves a
+connection. I then do cvs operations on the remote machine, which saves a
lot of time as the remote cvs protocol isn't very efficient.
I mirror a directory between my "old" and "new" ftp sites with the
-a, --archive archive mode, equivalent to -rlptgoD
-r, --recursive recurse into directories
-R, --relative use relative path names
+ --no-relative turn off --relative
+ --no-implied-dirs don't send implied dirs with -R
-b, --backup make backups (default ~ suffix)
--backup-dir make backups into this directory
--suffix=SUFFIX define backup suffix
-B, --block-size=SIZE checksum blocking size (default 700)
-e, --rsh=COMMAND specify the remote shell to use
--rsync-path=PATH specify path to rsync on the remote machine
- -C, --cvs-exclude auto ignore files in the same way CVS does
--existing only update files that already exist
--ignore-existing ignore files that already exist on the receiving side
--delete delete files that don't exist on the sending side
--link-dest=DIR create hardlinks to DIR for unchanged files
-P equivalent to --partial --progress
-z, --compress compress file data
+ -C, --cvs-exclude auto ignore files in the same way CVS does
--exclude=PATTERN exclude files matching PATTERN
--exclude-from=FILE exclude patterns listed in FILE
--include=PATTERN don't exclude files matching PATTERN
--include-from=FILE don't exclude patterns listed in FILE
+ --files-from=FILE read FILE for list of source-file names
+ -0 --from0 file names we read are separated by nulls, not newlines
--version print version number
--daemon run as a rsync daemon
--no-detach do not detach from the parent
verb(rsync -R foo/bar/foo.c remote:/tmp/)
then a file called /tmp/foo/bar/foo.c would be created on the remote
-machine. The full path name is preserved.
+machine -- the full path name is preserved.
+
+dit(bf(--no-relative)) Turn off the --relative option. This is only
+needed if you want to use --files-from without its implied --relative
+file processing.
+
+dit(bf(--no-implied-dirs)) When combined with the --relative option, the
+implied directories in each path are not explicitly duplicated as part
+of the transfer. This makes the transfer more optimal and also allows
+the two sides to have non-matching symlinks in the implied part of the
+path. For instance, if you transfer the file "/path/foo/file" with -R,
+the default is for rsync to ensure that "/path" and "/path/foo" on the
+destination exactly match the directories/symlinks of the source. Using
+the --no-implied-dirs option would omit both of these implied dirs,
+which means that if "/path" was a real directory on one machine and a
+symlink of the other machine, rsync would not try to change this.
dit(bf(-b, --backup)) With this option preexisting destination files are
renamed with a ~ extension as each file is transferred. You can
dit(bf(--no-whole-file)) Turn off --whole-file, for use when it is the
default.
-dit(bf(-p, --perms)) This option causes rsync to update the remote
-permissions to be the same as the local permissions.
+dit(bf(-p, --perms)) This option causes rsync to set the destination
+permissions to be the same as the source permissions.
+
+Without this option, each new file gets its permissions set based on the
+source file's permissions and the umask at the receiving end, while all
+other files (including updated files) retain their existing permissions
+(which is the same behavior as other file-copy utilities, such as cp).
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,
that this is the full path to the binary, not just the directory that
the binary is in.
+dit(bf(-C, --cvs-exclude)) This is a useful shorthand for excluding a
+broad range of files that you often don't want to transfer between
+systems. It uses the same algorithm that CVS uses to determine if
+a file should be ignored.
+
+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)
+
+then files listed in a $HOME/.cvsignore are added to the list and any
+files listed in the CVSIGNORE environment variable (space delimited).
+
+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.
+
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.
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 section on exclude patterns for information on the syntax of
+See the EXCLUDE PATTERNS section for information on the syntax of
this option.
dit(bf(--exclude-from=FILE)) This option is similar to the --exclude
';' or '#' are ignored.
If em(FILE) is bf(-) the list will be read from standard input.
-
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
+See the EXCLUDE PATTERNS section for information on the syntax of
this option.
dit(bf(--include-from=FILE)) This specifies a list of include patterns
from a file.
If em(FILE) is bf(-) the list will be read from standard input.
-
-dit(bf(-C, --cvs-exclude)) This is a useful shorthand for excluding a
-broad range of files that you often don't want to transfer between
-systems. It uses the same algorithm that CVS uses to determine if
-a file should be ignored.
-
-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)
-
-then files listed in a $HOME/.cvsignore are added to the list and any
-files listed in the CVSIGNORE environment variable (space delimited).
-
-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.
-
-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,
-making things faster.
-
-You can choose the number of bytes in the truncated checksum using the
---csum-length option. Any value less than or equal to 16 is valid.
-
-Note that if you use this option then you run the risk of ending up
-with an incorrect target file. The risk with a value of 16 is
-microscopic and can be safely ignored (the universe will probably end
-before it fails) but with smaller values the risk is higher.
-
-Current versions of rsync actually use an adaptive algorithm for the
-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(--files-from=FILE)) Using this option allows you to specify the
+exact list of files to transfer (as read from the specified FILE or "-"
+for stdin). It also tweaks the default behavior of rsync to make
+transferring just the specified files and directories easier. For
+instance, the --relative option is enabled by default when this option
+is used (use --no-relative if you want to turn that off), all
+directories specified in the list are created on the destination (rather
+than being noisily skipped without -r), and the -a (--archive) option's
+behavior does not imply -r (--recursive) -- specify it explicitly, if
+you want it.
+
+The file names that are read from the FILE are all relative to the
+source dir -- any leading slashes are removed and no ".." references are
+allowed to go higher than the source dir. For example, take this
+command:
+
+quote(rsync -a --files-from=/tmp/foo /usr remote:/backup)
+
+If /tmp/foo contains the string "bin" (or even "/bin"), the /usr/bin
+directory will be created as /backup/bin on the remote host (but the
+contents of the /usr/bin dir would not be sent unless you specified -r
+or the names were explicitly listed in /tmp/foo). Also keep in mind
+that the effect of the (enabled by default) --relative option is to
+duplicate only the path info that is read from the file -- it does not
+force the duplication of the source-spec path (/usr in this case).
+
+In addition, the --files-from file can be read from the remote host
+instead of the local host if you specify a "host:" in front of the file
+(the host must match one end of the transfer). As a short-cut, you can
+specify just a prefix of ":" to mean "use the remote end of the
+transfer". For example:
+
+quote(rsync -a --files-from=:/path/file-list src:/ /tmp/copy)
+
+This would copy all the files specified in the /path/file-list file that
+was located on the remote "src" host.
+
+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.
dit(bf(-T, --temp-dir=DIR)) This option instructs rsync to use DIR as a
scratch directory when creating temporary copies of the files
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.
dit(bf(-z, --compress)) With this option, rsync compresses any data from
the files that it sends to the destination machine. This
-option is useful on slow links. The compression method used is the
+option is useful on slow connections. The compression method used is the
same method that gzip uses.
Note this this option typically achieves better compression ratios
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 base directories, so patterns should not
+include the path elements to those base directories. The
+only way in which a pattern will match the absolute path of
+a file or directory is if the base path is the root directory.
+
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
applied recursively to each subcomponent.
The patterns can take several forms. The rules are:
itemize(
+
it() if the pattern starts with a / then it is matched against the
start of the filename, otherwise it is matched against the end of
- the filename. Thus "/foo" would match a file called "foo" at the base of
- the tree. On the other hand, "foo" would match any file called "foo"
+ the filename.
+ This is the equivalent of a leading ^ in regular expressions.
+ Thus "/foo" would match a file called "foo" at the base of the
+ transferred tree.
+ 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.
it() 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 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. Again, remember
- that the algorithm is applied recursively so "full filename" can
+ it() if the pattern contains a / (not counting a trailing /) or a "**"
+ then it is matched against the full filename, including any leading
+ directory. If the pattern doesn't contain a / or a "**", then it is
+ matched only against the final component of the filename. Again,
+ remember that the algorithm is applied recursively so "full filename" can
actually be any portion of a path.
it() if the pattern starts with "+ " (a plus followed by a space)
include/exclude list is reset, removing all previously defined patterns.
)
-The +/- rules are most useful in exclude lists, allowing you to have a
-single exclude list that contains both include and exclude options.
+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.
If you end an exclude list with --exclude '*', note that since the
algorithm is applied recursively that unless you explicitly include
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff