mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(28 Jul 2005)()()
+manpage(rsync)(1)(8 Feb 2006)()()
manpagename(rsync)(faster, flexible replacement for rcp)
manpagesynopsis()
-H, --hard-links preserve hard links
-K, --keep-dirlinks treat symlinked dir on receiver as dir
-p, --perms preserve permissions
+ -E, --executability preserve executability
+ --chmod=CHMOD change destination permissions
-o, --owner preserve owner (super-user only)
-g, --group preserve group
--devices preserve device files (super-user only)
-t, --times preserve times
-O, --omit-dir-times omit directories when preserving times
--super receiver attempts super-user activities
- --chmod=CHMOD change destination permissions
-S, --sparse handle sparse files efficiently
-n, --dry-run show what would have been transferred
-W, --whole-file copy files whole (without rsync algorithm)
--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.
Note that if you don't specify bf(--backup-dir), (1) the
bf(--omit-dir-times) option will be implied, and (2) if bf(--delete) is
-also in effect (without bf(--delete-excluded)), rsync will add a protect
+also in effect (without bf(--delete-excluded)), rsync will add a "protect"
filter-rule for the backup suffix to the end of all your existing excludes
(e.g. -f "P *~"). This will prevent previously backed-up files from being
deleted. Note that if you are supplying your own filter rules, you may
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
"disk" is actually a networked filesystem). This is the default when both
the source and destination are specified as local paths.
-dit(bf(-p, --perms)) This option causes rsync to set the destination
-permissions to be the same as the source permissions.
+dit(bf(-p, --perms)) This option causes the receiving rsync to set the
+destination permissions to be the same as the source permissions. (See
+also the bf(--chmod) option for a way to modify what rsync considers to
+be the source permissions.)
+
+When this option is em(off), permissions are set as follows:
+
+quote(itemize(
+ 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() 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).
-Without this option, all existing files (including updated files) retain
-their existing permissions, while each new file gets its permissions set
-based on the source file's permissions, but masked by the receiving end's
-umask setting
-(which is the same behavior as other file-copy utilities, such as cp).
+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 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'
+ permissions.
+ it() To make a file executable, rsync turns on each 'x' permission that
+ has a corresponding 'r' permission enabled.
+))
+
+If bf(--perms) is enabled, this option is ignored.
+
+dit(bf(--chmod)) This option tells rsync to apply one or more
+comma-separated "chmod" strings to the permission of the files in the
+transfer. The resulting value is treated as though it was the permissions
+that the sending side supplied for the file, which means that this option
+can seem to have no effect on existing files if bf(--perms) is not enabled.
+
+In addition to the normal parsing rules specified in the bf(chmod)(1)
+manpage, you can specify an item that should only apply to a directory by
+prefixing it with a 'D', or specify an item that should only apply to a
+file by prefixing it with a 'F'. For example:
+
+quote(--chmod=Dg+s,ug+w,Fo-w,+X)
+
+It is also legal to specify multiple bf(--chmod) options, as each
+additional option is just appended to the list of changes to make.
+
+See the bf(--perms) and bf(--executability) options for how the resulting
+permission value can be applied to the files in the transfer.
dit(bf(-o, --owner)) This option causes rsync to set the owner of the
destination file to be the same as the source file. By default, the
being running as the super-user. To turn off super-user activities, the
super-user can use bf(--no-super).
-dit(bf(--chmod)) This option tells rsync to apply the listed "chmod" pattern
-to the permission of the files on the destination. In addition to the normal
-parsing rules specified in the chmod manpage, you can specify an item that
-should only apply to a directory by prefixing it with a 'D', or specify an
-item that should only apply to a file by prefixing it with a 'F'. For example:
-
-quote(--chmod=Dg+s,ug+w,Fo-w,+X)
-
-It is also legal to specify multiple bf(--chmod) options.
-
-If permissions are not being preserved (via bf(--perms)), the resulting value
-will still be masked by the receiving end's umask setting.
-
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.
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.
verbose messages).
The "%i" escape has a cryptic output that is 9 letters long. The general
-format is like the string bf(UXcstpog)), where bf(U) is replaced by the
-kind of update being done, bf(X) is replaced by the file-type, and the
+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.
-The update types that replace the bf(U) are as follows:
+The update types that replace the bf(Y) are as follows:
quote(itemize(
it() A bf(<) means that a file is being transferred to the remote host
(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
partial-directory in the destination file's directory when needed, and then
remove it again when the partial file is deleted.
-If the partial-dir value is not an absolute path, rsync will also add a directory
-bf(--exclude) of this value at the end of all your existing excludes. This
-will prevent partial-dir files from being transferred and also prevent the
-untimely deletion of partial-dir items on the receiving side. An example:
-the above bf(--partial-dir) option would add an "bf(--exclude=.rsync-partial/)"
-rule at the end of any other filter rules. Note that if you are
-supplying your own exclude rules, you may need to manually insert your own
-exclude/protect rule somewhere higher up in the list so that
-it has a high enough priority to be effective (e.g., if your rules specify
-a trailing inclusion/exclusion of '*', the auto-added rule would never be
-reached).
+If the partial-dir value is not an absolute path, rsync will add an exclude
+rule at the end of all your existing excludes. This will prevent the
+sending of any partial-dir files that may exist on the sending side, and
+will also prevent the untimely deletion of partial-dir items on the
+receiving side. An example: the above bf(--partial-dir) option would add
+the equivalent of "bf(--exclude=.rsync-partial/)" at the end of any other
+filter rules.
+
+If you are supplying your own exclude rules, you may need to add your own
+exclude/hide/protect rule for the partial-dir because (1) the auto-added
+rule may be ineffective at the end of your other rules, or (2) you may wish
+to override rsync's exclude choice. For instance, if you want to make
+rsync clean-up any left-over partial-dirs that may be lying around, you
+should specify bf(--delete-after) and add a "risk" filter rule, e.g.
+bf(-f 'R .rsync-partial/'). (Avoid using bf(--delete-before) or
+bf(--delete-during) unless you don't need rsync to use any of the
+left-over partial-dir data during the current run.)
IMPORTANT: the bf(--partial-dir) should not be writable by other users or it
is a security risk. E.g. AVOID "/tmp".
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
succession. This attempts to make the updating of the files a little more
atomic. By default the files are placed into a directory named ".~tmp~" in
each file's destination directory, but if you've specified the
-bf(--partial-dir) option, that directory will be used instead.
+bf(--partial-dir) option, that directory will be used instead. See the
+comments in the bf(--partial-dir) section for a discussion of how this
+".~tmp~" dir will be excluded from the transfer, and what you can do if
+you wnat rsync to cleanup old ".~tmp~" dirs that might be lying around.
Conflicts with bf(--inplace) and bf(--append).
This option uses more memory on the receiving side (one bit per file
"- 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.7pre1 of rsync.
manpagesection(CREDITS)
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff