mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(28 Jul 2005)()()
+manpage(rsync)(1)(2 Mar 2006)()()
manpagename(rsync)(faster, flexible replacement for rcp)
manpagesynopsis()
rsync [OPTION]... SRC [SRC]... rsync://[USER@]HOST[:PORT]/DEST
+rsync [OPTION]... SRC
+
rsync [OPTION]... [USER@]HOST:SRC [DEST]
rsync [OPTION]... [USER@]HOST::SRC [DEST]
"USING RSYNC-DAEMON FEATURES VIA A REMOTE-SHELL CONNECTION" section for
an exception to this latter rule).
-As a special case, if a remote source is specified without a destination,
-the remote files are listed in an output format similar to "ls -l".
+As a special case, if a single source arg is specified without a
+destination, the files are listed in an output format similar to "ls -l".
As expected, if neither the source or destination path specify a remote
host, the copy occurs locally (see also the bf(--list-only) option).
If you need to specify a different remote-shell user, keep in mind that the
user@ prefix in front of the host is specifying the rsync-user value (for a
module that requires user-based authentication). This means that you must
-give the '-l user' option to ssh when specifying the remote-shell:
+give the '-l user' option to ssh when specifying the remote-shell, as in
+this example that uses the short version of the bf(--rsh) option:
verb( rsync -av -e "ssh -l ssh-user" rsync-user@host::module /dest)
-L, --copy-links transform symlink into referent file/dir
--copy-unsafe-links only "unsafe" symlinks are transformed
--safe-links ignore symlinks that point outside the tree
- -H, --hard-links preserve hard links
+ -k, --copy-dirlinks transform symlink to dir into referent dir
-K, --keep-dirlinks treat symlinked dir on receiver as dir
+ -H, --hard-links preserve hard links
-p, --perms preserve permissions
-E, --executability preserve executability
--chmod=CHMOD change destination permissions
--sockopts=OPTIONS specify custom TCP options
--blocking-io use blocking I/O for the remote shell
--stats give some file-transfer stats
+ -8, --8-bit-output leave high-bit chars unescaped in output
-h, --human-readable output numbers in a human-readable format
- --si like human-readable, but use powers of 1000
--progress show progress during transfer
-P same as --partial --progress
-i, --itemize-changes output a change-summary for all updates
-4, --ipv4 prefer IPv4
-6, --ipv6 prefer IPv6
--version print version number
- --help show this help screen)
+(-h) --help show this help (see below for -h comment)
+)
Rsync can also be run as a daemon, in which case the following options are
accepted: verb(
-v, --verbose increase verbosity
-4, --ipv4 prefer IPv4
-6, --ipv6 prefer IPv6
- --help show this help screen)
+ -h, --help show this help (if used after --daemon)
+)
manpageoptions()
startdit()
dit(bf(--help)) Print a short help page describing the options
available in rsync and exit. For backward-compatibility with older
-versions of rsync, the same help output can also be requested by using
-the bf(-h) option without any other args.
+versions of rsync, the help will also be output if you use the bf(-h)
+option without any other args.
dit(bf(--version)) print the rsync version number and exit.
times with a 2-second resolution), bf(--modify-window=1) is useful
(allowing times to differ by up to 1 second).
-dit(bf(-c, --checksum)) This forces the sender to checksum all files using
-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 not transferred. This option can be quite slow.
+dit(bf(-c, --checksum)) This forces the sender to checksum em(every)
+regular file using a 128-bit MD4 checksum. It does this during the initial
+file-system scan as it builds the list of all available files. The receiver
+then checksums its version of each file (if it exists and it has the same
+size as its sender-side counterpart) in order to decide which files need to
+be updated: files with either a changed size or a changed checksum are
+selected for transfer. Since this whole-file checksumming of all files on
+both sides of the connection occurs in addition to the automatic checksum
+verifications that occur during a file's transfer, this option can be quite
+slow.
+
+Note that rsync always verifies that each em(transferred) file was correctly
+reconstructed on the receiving side by checking its whole-file checksum, but
+that automatic after-the-transfer verification has nothing to do with this
+option's before-the-transfer "Does this file need to be updated?" check.
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
quote(tt( rsync -av /foo/bar/baz.c remote:/tmp/))
-... this would create a file called baz.c in /tmp/ on the remote
+... this would create a file named baz.c in /tmp/ on the remote
machine. If instead you used
quote(tt( rsync -avR /foo/bar/baz.c remote:/tmp/))
-then a file called /tmp/foo/bar/baz.c would be created on the remote
+then a file named /tmp/foo/bar/baz.c would be created on the remote
machine -- the full path name is preserved. To limit the amount of
path information that is sent, you have a couple options: (1) With
a modern rsync on the sending side (beginning with 2.6.7), you can
-insert a dot dir into the source path, like this:
+insert a dot and a slash into the source path, like this:
quote(tt( rsync -avR /foo/./bar/baz.c remote:/tmp/))
That would create /tmp/bar/baz.c on the remote machine. (Note that the
-dot dir must followed by a slash, so "/foo/." would not be abbreviated.)
+dot must be followed by a slash, so "/foo/." would not be abbreviated.)
(2) For older rsync versions, you would need to use a chdir to limit the
source path. For example, when pushing files:
tt( remote:bar/baz.c /tmp/)
)
-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
-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 bf(-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 bf(--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(--no-implied-dirs)) This option affects the default behavior of the
+bf(--relative) option. When it is specified, the attributes of the implied
+directories from the source names are not included in the transfer. This
+means that the corresponding path elements on the destination system are
+left unchanged if they exist, and any missing implied directories are
+created with default attributes. This even allows these implied path
+elements to have big differences, such as being a symlink to a directory on
+one side of the transfer, and a real directory on the other side.
+
+For instance, if a command-line arg or a files-from entry told rsync to
+transfer the file "path/foo/file", the directories "path" and "path/foo"
+are implied when bf(--relative) is used. If "path/foo" is a symlink to
+"bar" on the destination system, the receiving rsync would ordinarily
+delete "path/foo", recreate it as a directory, and receive the file into
+the new directory. With bf(--no-implied-dirs), the receiving rsync updates
+"path/foo/file" using the existing path elements, which means that the file
+ends up being created in "path/bar". Another way to accomplish this link
+preservation is to use the bf(--keep-dirlinks) option (which will also
+affect symlinks to directories in the rest of the transfer).
+
+In a similar but opposite scenario, if the transfer of "path/foo/file" is
+requested and "path/foo" is a symlink on the sending side, running without
+bf(--no-implied-dirs) would cause rsync to transform "path/foo" on the
+receiving side into an identical symlink, and then attempt to transfer
+"path/foo/file", which might fail if the duplicated symlink did not point
+to a directory on the receiving side. Another way to avoid this sending of
+a symlink as an implied directory is to use bf(--copy-unsafe-links), or
+bf(--copy-dirlinks) (both of which also affect symlinks in the rest of the
+transfer -- see their descriptions for full details).
dit(bf(-b, --backup)) With this option, preexisting destination files are
renamed as each file is transferred or deleted. You can control where the
dit(bf(-l, --links)) When symlinks are encountered, recreate the
symlink on the destination.
-dit(bf(-L, --copy-links)) When symlinks are encountered, the file that
+dit(bf(-L, --copy-links)) When symlinks are encountered, the item that
they point to (the referent) is copied, rather than the symlink. In older
versions of rsync, this option also had the side-effect of telling the
receiving side to follow symlinks, such as symlinks to directories. In a
dit(bf(--copy-unsafe-links)) This tells rsync to copy the referent of
symbolic links that point outside the copied tree. Absolute symlinks
are also treated like ordinary files, and so are any symlinks in the
-source path itself when bf(--relative) is used.
+source path itself when bf(--relative) is used. This option has no
+additional effect if bf(--copy-links) was also specified.
dit(bf(--safe-links)) This tells rsync to ignore any symbolic links
which point outside the copied tree. All absolute symlinks are
also ignored. Using this option in conjunction with bf(--relative) may
give unexpected results.
-dit(bf(-H, --hard-links)) This tells rsync to recreate hard links on
-the remote system to be the same as the local system. Without this
-option hard links are treated like regular files.
+dit(bf(-K, --copy-dirlinks)) This option causes the sending side to treat
+a symlink to a directory as though it were a real directory. This is
+useful if you don't want symlinks to non-directories to be affected, as
+they would be using bf(--copy-links).
-Note that rsync can only detect hard links if both parts of the link
-are in the list of files being sent.
+Without this option, if the sending side has replaced a directory with a
+symlink to a directory, the receiving side will delete anything that is in
+the way of the new symlink, including a directory hierarchy (as long as
+bf(--force) or bf(--delete) is in effect).
-This option can be quite slow, so only use it if you need it.
+See also bf(--keep-dirlinks) for an analogous option for the receiving
+side.
-dit(bf(-K, --keep-dirlinks)) On the receiving side, if a symlink is
-pointing to a directory, it will be treated as matching a directory
-from the sender.
+dit(bf(-K, --keep-dirlinks)) This option causes the receiving side to treat
+a symlink to a directory as though it were a real directory, but only if it
+matches a real directory from the sender. Without this option, the
+receiver's symlink would be deleted and replaced with a real directory.
-dit(bf(-W, --whole-file)) With this option the incremental rsync algorithm
-is not used and the whole file is sent as-is instead. The transfer may be
-faster if this option is used when the bandwidth between the source and
-destination machines is higher than the bandwidth to disk (especially when the
-"disk" is actually a networked filesystem). This is the default when both
-the source and destination are specified as local paths.
+For example, suppose you transfer a directory "foo" that contains a file
+"file", but "foo" is a symlink to directory "bar" on the receiver. Without
+bf(--keep-dirlinks), the receiver deletes symlink "foo", recreates it as a
+directory, and receives the file into the new directory. With
+bf(--keep-dirlinks), the receiver keeps the symlink and "file" ends up in
+"bar".
+
+See also bf(--copy-dirlinks) for an analogous option for the sending side.
+
+dit(bf(-H, --hard-links)) This tells rsync to look for hard-linked files in
+the transfer and link together the corresponding files on the receiving
+side. Without this option, hard-linked files in the transfer are treated
+as though they were separate files.
+
+Note that rsync can only detect hard links if both parts of the link
+are in the list of files being sent.
dit(bf(-p, --perms)) This option causes the receiving rsync to set the
destination permissions to be the same as the source permissions. (See
bf(--perms) option is off and use bf(--chmod=ugo=rwX) (which ensures that
all non-masked bits get enabled). If you'd care to make this latter
behavior easier to type, you could define a popt alias for it, such as
-putting this line in the file ~/.popt (this defines the bf(-s) option):
+putting this line in the file ~/.popt (this defines the bf(-s) option,
+and includes --no-g to use the default group of the destination dir):
-quote(tt( rsync alias -s --no-p --chmod=ugo=rwX))
+quote(tt( rsync alias -s --no-p --no-g --chmod=ugo=rwX))
You could then use this new option in a command such as this one:
quote(tt( rsync -asv src/ dest/))
+(Caveat: make sure that bf(-a) does not follow bf(-s), or it will re-enable
+the "--no-*" options.)
+
The preservation of the destination's setgid bit on newly-created
directories when bf(--perms) is off was added in rsync 2.6.7. Older rsync
versions erroneously preserved the three special permission bits for
being running as the super-user. To turn off super-user activities, the
super-user can use bf(--no-super).
-dit(bf(-n, --dry-run)) This tells rsync to not do any file transfers,
-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. Conflicts with bf(--inplace) because it's
not possible to overwrite data in a sparse fashion.
filesystem. It doesn't seem to handle seeks over null regions
correctly and ends up corrupting the files.
+dit(bf(-n, --dry-run)) This tells rsync to not do any file transfers,
+instead it will just report the actions it would have taken.
+
+dit(bf(-W, --whole-file)) With this option the incremental rsync algorithm
+is not used and the whole file is sent as-is instead. The transfer may be
+faster if this option is used when the bandwidth between the source and
+destination machines is higher than the bandwidth to disk (especially when the
+"disk" is actually a networked filesystem). This is the default when both
+the source and destination are specified as local paths.
+
dit(bf(-x, --one-file-system)) This tells rsync to avoid crossing a
filesystem boundary when recursing. This does not limit the user's ability
to specify items to copy from multiple filesystems, just rsync's recursion
as it is sent to the destination machine, which reduces the amount of data
being transmitted -- something that is useful over a slow connection.
-Note this this option typically achieves better compression ratios that can
+Note that this option typically achieves better compression ratios than can
be achieved by using a compressing remote shell or a compressing transport
because it takes advantage of the implicit information in the matching data
blocks that are not explicitly sent over the connection.
with older versions of rsync, but that also turns on the output of other
verbose messages).
-The "%i" escape has a cryptic output that is 8 letters long. The general
-format is like the string bf(YXcstpog), where bf(Y) is replaced by the
-kind of update being done, bf(X) is replaced by the file-type, and the
+The "%i" escape has a cryptic output that is 9 letters long. The general
+format is like the string bf(YXcstpogz), where bf(Y) is replaced by the
+type of update being done, bf(X) is replaced by the file-type, and the
other letters represent attributes that may be output if they are being
modified.
(received).
it() A bf(c) means that a local change/creation is occurring for the item
(such as the creation of a directory or the changing of a symlink, etc.).
- it() A bf(h) means that the item is a hard-link to another item (requires
+ it() A bf(h) means that the item is a hard link to another item (requires
bf(--hard-links)).
it() A bf(.) means that the item is not being updated (though it might
have attributes that are being modified).
sender's value (requires bf(--owner) and super-user privileges).
it() A bf(g) means the group is different and is being updated to the
sender's value (requires bf(--group) and the authority to set the group).
+ it() The bf(z) slot is reserved for future use.
))
One other output is possible: when deleting files, the "%i" will output
Specifying this option will mention each file, dir, etc. that gets updated
in a significant way (a transferred file, a recreated symlink/device, or a
-touched directory) unless the itemized-changes escape (%i) is included in
+touched directory) unless the itemize-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(--itemize-changes) option for a description of the
on the file transfer, allowing you to tell how effective the rsync
algorithm is for your data.
-dit(bf(-h, --human-readable)) Output numbers in a more human-readable format.
-Large numbers may be output in larger units, with a K (1024), M (1024*1024),
-or G (1024*1024*1024) suffix.
+The current statistics are as follows: itemize(
+ it() bf(Number of files) is the count of all "files" (in the generic
+ sense), which includes directories, symlinks, etc.
+ it() bf(Number of files transferred) is the count of normal files that
+ were updated via the rsync algorithm, which does not include created
+ dirs, symlinks, etc.
+ it() bf(Total file size) is the total sum of all file sizes in the transfer.
+ This does not count any size for directories or special files, but does
+ include the size of symlinks.
+ it() bf(Total transferred file size) is the total sum of all files sizes
+ for just the transferred files.
+ it() bf(Literal data) is how much unmatched file-update data we had to
+ send to the receiver for it to recreate the updated files.
+ it() bf(Matched data) is how much data the receiver got locally when
+ recreating the updated files.
+ it() bf(File list size) is how big the file-list data was when the sender
+ sent it to the receiver. This is smaller than the in-memory size for the
+ file list due to some compressing of duplicated data when rsync sends the
+ list.
+ it() bf(File list generation time) is the number of seconds that the
+ sender spent creating the file list. This requires a modern rsync on the
+ sending side for this to be present.
+ it() bf(File list transfer time) is the number of seconds that the sender
+ spent sending the file list to the receiver.
+ it() bf(Total bytes sent) is the count of all the bytes that rsync sent
+ from the client side to the server side.
+ it() bf(Total bytes received) is the count of all non-message bytes that
+ rsync received by the client side from the server side. "Non-message"
+ bytes means that we don't count the bytes for a verbose message that the
+ server sent to us, which makes the stats more consistent.
+)
+
+dit(bf(-8, --8-bit-output)) This tells rsync to leave all high-bit characters
+unescaped in the output instead of trying to test them to see if they're
+valid in the current locale and escaping the invalid ones. All control
+characters (but never tabs) are always escaped, regardless of this option's
+setting.
-dit(bf(--si)) Similar to the bf(--human-readable) option, but using powers
-of 1000 instead of 1024.
+The escape idiom that started in 2.6.7 is to output a literal backslash (\)
+and a hash (#), followed by exactly 3 octal digits. For example, a newline
+would output as "\#012". A literal backslash that is in a filename is not
+escaped unless it is followed by a hash and 3 digits (0-9).
+
+dit(bf(-h, --human-readable)) Output numbers in a more human-readable format.
+This makes big numbers output using larger units, with a K, M, or G suffix. If
+this option was specified once, these units are K (1000), M (1000*1000), and
+G (1000*1000*1000); if the option is repeated, the units are powers of 1024
+instead of 1000.
dit(bf(--partial)) By default, rsync will delete any partially
transferred file if the transfer is interrupted. In some circumstances
You can also set the partial-dir value the RSYNC_PARTIAL_DIR environment
variable. Setting this in the environment does not force bf(--partial) to be
-enabled, but rather it effects where partial files go when bf(--partial) is
+enabled, but rather it affects where partial files go when bf(--partial) is
specified. For instance, instead of using bf(--partial-dir=.rsync-tmp)
along with bf(--progress), you could set RSYNC_PARTIAL_DIR=.rsync-tmp in your
environment and then just use the bf(-P) option to turn on the use of the
that any superfluous files and directories in the destination are removed
(note the hide filter of non-directories being used instead of an exclude):
-quote( rsync -avm --del --include='*.pdf' -f 'hide! */' src/ dest)
+quote( rsync -avm --del --include='*.pdf' -f 'hide,! */' src/ dest)
If you didn't want to remove superfluous destination files, the more
time-honored options of "--include='*/' --exclude='*'" would work fine
single line.
dit(bf(--list-only)) This option will cause the source files to be listed
-instead of transferred. This option is inferred if there is no destination
-specified, so you don't usually need to use it explicitly. However, it can
-come in handy for a user that wants to avoid the "bf(-r --exclude='/*/*')"
-options that rsync might use as a compatibility kluge when generating a
-non-recursive listing, or to list the files that are involved in a local
-copy (since the destination path is not optional for a local copy, you
-must specify this option explicitly and still include a destination).
+instead of transferred. This option is inferred if there is a single source
+arg and no destination specified, so its main uses are: (1) to turn a copy
+command that includes a
+destination arg into a file-listing command, (2) to be able to specify more
+than one local source arg (note: be sure to include the destination), or
+(3) to avoid the automatically added "bf(-r --exclude='/*/*')" options that
+rsync usually uses as a compatibility kluge when generating a non-recursive
+listing. Caution: keep in mind that a source arg with a wild-card is expanded
+by the shell into multiple args, so it is never safe to try to list such an arg
+without using this option. For example:
+
+verb( rsync -av --list-only foo* dest/)
dit(bf(--bwlimit=KBPS)) This option allows you to specify a maximum
transfer rate in kilobytes per second. This option is most effective when
particular spot in the hierarchy of files, otherwise it is matched
against the end of the pathname. This is similar to a leading ^ in
regular expressions.
- Thus "/foo" would match a file called "foo" at either the "root of the
+ Thus "/foo" would match a file named "foo" at either the "root of the
transfer" (for a global rule) or in the merge-file's directory (for a
per-directory rule).
An unqualified "foo" would match any file or directory named "foo"
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: "+ */" (put it somewhere before the
-"- *" rule). Another solution is to add specific include rules for all
+"- *" rule), and perhaps use the bf(--prune-empty-dirs) option. 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:
itemize(
it() "- *.o" would exclude all filenames matching *.o
- it() "- /foo" would exclude a file called foo in the transfer-root directory
- it() "- foo/" would exclude any directory called foo
- it() "- /foo/*/bar" would exclude any file called bar two
- levels below a directory called foo in the transfer-root directory
- it() "- /foo/**/bar" would exclude any file called bar two
- or more levels below a directory called foo in the transfer-root directory
+ it() "- /foo" would exclude a file (or directory) named foo in the
+ transfer-root directory
+ it() "- foo/" would exclude any directory named foo
+ it() "- /foo/*/bar" would exclude any file named bar which is at two
+ levels below a directory named foo in the transfer-root directory
+ it() "- /foo/**/bar" would exclude any file named bar two
+ or more levels below a directory named foo in the transfer-root directory
it() The combination of "+ */", "+ *.c", and "- *" would include all
- directories and C source files but nothing else.
+ directories and C source files but nothing else (see also the
+ bf(--prune-empty-dirs) option)
it() The combination of "+ foo/", "+ foo/bar.c", and "- *" would include
only the foo directory and foo/bar.c (the foo directory must be
explicitly included or it would be excluded by the "*")
"- foo + bar" is parsed as two rules (assuming that prefix-parsing wasn't
also disabled).
it() You may also specify any of the modifiers for the "+" or "-" rules
- (below) in order to have the rules that are read-in from the file
+ (below) in order to have the rules that are read in from the file
default to having that modifier set. For instance, "merge,-/ .excl" would
treat the contents of .excl as absolute-path excludes,
while "dir-merge,s .filt" and ":sC" would each make all their
This will merge the contents of the /home/user/.global-filter file at the
start of the list and also turns the ".rules" filename into a per-directory
-filter file. All rules read-in prior to the start of the directory scan
+filter file. All rules read in prior to the start of the directory scan
follow the global anchoring rules (i.e. a leading slash matches at the root
of the transfer).
dit(bf(--copy-unsafe-links)) Turn all unsafe symlinks into files, noisily
skip all safe symlinks.
-dit(bf(--links --safe-links)) Duplicate safe symlinks and skip unsafe
+dit(bf(--links --safe-links)) Duplicate safe symlinks and skip unsafe
ones.
dit(bf(--links)) Duplicate all symlinks.
manpagebugs()
-times are transferred as unix time_t values
+times are transferred as *nix time_t values
When transferring to FAT filesystems rsync may re-sync
unmodified files.
manpagesection(VERSION)
-This man page is current for version 2.6.6 of rsync.
+This man page is current for version 2.6.7pre3 of rsync.
manpagesection(CREDITS)