manpagename(rsync)(faster, flexible replacement for rcp)
manpagesynopsis()
+rsync [OPTION]... SRC [SRC]... DEST
+
rsync [OPTION]... SRC [SRC]... [USER@]HOST:DEST
-rsync [OPTION]... [USER@]HOST:SRC [DEST]
+rsync [OPTION]... SRC [SRC]... [USER@]HOST::DEST
-rsync [OPTION]... SRC [SRC]... DEST
+rsync [OPTION]... SRC [SRC]... rsync://[USER@]HOST[:PORT]/DEST
-rsync [OPTION]... [USER@]HOST::SRC [DEST]
+rsync [OPTION]... [USER@]HOST:SRC [DEST]
-rsync [OPTION]... SRC [SRC]... [USER@]HOST::DEST
+rsync [OPTION]... [USER@]HOST::SRC [DEST]
rsync [OPTION]... rsync://[USER@]HOST[:PORT]/SRC [DEST]
-rsync [OPTION]... SRC [SRC]... rsync://[USER@]HOST[:PORT]/DEST
-
manpagedescription()
rsync is a program that behaves in much the same way that rcp does,
You can also specify any remote shell you like, either by using the bf(-e)
command line option, or by setting the RSYNC_RSH environment variable.
-One common substitute is to use ssh, which offers a high degree of
-security.
-
Note that rsync must be installed on both the source and destination
machines.
itemize(
it() you either use a double colon :: instead of a single colon to
separate the hostname from the path, or you use an rsync:// URL.
- it() the first word after the :: is a module name.
+ it() the first word of the "path" is actually a module name.
it() the remote daemon may print a message of the day when you
connect.
it() if you specify no path name on the remote daemon then the
list of accessible paths on the daemon will be shown.
it() if you specify no local destination then a listing of the
specified files on the remote daemon is provided.
+ it() you must not specify the bf(--rsh) (bf(-e)) option.
)
An example that copies all the files in a remote module named "src":
-q, --quiet suppress non-error messages
-c, --checksum skip based on checksum, not mod-time & size
-a, --archive archive mode; same as -rlptgoD (no -H)
+ --no-OPTION turn off an implied OPTION (e.g. --no-D)
-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
+ --no-implied-dirs don't send implied dirs with --relative
-b, --backup make backups (see --suffix & --backup-dir)
--backup-dir=DIR make backups into hierarchy based in DIR
--suffix=SUFFIX backup suffix (default ~ w/o --backup-dir)
-S, --sparse handle sparse files efficiently
-n, --dry-run show what would have been transferred
-W, --whole-file copy files whole (without rsync algorithm)
- --no-whole-file always use incremental rsync algorithm
-x, --one-file-system don't cross filesystem boundaries
-B, --block-size=SIZE force a fixed checksum block-size
-e, --rsh=COMMAND specify the remote shell to use
--address=ADDRESS bind address for outgoing socket to daemon
--port=PORT specify double-colon alternate port number
--blocking-io use blocking I/O for the remote shell
- --no-blocking-io turn off blocking I/O when it is default
--stats give some file-transfer stats
--progress show progress during transfer
-P same as --partial --progress
dit(bf(-a, --archive)) This is equivalent to bf(-rlptgoD). It is a quick
way of saying you want recursion and want to preserve almost
-everything. The only exception to this is if bf(--files-from) was
+everything (with -H being a notable omission).
+The only exception to the above equivalence is when bf(--files-from) is
specified, in which case bf(-r) is not implied.
Note that bf(-a) bf(does not preserve hardlinks), because
finding multiply-linked files is expensive. You must separately
specify bf(-H).
+dit(--no-OPTION) You may turn off one or more implied options by prefixing
+the option name with "no-". Not all options may be prefixed with a "no-":
+only options that are implied by other options (e.g. bf(--no-D),
+bf(--no-perms)) or have different defaults in various circumstances
+(e.g. bf(--no-whole-file), bf(--no-blocking-io), bf(--no-dirs)). You may
+specify either the short or the long option name after the "no-" prefix
+(e.g. bf(--no-R) is the same as bf(--no-relative)).
+
+For example: if you want to use bf(-a) (bf(--archive)) but don't want
+bf(-o) (bf(--owner)), instead of converting bf(-a) into bf(-rlptgD), you
+could specify bf(-a --no-o) (or bf(-a --no-owner)).
+
+The order of the options is important: if you specify bf(--no-r -a), the
+bf(-r) option would end up being turned on, the opposite of bf(-a --no-r).
+Note also that the side-effects of the bf(--files-from) option are NOT
+positional, as it affects the default state of several options and sligntly
+changes the meaning of bf(-a) (see the bf(--files-from) option for more
+details).
+
dit(bf(-r, --recursive)) This tells rsync to copy directories
recursively. See also bf(--dirs) (bf(-d)).
tt( remote:bar/baz.c /tmp/)
)
-dit(bf(--no-relative)) Turn off the bf(--relative) option. This is only
-needed if you want to use bf(--files-from) without its implied bf(--relative)
-file processing.
-
dit(bf(--no-implied-dirs)) When combined with the bf(--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
resend will do a normal bf(--inplace) update to correct the mismatched data.
Only files on the receiving side that are shorter than the corresponding
file on the sending side (as well as new files) are sent.
-Implies bf(--inplace).
+Implies bf(--inplace), but does not conflict with bf(--sparse) (though the
+bf(--sparse) option will be auto-disabled if a resend of the already-existing
+data is required).
dit(bf(-d, --dirs)) Tell the sending side to include any directories that
are encountered. Unlike bf(--recursive), a directory's contents are not copied
unless the directory was specified on the command-line as either "." or a
name with a trailing slash (e.g. "foo/"). Without this option or the
bf(--recursive) option, rsync will skip all directories it encounters (and
-output a message to that effect for each one).
+output a message to that effect for each one). If you specify both
+bf(--dirs) and bf(--recursive), the latter takes precedence.
dit(bf(-l, --links)) When symlinks are encountered, recreate the
symlink on the destination.
"disk" is actually a networked filesystem). This is the default when both
the source and destination are specified as local paths.
-dit(bf(--no-whole-file)) Turn off bf(--whole-file), for use when it is the
-default.
-
dit(bf(-p, --perms)) This option causes rsync to set the destination
permissions to be the same as the source permissions.
instead it will just report the actions it would have taken.
dit(bf(-S, --sparse)) Try to handle sparse files efficiently so they take
-up less space on the destination.
+up less space on the destination. Conflicts with bf(--inplace) because it's
+not possible to overwrite data in a sparse fashion.
NOTE: Don't use this option when the destination is a Solaris "tmpfs"
filesystem. It doesn't seem to handle seeks over null regions
option or mark the rules as only matching on the sending side (see the
include/exclude modifiers in the FILTER RULES section).
-This option has no effect unless directory recursion is enabled.
+Prior to rsync 2.6.7, this option would have no effect unless bf(--recursive)
+was in effect. Beginning with 2.6.7, deletions will also occur when bf(--dirs)
+is specified, but only for directories whose contents are being copied.
This option can be dangerous if used incorrectly! It is a very good idea
to run first using the bf(--dry-run) option (bf(-n)) to see what files would be
dit(bf(--max-size=SIZE)) This tells rsync to avoid transferring any
file that is larger than the specified SIZE. The SIZE value can be
-suffixed with a letter to indicate a size multiplier (K, M, or G) and
+suffixed with a string to indicate a size multiplier, and
may be a fractional value (e.g. "bf(--max-size=1.5m)").
+The suffixes are as follows: "K" (or "k") is a kilobyte (1024),
+"M" (or "m") is a megabyte (1024*1024), and "G" (or "g") is a
+gigabyte (1024*1024*1024).
+If you want the multiplier to be 1000 instead of 1024, suffix the K, G, or
+M with a "T" (or "t") to indicate that a power of 10 is desired.
+Finally, if the suffix ends in either "+1" or "-1", the value will
+be offset by one byte in the indicated direction.
+Examples: --max-size=1.5mt-1 is 1499999 bytes, and --max-size=2g+1 is
+2147483649 bytes.
+
dit(bf(-B, --block-size=BLOCKSIZE)) This forces the block size used in
the rsync algorithm to a fixed value. It is normally selected based on
the size of each file being updated. See the technical report for details.
dit(bf(-F)) The bf(-F) option is a shorthand for adding two bf(--filter) rules to
your command. The first time it is used is a shorthand for this rule:
-quote(tt( --filter=': /.rsync-filter'))
+quote(tt( --filter='dir-merge /.rsync-filter'))
This tells rsync to look for per-directory .rsync-filter files that have
been sprinkled through the hierarchy and use their rules to filter the
files in the transfer. If bf(-F) is repeated, it is a shorthand for this
rule:
-quote(tt( --filter='- .rsync-filter'))
+quote(tt( --filter='exclude .rsync-filter'))
This filters out the .rsync-filter files themselves from the transfer.
See the FILTER RULES section for detailed information on this option.
-dit(bf(--exclude-from=FILE)) This option is similar to the bf(--exclude)
-option, but instead it adds all exclude patterns listed in the file
-FILE to the exclude list. Blank lines in FILE and lines starting with
-';' or '#' are ignored.
-If em(FILE) is bf(-) the list will be read from standard input.
+dit(bf(--exclude-from=FILE)) This option is related to the bf(--exclude)
+option, but it specifies a FILE that contains exclude patterns (one per line).
+Blank lines in the file and lines starting with ';' or '#' are ignored.
+If em(FILE) is bf(-), the list will be read from standard input.
dit(bf(--include=PATTERN)) This option is a simplified form of the
bf(--filter) option that defaults to an include rule and does not allow
See the FILTER RULES section for detailed information on this option.
-dit(bf(--include-from=FILE)) This specifies a list of include patterns
-from a file.
-If em(FILE) is "-" the list will be read from standard input.
+dit(bf(--include-from=FILE)) This option is related to the bf(--include)
+option, but it specifies a FILE that contains include patterns (one per line).
+Blank lines in the file and lines starting with ';' or '#' are ignored.
+If em(FILE) is bf(-), the list will be read from standard input.
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 "-"
+exact list of files to transfer (as read from the specified FILE or bf(-)
for standard input). It also tweaks the default behavior of rsync to make
transferring just the specified files and directories easier:
quote(itemize(
it() The bf(--relative) (bf(-R)) option is implied, which preserves the path
information that is specified for each item in the file (use
- bf(--no-relative) if you want to turn that off).
+ bf(--no-relative) or bf(--no-R) if you want to turn that off).
it() The bf(--dirs) (bf(-d)) option is implied, which will create directories
specified in the list on the destination rather than noisily skipping
- them.
+ them (use bf(--no-dirs) or bf(--no-d) if you want to turn that off).
it() The bf(--archive) (bf(-a)) option's behavior does not imply bf(--recursive)
(bf(-r)), so specify it explicitly, if you want it.
+ it() These side-effects change the default state of rsync, so the position
+ of the bf(--files-from) option on the command-line has no bearing on how
+ other options are parsed (e.g. bf(-a) works the same before or after
+ bf(--files-from), as does bf(--no-R) and all other options).
))
The file names that are read from the FILE are all relative to the
blocking I/O, otherwise it defaults to using non-blocking I/O. (Note that
ssh prefers non-blocking I/O.)
-dit(bf(--no-blocking-io)) Turn off bf(--blocking-io), for use when it is the
-default.
-
dit(bf(-i, --itemize-changes)) Requests a simple itemized list of the
changes that are being made to each file, including attribute changes.
This is exactly the same as specifying bf(--log-format='%i %n%L').
touched directory) unless the itemized-changes escape (%i) is included in
the string, in which case the logging of names increases to mention any
item that is changed in any way (as long as the receiving side is at least
-2.6.4). See the bf(--itemized-changes) option for a description of the
+2.6.4). See the bf(--itemize-changes) option for a description of the
output of "%i".
The bf(--verbose) option implies a format of "%n%L", but you can use
This option uses more memory on the receiving side (one bit per file
transferred) and also requires enough free disk space on the receiving
side to hold an additional copy of all the updated files. Note also that
-you should not use an absolute path to bf(--partial-dir) unless there is no
+you should not use an absolute path to bf(--partial-dir) unless (1)
+there is no
chance of any of the files in the transfer having the same name (since all
the updated files will be put into a single directory if the path is
-absolute).
+absolute)
+and (2) there are no mount points in the hierarchy (since the
+delayed updates will fail if they can't be renamed into place).
See also the "atomic-rsync" perl script in the "support" subdir for an
update algorithm that is even more atomic (it uses bf(--link-dest) and a
dit(bf(--read-batch=FILE)) Apply all of the changes stored in FILE, a
file previously generated by bf(--write-batch).
-If em(FILE) is "-" the batch data will be read from standard input.
+If em(FILE) is bf(-), the batch data will be read from standard input.
See the "BATCH MODE" section for details.
dit(bf(--protocol=NUM)) Force an older protocol version to be used. This
The following modifiers are accepted after a "+" or "-":
itemize(
- it() A "/" specifies that the include/exclude should be treated as an
- absolute path, relative to the root of the filesystem. For example,
+ it() A "/" specifies that the include/exclude rule should be matched
+ against the absolute pathname of the current item. For example,
"-/ /etc/passwd" would exclude the passwd file any time the transfer
- was sending files from the "/etc" directory.
+ was sending files from the "/etc" directory, and "-/ subdir/foo"
+ would always exclude "foo" when it is in a dir named "subdir", even
+ if "foo" is at the root of the current transfer.
it() A "!" specifies that the include/exclude should take effect if
the pattern fails to match. For instance, "-! */" would exclude all
non-directories.
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff