mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(28 Jul 2005)()()
+manpage(rsync)(1)(19 Feb 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).
--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
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
+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.
Note that rsync can only detect hard links if both parts of the link
it() Existing files (including updated files) retain their existing
permissions, though the bf(--executability) option might change just
the execute permission for the file.
- it() Each new file gets its permissions set based on the source file's
- permissions, but masked by the receiving end's umask setting (including
- the stripping of the three special permission bits).
+ it() New files get their "normal" permission bits set to the source
+ file's permissions masked with the receiving end's umask setting, and
+ their special permission bits disabled except in the case where a new
+ directory inherits a setgid bit from its parent directory.
))
-
+
Thus, when bf(--perms) and bf(--executability) are both disabled,
rsync's behavior is the same as that of other file-copy utilities,
such as bf(cp)(1) and bf(tar)(1).
+In summary: to give destination files (both old and new) the source
+permissions, use bf(--perms). To give new files the destination-default
+permissions (while leaving existing files unchanged), make sure that the
+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,
+and includes --no-g to use the default group of the destination dir):
+
+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
+newly-created files when bf(--perms) was off, while overriding the
+destination's setgid bit setting on a newly-created directory. (Keep in
+mind that it is the version of the receiving rsync that affects this
+behavior.)
+
dit(bf(-E, --executability)) This option causes rsync to preserve the
executability (or non-executability) of regular files when bf(--perms) is
not enabled. A regular file is considered to be executable if at least one
-'x' is turned on in the source permissions.
+'x' is turned on in its permissions. When an existing destination file's
+executability differs from that of the corresponding source file, rsync
+modifies the destination file's permissions as follows:
quote(itemize(
it() To make a file non-executable, rsync turns off all its 'x'
through the hierarchy of each directory that the user specified, and also
the analogous recursion on the receiving side during deletion. Also keep
in mind that rsync treats a "bind" mount to the same device as being on the
-same filesystem.
+same filesystem.
If this option is repeated, rsync omits all mount-point directories from
the copy. Otherwise, it includes an empty directory at each mount-point it
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(--si)) Similar to the bf(--human-readable) option, but using powers
-of 1000 instead of 1024.
+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.
+
+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
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).
+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.
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.7pre2 of rsync.
manpagesection(CREDITS)
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff