As expected, if neither the source or destination path specify a remote
host, the copy occurs locally (see also the bf(--list-only) option).
+Rsync refers to the local side as the "client" and the remote side as the
+"server". Don't confuse "server" with an rsync daemon -- a daemon is always a
+server, but a server can be either a daemon or a remote-shell spawned process.
+
manpagesection(SETUP)
See the file README for installation instructions.
-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
+ --munge-links munge symlinks to make them safer
-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
--remove-source-files sender removes synchronized files (non-dir)
--del an alias for --delete-during
--delete delete extraneous files from dest dirs
- --delete-before receiver deletes before transfer (default)
- --delete-during receiver deletes during xfer, not before
+ --delete-before receiver deletes before xfer, not during
+ --delete-during receiver deletes during transfer (default)
--delete-delay find deletions during, delete after
--delete-after receiver deletes after transfer, not before
--delete-excluded also delete excluded files from dest dirs
--delay-updates put all updated files into place at end
-m, --prune-empty-dirs prune empty directory chains from file-list
--numeric-ids don't map uid/gid values by user/group name
+ --usermap=STRING custom username mapping
+ --groupmap=STRING custom groupname mapping
+ --chown=USER:GROUP simple username/groupname mapping
--timeout=SECONDS set I/O timeout in seconds
--contimeout=SECONDS set daemon connection timeout in seconds
-I, --ignore-times don't skip files that match size and time
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"
filter-rule for the backup suffix to the end of all your existing excludes
-(e.g. bf(-f "Pp *~")). This will prevent previously backed-up files from being
+(e.g. bf(-f "P *~")). This will prevent previously backed-up files from being
deleted. Note that if you are supplying your own filter 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
also ignored. Using this option in conjunction with bf(--relative) may
give unexpected results.
+dit(bf(--munge-links)) This option tells rsync to (1) modify all symlinks on
+the receiving side in a way that makes them unusable but recoverable (see
+below), or (2) to unmunge symlinks on the sending side that had been stored in
+a munged state. This is useful if you don't quite trust the source of the data
+to not try to slip in a symlink to a unexpected place.
+
+The way rsync disables the use of symlinks is to prefix each one with the
+string "/rsyncd-munged/". This prevents the links from being used as long as
+that directory does not exist. When this option is enabled, rsync will refuse
+to run if that path is a directory or a symlink to a directory.
+
+The option only affects the client side of the transfer, so if you need it to
+affect the server, specify it via bf(--remote-option). (Note that in a local
+transfer, the client side is the sender.)
+
+This option has no affect on a daemon, since the daemon configures whether it
+wants munged symlinks via its "munge symlinks" parameter. See also the
+"munge-symlinks" perl script in the support directory of the source code.
+
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
quote(tt( rsync -av --link-dest=$PWD/prior_dir host:src_dir/ new_dir/))
+If file's aren't linking, double-check their attributes. Also check if some
+attributes are getting forced outside of rsync's control, such a mount option
+that squishes root to a single user, or mounts a removable drive with generic
+ownership (such as OS X's "Ignore ownership on this volume" option).
+
Beginning in version 2.6.4, multiple bf(--link-dest) directories may be
provided, which will cause rsync to search the list in the order specified
for an exact match.
the chroot setting affects rsync's ability to look up the names of the
users and groups and what you can do about it.
+dit(bf(--usermap=STRING, --groupmap=STRING)) These options allow you to
+specify users and groups that should be mapped to other values by the
+receiving side. The bf(STRING) is one or more bf(FROM):bf(TO) pairs of
+values separated by commas. Any matching bf(FROM) value from the sender is
+replaced with a bf(TO) value from the receiver. You may specify usernames
+or user IDs for the bf(FROM) and bf(TO) values, and the bf(FROM) value may
+also be a wild-card string, which will be matched against the sender's
+names (wild-cards do NOT match against ID numbers, though see below for
+why a '*' matches everything). You may instead specify a range of ID
+numbers via an inclusive range: LOW-HIGH. For example:
+
+verb( --usermap=0-99:nobody,wayne:admin,*:normal --groupmap=usr:1,1:usr)
+
+The first match in the list is the one that is used. You should specify
+all your user mappings using a single bf(--usermap) option, and/or all
+your group mappings using a single bf(--groupmap) option.
+
+Note that the sender's name for the 0 user and group are not transmitted
+to the receiver, so you should either match these values using a 0, or use
+the names in effect on the receiving side (typically "root"). All other
+bf(FROM) names match those in use on the sending side. All bf(TO) names
+match those in use on the receiving side.
+
+Any IDs that do not have a name on the sending side are treated as having an
+empty name for the purpose of matching. This allows them to be matched via
+a "*" or using an empty name. For instance:
+
+verb( --usermap=:nobody --groupmap=*:nobody)
+
+When the bf(--numeric-ids) option is used, the sender does not send any
+names, so all the IDs are treated as having an empty name. This means that
+you will need to specify numeric bf(FROM) values if you want to map these
+nameless IDs to different values.
+
+For the bf(--usermap) option to have any effect, the bf(-o) (bf(--owner))
+option must be used (or implied), and the receiver will need to be running
+as a super-user (see also the bf(--fake-super) option). For the bf(--groupmap)
+option to have any effect, the bf(-g) (bf(--groups)) option must be used
+(or implied), and the receiver will need to have permissions to set that
+group.
+
+dit(bf(--chown=USER:GROUP)) This option forces all files to be owned by USER
+with group GROUP. This is a simpler interface than using bf(--usermap) and
+bf(--groupmap) directly, but it is implemented using those options internally,
+so you cannot mix them. If either the USER or GROUP is empty, no mapping for
+the omitted user/group will occur. If GROUP is empty, the trailing colon may
+be omitted, but if USER is empty, a leading colon must be supplied.
+
+If you specify "--chown=foo:bar, this is exactly the same as specifying
+"--usermap=*:foo --groupmap=*:bar", only easier.
+
dit(bf(--timeout=TIMEOUT)) This option allows you to set a maximum I/O
timeout in seconds. If no data is transferred for the specified time
then rsync will exit. The default is 0, which means no timeout.
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.
+There are 3 possible levels: (1) output numbers with a separator between each
+set of 3 digits (either a comma or a period, depending on if the decimal point
+is represented by a period or a comma); (2) output numbers in units of 1000
+(with a character suffix for larger units -- see below); (3) output numbers in
+units of 1024.
+
+The default is human-readable level 1. Each bf(-h) option increases the level
+by one. You can take the level down to 0 (to output numbers as pure digits) by
+specifing the bf(--no-human-readable) (bf(--no-h)) option.
+
+The unit letters that are appended in levels 2 and 3 are: K (kilo), M (mega),
+G (giga), or T (tera). For example, a 1234567-byte file would output as 1.23M
+in level-2 (assuming that a period is your local decimal point).
+
+Backward compatibility note: versions of rsync prior to 3.1.0 do not support
+human-readable level 1, and they default to level 0. Thus, specifying one or
+two bf(-h) options behaves the same in old and new versions as long as you
+didn't specify a bf(--no-h) option prior to one or more bf(-h) options.
dit(bf(--partial)) By default, rsync will delete any partially
transferred file if the transfer is interrupted. In some circumstances
it() rsync chooses between doing a simple string match and wildcard
matching by checking if the pattern contains one of these three wildcard
characters: '*', '?', and '[' .
- it() a '*' matches any non-empty path component (it stops at slashes).
+ it() a '*' matches any path component, but it stops at slashes.
it() use '**' to match anything, including slashes.
it() a '?' matches any character except a slash (/).
it() a '[' introduces a character class, such as [a-z] or [[:alpha:]].
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff