X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/fbe5eeb831ea4842fc2bb3bfffc9a5689b74080f..c70e07d9ac09da1f00c531bb9137347f516f88f9:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 1daed83e..d647fb80 100644 --- a/rsync.yo +++ b/rsync.yo @@ -1,5 +1,5 @@ mailto(rsync-bugs@samba.org) -manpage(rsync)(1)(22 Feb 2005)()() +manpage(rsync)(1)(28 Feb 2005)()() manpagename(rsync)(faster, flexible replacement for rcp) manpagesynopsis() @@ -193,8 +193,8 @@ Using rsync in this way is the same as using it with a remote shell except 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 @@ -297,7 +297,6 @@ Here is a short summary of the options available in rsync. Please refer 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 @@ -329,7 +328,7 @@ to the detailed description below for a complete description. verb( -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 @@ -750,8 +749,8 @@ 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. 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 @@ -787,10 +786,18 @@ environment variable, which accepts the same range of values as bf(-e). 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 @@ -814,7 +821,7 @@ See the bf(cvs(1)) manual for more information. 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 @@ -945,9 +952,10 @@ directory. This is useful for creating a sparse backup of just files that 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 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). @@ -960,10 +968,11 @@ An example: 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 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). @@ -1019,24 +1028,93 @@ 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 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 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. 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 @@ -1201,8 +1279,8 @@ The options allowed when starting an rsync daemon are as follows: 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