mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(25 Jan 2002)()()
+manpage(rsync)(1)(26 Jan 2003)()()
manpagename(rsync)(faster, flexible replacement for rcp)
manpagesynopsis()
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 *.c foo:src/)
-this would transfer all files matching the pattern *.c from the
+This would transfer all files matching the pattern *.c from the
current directory to the directory src on the machine foo. If any of
the files already exist on the remote system then the rsync
remote-update protocol is used to update the file by sending only the
quote(rsync -avz foo:src/bar /data/tmp)
-this would recursively transfer all files from the directory src/bar on the
+This would recursively transfer all files from the directory src/bar on the
machine foo into the /data/tmp/bar directory on the local machine. The
files are transferred in "archive" mode, which ensures that symbolic
links, devices, attributes, permissions, ownerships etc are preserved
quote(rsync -avz foo:src/bar/ /data/tmp)
-a trailing slash on the source changes this behavior to transfer
-all files from the directory src/bar on the machine foo into the
-/data/tmp/. A trailing / on a source name means "copy the
-contents of this directory". Without a trailing slash it means "copy
-the directory". This difference becomes particularly important when
-using the --delete option.
+A trailing slash on the source changes this behavior to avoid creating an
+additional directory level at the destination. You can think of a trailing
+/ on a source as meaning "copy the contents of this directory" as opposed
+to "copy the directory by name", but in both cases the attributes of the
+containing directory are transferred to the containing directory on the
+destination. In other words, each of the following commands copies the
+files in the same way, including their setting of the attributes of
+/dest/foo:
+
+quote(rsync -avz /src/foo /dest)
+quote(rsync -avz /src/foo/ /dest/foo)
You can also use rsync in local-only mode, where both the source and
destination don't have a ':' in the name. In this case it behaves like
quote(rsync somehost.mydomain.com::)
-this would list all the anonymous rsync modules available on the host
+This would list all the anonymous rsync modules available on the host
somehost.mydomain.com. (See the following section for more details.)
NOTE: rsync's argument parsing expects the trailing ".", so make sure
that it's there. If you want to use a rsyncd.conf(5)-style
configuration file other than the default, you can added a
---config-file option to the em(command):
+--config option to the em(command):
-quote(rsync --server --daemon --config-file=em(file) .)
+quote(rsync --server --daemon --config=em(file) .)
manpagesection(EXAMPLES)
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
- -b, --backup make backups (default ~ suffix)
+ --no-relative turn off --relative
+ --no-implied-dirs don't send implied dirs with -R
+ -b, --backup make backups (see --suffix)
--backup-dir make backups into this directory
- --suffix=SUFFIX define backup suffix
+ --suffix=SUFFIX define 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
-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
the timestamps as being equal if they are within the value of
modify_window. This is normally zero, but you may find it useful to
set this to a larger value in some situations. In particular, when
-transferring to/from FAT filesystems which cannot represent times with
-a 1 second resolution this option is useful.
+transferring to Windows FAT filesystems which cannot represent times
+with a 1 second resolution --modify-window=1 is useful.
dit(bf(-c, --checksum)) This forces the sender to checksum all files using
a 128-bit MD4 checksum before transfer. The checksum is then
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.
-
-dit(bf(-b, --backup)) With this option preexisting destination files are
-renamed with a ~ extension as each file is transferred. You can
-control the backup suffix using the --suffix option.
+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 as each file is transferred or deleted. You can control where the
+backup file goes and what (if any) suffix gets appended using the
+--backup-dir and --suffix options.
dit(bf(--backup-dir=DIR)) In combination with the --backup option, this
tells rsync to store all backups in the specified directory. This is
will keep their original filenames).
dit(bf(--suffix=SUFFIX)) This option allows you to override the default
-backup suffix used with the -b option. The default is a ~.
-If --backup-dir and --suffix are both specified,
-the SUFFIX is appended to the filename even in the backup directory.
+backup suffix used with the --backup (-b) option. The default suffix is a ~
+if no --backup-dir was specified, otherwise it is an empty string.
dit(bf(-u, --update)) This forces rsync to skip any files for which the
destination file already exists and has a date later than the source
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
dit(bf(--progress)) This option tells rsync to print information
showing the progress of the transfer. This gives a bored user
something to watch.
-
-This option is normally combined with -v. Using this option without
-the -v option will produce weird results on your display.
+Implies --verbose without incrementing verbosity.
dit(bf(-P)) The -P option is equivalent to --partial --progress. I
found myself typing that combination quite often so I created an
selection of which files to transfer and which files to skip.
rsync builds an ordered list of include/exclude options as specified on
-the command line. When a filename is encountered, rsync checks the
+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 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.
+
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 top 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.
*?[ then expression matching is applied using the shell filename
matching rules. Otherwise a simple string match is used.
- it() if the pattern includes a double asterisk "**" then all wildcards in
- the pattern will match slashes, otherwise they will stop at slashes.
+ it() the double asterisk pattern "**" will match slashes while a
+ single asterisk pattern "*" 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
- actually be any portion of a path.
+ 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 below the starting directory.
it() if the pattern starts with "+ " (a plus followed by a space)
then it is always considered an include pattern, even if specified as
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
itemize(
it() --exclude "*.o" would exclude all filenames matching *.o
- it() --exclude "/foo" would exclude a file in the base directory called foo
+ it() --exclude "/foo" would exclude a file called foo in the top directory
it() --exclude "foo/" would exclude any directory called foo
it() --exclude "/foo/*/bar" would exclude any file called bar two
- levels below a base directory called foo
+ levels below a directory called foo in the top directory
it() --exclude "/foo/**/bar" would exclude any file called bar two
- or more levels below a base directory called foo
+ or more levels below a directory called foo in the top 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/
+$ rsync --write-batch=pfx -a /source/dir/ /adest/dir/
$ rcp pfx.rsync_* remote:
-$ rsh remote rsync --read_batch=pfx -a /bdest/dir/
+$ rsh remote rsync --read-batch=pfx -a /bdest/dir/
# or alternatively
$ rsh remote ./pfx.rsync_argvs /bdest/dir/
)
manpagesection(EXIT VALUES)
startdit()
-dit(bf(RERR_SYNTAX 1)) Syntax or usage error
-dit(bf(RERR_PROTOCOL 2)) Protocol incompatibility
-dit(bf(RERR_FILESELECT 3)) Errors selecting input/output files, dirs
+dit(bf(1)) Syntax or usage error
+dit(bf(2)) Protocol incompatibility
+dit(bf(3)) Errors selecting input/output files, dirs
-dit(bf(RERR_UNSUPPORTED 4)) Requested action not supported: an attempt
+dit(bf(4)) Requested action not supported: an attempt
was made to manipulate 64-bit files on a platform that cannot support
them; or an option was speciifed that is supported by the client and
not by the server.
-dit(bf(RERR_SOCKETIO 10)) Error in socket IO
-dit(bf(RERR_FILEIO 11)) Error in file IO
-dit(bf(RERR_STREAMIO 12)) Error in rsync protocol data stream
-dit(bf(RERR_MESSAGEIO 13)) Errors with program diagnostics
-dit(bf(RERR_IPC 14)) Error in IPC code
-dit(bf(RERR_SIGNAL 20)) Received SIGUSR1 or SIGINT
-dit(bf(RERR_WAITCHILD 21)) Some error returned by waitpid()
-dit(bf(RERR_MALLOC 22)) Error allocating core memory buffers
-dit(bf(RERR_TIMEOUT 30)) Timeout in data send/receive
+dit(bf(5)) Error starting client-server protocol
+dit(bf(10)) Error in socket IO
+dit(bf(11)) Error in file IO
+dit(bf(12)) Error in rsync protocol data stream
+dit(bf(13)) Errors with program diagnostics
+dit(bf(14)) Error in IPC code
+dit(bf(20)) Received SIGUSR1 or SIGINT
+dit(bf(21)) Some error returned by waitpid()
+dit(bf(22)) Error allocating core memory buffers
+dit(bf(23)) Partial transfer
+dit(bf(30)) Timeout in data send/receive
enddit()
manpagesection(ENVIRONMENT VARIABLES)
times are transferred as unix time_t values
+When transferring to FAT filesystmes rsync may resync
+unmodified files.
+See the comments on the --modify-window option.
+
file permissions, devices etc are transferred as native numerical
values
see also the comments on the --delete option
-Please report bugs! The rsync bug tracking system is online at
-url(http://rsync.samba.org/rsync/)(http://rsync.samba.org/rsync/)
-
-manpagesection(VERSION)
-This man page is current for version 2.0 of rsync
+Please report bugs! See the website at
+url(http://rsync.samba.org/)(http://rsync.samba.org/)
manpagesection(CREDITS)
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff