mailto(rsync-bugs@samba.org)
-manpage(rsync)(1)(30 Sep 2004)()()
+manpage(rsync)(1)(28 Feb 2005)()()
manpagename(rsync)(faster, flexible replacement for rcp)
manpagesynopsis()
that:
itemize(
- it() you use a double colon :: instead of a single colon to
- separate the hostname from the path or an rsync:// URL.
+ it() you either use a double colon :: instead of a single colon to
+ separate the hostname from the path, or you use an rsync:// URL.
it() the remote server may print a message of the day when you
connect.
it() if you specify no path name on the remote server then the
to the detailed description below for a complete description. verb(
-v, --verbose increase verbosity
-q, --quiet suppress non-error messages
- -c, --checksum always checksum
-c, --checksum skip based on checksum, not mod-time & size
-a, --archive archive mode; same as -rlptgoD (no -H)
-r, --recursive recurse into directories
-O, --omit-dir-times omit directories when preserving times
-S, --sparse handle sparse files efficiently
-n, --dry-run show what would have been transferred
- -W, --whole-file copy files whole
+ -W, --whole-file copy files whole (without rsync algorithm)
--no-whole-file always use incremental rsync algorithm
-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
--del an alias for --delete-during
--delete delete files that don't exist on sender
--delete-before receiver deletes before transfer (default)
-I, --ignore-times don't skip files that match size and time
--size-only skip files that match in size
--modify-window=NUM compare mod-times with reduced accuracy
- -T --temp-dir=DIR create temporary files in directory DIR
+ -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
-f, --filter=RULE add a file-filtering RULE
- -F same as --filter=': /.rsync-filter'
+ -F same as --filter='dir-merge /.rsync-filter'
repeated: --filter='- .rsync-filter'
--exclude=PATTERN exclude files matching PATTERN
--exclude-from=FILE read exclude patterns from FILE
--include=PATTERN don't exclude files matching PATTERN
--include-from=FILE read include patterns from FILE
--files-from=FILE read list of source-file names from FILE
- -0 --from0 all *from file lists are delimited by nulls
+ -0, --from0 all *from file lists are delimited by nulls
--version print version number
--port=PORT specify double-colon alternate port number
--blocking-io use blocking I/O for the remote shell
--stats give some file-transfer stats
--progress show progress during transfer
-P same as --partial --progress
+ -i, --itemize-changes output a change-summary for all updates
--log-format=FORMAT log file-transfers using specified format
--password-file=FILE read password from FILE
--list-only list the files instead of copying them
--write-batch=FILE write a batched update to FILE
--read-batch=FILE read a batched update from FILE
--checksum-seed=NUM set block/file checksum seed (advanced)
- -4 --ipv4 prefer IPv4
- -6 --ipv6 prefer IPv6
+ -4, --ipv4 prefer IPv4
+ -6, --ipv6 prefer IPv6
-h, --help show this help screen)
Rsync can also be run as a daemon, in which case the following options are
--no-detach do not detach from the parent
--port=PORT listen on alternate port number
-v, --verbose increase verbosity
- -4 --ipv4 prefer IPv4
- -6 --ipv6 prefer IPv6
+ -4, --ipv4 prefer IPv4
+ -6, --ipv6 prefer IPv6
-h, --help show this help screen)
manpageoptions()
information at the end. More than two bf(-v) flags should only be used if
you are debugging rsync.
+Note that the names of the transferred files that are output are done using
+a default bf(--log-format) of "%n%L", which tells you just the name of the
+file and, if the item is a symlink, where it points. At the single bf(-v)
+level of verbosity, this does not mention when a file gets its attributes
+changed. If you ask for an itemized list of changed attributes (either
+bf(--itemize-changes) or adding "%i" to the bf(--log-format) setting), the
+output (on the client) increases to mention all items that are changed in
+any way. See the bf(--log-format) option for more details.
+
dit(bf(-q, --quiet)) This option decreases the amount of information you
are given during the transfer, notably suppressing information messages
from the remote server. This flag is useful when invoking rsync from
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(--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.
-
-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
-suffixed with a letter to indicate a size multiplier (K, M, or G) and
-may be a fractional value (e.g. "bf(--max-size=1.5m)").
+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
is only relevant without bf(--delete) because deletions are now done depth-first.
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 (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
+suffixed with a letter to indicate a size multiplier (K, M, or G) and
+may be a fractional value (e.g. "bf(--max-size=1.5m)").
+
dit(bf(-B, --block-size=BLOCKSIZE)) This forces the block size used in
the rsync algorithm to a fixed value. It is normally selected based on
the size of each file being updated. See the technical report for details.
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
If you're combining bf(-C) with your own bf(--filter) rules, you should
note that these CVS excludes are appended at the end of your own rules,
-regardless of where the -C was placed on the command-line. This makes them
+regardless of where the bf(-C) was placed on the command-line. This makes them
a lower priority than any rules you specified explicitly. If you want to
control where these CVS excludes get inserted into your filter rules, you
should omit the bf(-C) as a command-line option and use a combination of
transferred on the receiving side. The default behavior is to create
the temporary files in the receiving directory.
+dit(bf(-y, --fuzzy)) This option tells rsync that it should look for a
+basis file for any destination file that is missing. The current algorithm
+looks in the same directory as the destination file for either a file that
+has an identical size and modified-time, or a similarly-named file. If
+found, rsync uses the fuzzy basis file to try to speed up the transfer.
+
+Note that the use of the bf(--delete) option might get rid of any potential
+fuzzy-match files, so either use bf(--delete-after) or specify some
+filename exclusions if you need to prevent this.
+
dit(bf(--compare-dest=DIR)) This option instructs rsync to use em(DIR) on
the destination machine as an additional hierarchy to compare destination
files against doing transfers (if the files are missing in the destination
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(--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.
+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.
+
+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).
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) and bf(--copy-dest).
dit(bf(--no-blocking-io)) Turn off bf(--blocking-io), for use when it is the
default.
+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 exactly the same as specifying bf(--log-format='%i %n%L').
+
+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.
+
+The update types that replace the bf(U) are as follows:
+
+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 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 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
+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 different and is being updated to the
+ 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
+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. The log format is
-specified using the same format conventions as the log format option in
-rsyncd.conf.
+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
startdit()
dit(bf(--daemon)) This tells rsync that it is to run as a daemon. The
-daemon may be accessed using the bf(host::module) or
-bf(rsync://host/module/) syntax.
+daemon you start running may be accessed using an rsync client using
+the bf(host::module) or bf(rsync://host/module/) syntax.
If standard input is a socket then rsync will assume that it is being
run via inetd, otherwise it will detach from the current terminal and
Matt McCutchen's Web Site / rsync / rsync.git / blobdiff