-x, --one-file-system don't cross filesystem boundaries
-B, --block-size=SIZE force a fixed checksum block-size
-e, --rsh=COMMAND specify the remote shell to use
- --rsync-path=PATH specify path to rsync on the remote machine
+ --rsync-path=PROGRAM specify the rsync to run on remote machine
--existing only update files that already exist
--ignore-existing ignore files that already exist on receiver
--remove-sent-files sent files/symlinks are removed from sender
-T, --temp-dir=DIR create temporary files in directory DIR
-y, --fuzzy find similar file for basis if no dest file
--compare-dest=DIR also compare received files relative to DIR
+ --copy-dest=DIR ... and include copies of unchanged files
--link-dest=DIR hardlink to files in DIR when unchanged
-z, --compress compress file data during the transfer
-C, --cvs-exclude auto-ignore files in the same way CVS does
Requires the bf(--recursive) option (which is implied by bf(-a)) to have any effect.
dit(bf(--max-delete=NUM)) This tells rsync not to delete more than NUM
-files or directories. This is useful when mirroring very large trees
-to prevent disasters.
+files or directories (NUM must be non-zero).
+This is useful when mirroring very large trees to prevent disasters.
dit(bf(--max-size=SIZE)) This tells rsync to avoid transferring any
file that is larger than the specified SIZE. The SIZE value can be
See also the bf(--blocking-io) option which is affected by this option.
-dit(bf(--rsync-path=PATH)) Use this to specify the path to the copy of
-rsync on the remote machine. Useful when it's not in your path. Note
-that this is the full path to the binary, not just the directory that
-the binary is in.
+dit(bf(--rsync-path=PROGRAM)) Use this to specify what program is to be run
+on the remote machine to start-up rsync. Often used when rsync is not in
+the default remote-shell's path (e.g. --rsync-path=/usr/local/bin/rsync).
+Note that PROGRAM is run with the help of a shell, so it can be any
+program, script, or command sequence you'd care to run, so long as it does
+not corrupt the standard-in & standard-out that rsync is using to
+communicate.
+
+One tricky example is to set a different default directory on the remote
+machine for use with the bf(--relative) option. For instance:
+
+quote(tt( rsync -avR --rsync-path="cd /a/b && rsync" hst:c/d /e/))
dit(bf(-C, --cvs-exclude)) This is a useful shorthand for excluding a
broad range of files that you often don't want to transfer between
have changed from an earlier backup.
Beginning in version 2.6.4, multiple bf(--compare-dest) directories may be
-provided and rsync will search the list in the order specified until it
-finds an existing file. That first discovery is used as the basis file,
-and also determines if the transfer needs to happen.
+provided, which will cause rsync to search the list in the order specified
+for an exact match.
+If a match is found that differs only in attributes, a local copy is made
+and the attributes updated.
+If a match is not found, a basis file from one of the em(DIR)s will be
+selected to try to speed up the transfer.
If em(DIR) is a relative path, it is relative to the destination directory.
-See also bf(--link-dest).
+See also bf(--copy-dest) and bf(--link-dest).
+
+dit(bf(--copy-dest=DIR)) This option behaves like bf(--compare-dest), but
+rsync will also copy unchanged files found in em(DIR) to the destination
+directory using a local copy.
+This is useful for doing transfers to a new destination while leaving
+existing files intact, and then doing a flash-cutover when all files have
+been successfully transferred.
-dit(bf(--link-dest=DIR)) This option behaves like bf(--compare-dest), but
+Multiple bf(--copy-dest) directories may be provided, which will cause
+rsync to search the list in the order specified for an unchanged file.
+If a match is not found, a basis file from one of the em(DIR)s will be
+selected to try to speed up the transfer.
+
+If em(DIR) is a relative path, it is relative to the destination directory.
+See also bf(--compare-dest) and bf(--link-dest).
+
+dit(bf(--link-dest=DIR)) This option behaves like bf(--copy-dest), but
unchanged files are hard linked from em(DIR) to the destination directory.
The files must be identical in all preserved attributes (e.g. permissions,
possibly ownership) in order for the files to be linked together.
quote(tt( rsync -av --link-dest=$PWD/prior_dir host:src_dir/ new_dir/))
-Beginning with version 2.6.4, if more than one bf(--link-dest) option is
-specified, rsync will try to find an exact match to link with (searching
-the list in the order specified), and if not found, a basis file from one
-of the em(DIR)s will be selected to try to speed up the transfer.
+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.
+If a match is found that differs only in attributes, a local copy is made
+and the attributes updated.
+If a match is not found, a basis file from one of the em(DIR)s will be
+selected to try to speed up the transfer.
If em(DIR) is a relative path, it is relative to the destination directory.
-See also bf(--compare-dest).
+See also bf(--compare-dest) and bf(--copy-dest).
Note that rsync versions prior to 2.6.1 had a bug that could prevent
bf(--link-dest) from working properly for a non-root user when bf(-o) was specified
changes that are being made to each file, including attribute changes.
This is exactly the same as specifying bf(--log-format='%i %n%L').
-The "%i" escape has a cryptic output that is 8 letters long. The general
-format is as follows:
+The "%i" escape has a cryptic output that is 9 letters long. The general
+format is like the string bf(UXcstpoga)), where bf(U) is replaced by the
+kind 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
+updated.
-quote(tt( =Xcstpog))
+The update types that replace the bf(U) are as follows:
-The bf(=) is output as either a bf(<) (receive) or a bf(>) (send) if the
-item is being transferred, a bf(.) if only the attributes are being
-updated, or a bf(=) if the items are identical. Note that when a symlink
-or a device gets its value changed, that is considered to be a transfer (as
-opposed to a change in permissions, ownership, etc.).
+quote(itemize(
+ it() A bf(<) means that a file is being transferred to the local host
+ (received).
+ it() A bf(>) means that a file is being transferred to the remote host
+ (sent).
+ it() A bf(c) means that a local change/creation is occuring for the item
+ (such as the creation of a directory or a symlink).
+ 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 only has attributes that are being
+ changed.
+ it() A bf(=) means that the item is identical (this only only output for
+ higher levels of verbosity).
+))
-The bf(X) will be replaced by one of the following: an "f" for a file, a
-"d" for a dir, an "L" for a symlink, or a "D" for a device.
+The file-types that replace the bf(X) are: bf(f) for a file, a bf(d) for a
+dir, an bf(L) for a symlink, and a bf(D) for a device.
-The rest of the letters in the string above are the actual letters that
+The other letters in the string above are the actual letters that
will be output if the associated attribute for the item is being updated or
a "." for no change. Three exceptions to this are: (1) a newly created
item replaces each letter with a "+", (2) an identical item replaces each
server's value (requires bf(--owner) and root privileges).
it() A bf(g) means the group is different and is being updated to the
server's value (requires bf(--group) and the authority to set the group).
+ it() The bf(a) is reserved for a future enhanced version that supports
+ extended file attributes, such as ACLs.
))
One other output is possible: when deleting files, the "%i" will output
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff