mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(30 Sep 2004)()()
+manpage(rsync)(1)(22 Feb 2005)()()
manpagename(rsync)(faster, flexible replacement for rcp)
manpagesynopsis()
--rsync-path=PATH specify path to rsync on the 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
--del an alias for --delete-during
--delete delete files that don't exist on sender
--delete-before receiver deletes before transfer (default)
-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
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
everything. The only exception to this is if bf(--files-from) was
-specified, in which case bf(-d) is implied instead of bf(-r).
+specified, in which case bf(-r) is not implied.
Note that bf(-a) bf(does not preserve hardlinks), because
finding multiply-linked files is expensive. You must separately
renamed as each file is transferred or deleted. You can control where the
backup file goes and what (if any) suffix gets appended using the
bf(--backup-dir) and bf(--suffix) options.
+Note that if you don't specify bf(--backup-dir), the bf(--omit-dir-times)
+option will be enabled.
dit(bf(--backup-dir=DIR)) In combination with the bf(--backup) option, this
tells rsync to store all backups in the specified directory. This is
specify a backup suffix using the bf(--suffix) option
(otherwise the files backed up in the specified directory
will keep their original filenames).
-If DIR is a relative path, it is relative to the destination directory
-(which changes in a recursive transfer).
dit(bf(--suffix=SUFFIX)) This option allows you to override the default
backup suffix used with the bf(--backup) (bf(-b)) option. The default suffix is a ~
The option implies bf(--partial) (since an interrupted transfer does not delete
the file), but conflicts with bf(--partial-dir) and bf(--delay-updates).
-Prior to rsync 2.6.4 bf(--inplace) was also incompatible with bf(--compare-dest),
-bf(--copy-dest), and bf(--link-dest).
+Prior to rsync 2.6.4 bf(--inplace) was also incompatible with bf(--compare-dest)
+and bf(--link-dest).
WARNING: The file's data will be in an inconsistent state during the
transfer (and possibly afterward if the transfer gets interrupted), so you
dit(bf(-O, --omit-dir-times)) This tells rsync to omit directories when
it is preserving modification times (see bf(--times)). If NFS is sharing
the directories on the receiving side, it is a good idea to use bf(-O).
+This option is inferred if you use bf(--backup) without bf(--backup-dir).
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.
This tells rsync not to update files that already exist on
the destination.
+dit(bf(--remove-sent-files)) This tells rsync to remove from the sending
+side the files and/or symlinks that are newly created or whose content is
+updated on the receiving side. Directories and devices are not removed,
+nor are files/symlinks whose attributes are merely changed.
+
dit(bf(--delete)) This tells rsync to delete extraneous files from the
receiving side (ones that aren't on the sending side), but only for the
directories that are being synchronized. You must have asked rsync to
and also determines if the transfer needs to happen.
If em(DIR) is a relative path, it is relative to the destination directory.
-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 the data in the em(DIR) for an efficient 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.
-
-If em(DIR) is a relative path, it is relative to the destination directory.
-See also bf(--compare-dest) and bf(--link-dest).
+See also bf(--link-dest).
-dit(bf(--link-dest=DIR)) This option behaves like bf(--copy-dest), but
+dit(bf(--link-dest=DIR)) This option behaves like bf(--compare-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.
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(--copy-dest).
+See also bf(--compare-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
dit(bf(-i, --itemize-changes)) Requests a simple itemized list of the
changes that are being made to each file, including attribute changes.
-This is equivalent to specifying bf(--log-format='%i %n%L'). (See the
-description of what the output of '%i' means in the rsyncd.conf manpage.)
-Rsync also mentions the delete action when an item replaces an item of a
-different type (e.g. a directory replaces a file of the same name).
+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:
+
+quote(tt( =Xcstpog))
+
+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.).
+
+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 rest of the 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
+letter with a space, and (3) an unknown attribute replaces each letter with
+a "?" (this happens when talking to an older rsync).
+
+The attribute that is associated with each letter is as follows:
+
+quote(itemize(
+ it() A bf(c) means the checksum of the file is different and will be
+ updated by the file transfer (requries bf(--checksum)).
+ it() A bf(s) means the size of the file is different and will be updated
+ by the file transfer.
+ it() A bf(t) means the modification time is different and is being updated
+ to the server's value (requires bf(--times)). An alternate value of bf(T)
+ means that the time will be set to the transfer time, which happens
+ anytime a symlink is transferred, or when a file or device is transferred
+ without bf(--times).
+ it() A bf(p) means the permissions are different and are being updated to
+ the server's value (requires bf(--perms)).
+ it() An bf(o) means the owner is being updated to the server's value
+ (requires bf(--owner) and root privileges).
+ it() A bf(g) means the group is being updated to the server's value
+ (requires bf(--group) and the authority to set the requested group).
+))
+
+One other output is possible: when deleting files, the "%i" will output
+the string "deleting" for each item that is being removed (assuming that
+you are talking to a recent enough rsync that it logs deletions instead of
+outputting them as a verbose message).
dit(bf(--log-format=FORMAT)) This allows you to specify exactly what the
-rsync client logs to stdout on a per-file basis. This format can be used
-without bf(--verbose) to enable just the outputting of the file-transfer
-information, or it can be used to change how the names are output when
-bf(--verbose) is enabled. Rsync will log the name of an item prior to its
-transfer unless one of the transferred-byte-count values is requested, in
-which case the logging is done at the end of the item's transfer. In this
-late-transfer state, if bf(--progress) is also specified, rsync will output
-just the name of the file prior to the progress information.
-
-The log format is specified using the same format conventions as the
-"log format" option in rsyncd.conf, so see that manpage for details.
-(Note that this option does not affect what a daemon logs to its logfile.)
+rsync client outputs to the user on a per-file basis. The format is a text
+string containing embedded single-character escape sequences prefixed with
+a percent (%) character. For a list of the possible escape characters, see
+the "log format" setting in the rsyncd.conf manpage. (Note that this
+option does not affect what a daemon logs to its logfile.)
+
+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
+the string, in which case the logging of names increases to mention any
+item that is updated in any way (as long as the receiving side is version
+2.6.4). See the bf(--itemized-changes) option for a description of the
+output of "%i".
+
+The bf(--verbose) option implies a format of "%n%L", but you can use
+bf(--log-format) without bv(--verbose) if you like, or you can override
+the format of its per-file output using this option.
+
+Rsync will output the log-format string prior to a file's transfer unless
+one of the transfer-statistic escapes is requested, in which case the
+logging is done at the end of the file's transfer. When this late logging
+is in effect and bf(--progress) is also specified, rsync will also output
+the name of the file being transferred prior to its progress information
+(followed, of course, by the log-format output).
dit(bf(--stats)) This tells rsync to print a verbose set of statistics
on the file transfer, allowing you to tell how effective the rsync
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff