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.
--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
+ --ignore-missing-args ignore missing source args without error
+ --delete-missing-args delete missing source args from destination
--ignore-errors delete even if there are I/O errors
--force force deletion of dirs even if not empty
--max-delete=NUM don't delete more than NUM files
--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
bf(--delete-excluded).
See bf(--delete) (which is implied) for more details on file-deletion.
+dit(bf(--ignore-missing-args)) When rsync is first processing the explicitly
+requested source files (e.g. command-line arguments or bf(--files-from)
+entries), it is normally an error if the file cannot be found. This option
+suppresses that error, and does not try to transfer the file. This does not
+affect subsequent vanished-file errors if a file was initially found to be
+present and later is no longer there.
+
+dit(bf(--delete-missing-args)) This option takes the behavior of (the implied)
+bf(--ignore-missing-args) option a step farther: each missing arg will become
+a deletion request of the corresponding destination file on the receiving side
+(should it exist). If the destination file is a non-empty directory, it will
+only be successfully deleted if --force or --delete are in effect. Other than
+that, this option is independent of any other type of delete processing.
+
+The missing source files are represented by special file-list entries which
+display as a "*missing" entry in the bf(--list-only) output.
+
dit(bf(--ignore-errors)) Tells bf(--delete) to go ahead and delete files
even when there are I/O errors.
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.
When the file transfer finishes, rsync replaces the progress line with a
summary line that looks like this:
-verb( 1238099 100% 146.38kB/s 0:00:08 (xfer#5, to-check=169/396))
+verb( 1,238,099 100% 146.38kB/s 0:00:08 (xfr#5, to-chk=169/396))
-In this example, the file was 1238099 bytes long in total, the average rate
+In this example, the file was 1,238,099 bytes long in total, the average rate
of transfer for the whole file was 146.38 kilobytes per second over the 8
seconds that it took to complete, it was the 5th transfer of a regular file
during the current rsync session, and there are 169 more files for the
receiver to check (to see if they are up-to-date or not) remaining out of
the 396 total files in the file-list.
+In an incremental recursion scan, rsync won't know the total number of files
+in the file-list until it reaches the ends of the scan, but since it starts to
+transfer files during the scan, it will display a line with the text "ir-chk"
+(for incremental recursion check) instead of "to-chk" until the point that it
+knows the full size of the list, at which point it will switch to using
+"to-chk". Thus, seeing "ir-chk" lets you know that the total count of files
+in the file list is still going to increase (and each time it does, the count
+of files left to check will increase by the number of the files added to the
+list).
+
dit(bf(-P)) The bf(-P) option is equivalent to bf(--partial) bf(--progress). Its
purpose is to make it much easier to specify these two options for a long
transfer that may be interrupted.
dit(bf(--password-file)) This option allows you to provide a password in a
file for accessing an rsync daemon. The file must not be world readable.
-It should contain just the password as a single line.
+It should contain just the password as the first line of the file (all
+other lines are ignored).
This option does not supply a password to a remote shell transport such as
ssh; to learn how to do that, consult the remote shell's documentation.
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff