X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/d37d1c44ff388153302fb47bdb8dc39479b48759..0417c34e2d641cbac292ba5cf8a619249c87d4e3:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 12bd07db..5094c8a2 100644 --- a/rsync.yo +++ b/rsync.yo @@ -3,20 +3,20 @@ manpage(rsync)(1)(28 Jul 2005)()() manpagename(rsync)(faster, flexible replacement for rcp) manpagesynopsis() +rsync [OPTION]... SRC [SRC]... DEST + rsync [OPTION]... SRC [SRC]... [USER@]HOST:DEST -rsync [OPTION]... [USER@]HOST:SRC [DEST] +rsync [OPTION]... SRC [SRC]... [USER@]HOST::DEST -rsync [OPTION]... SRC [SRC]... DEST +rsync [OPTION]... SRC [SRC]... rsync://[USER@]HOST[:PORT]/DEST -rsync [OPTION]... [USER@]HOST::SRC [DEST] +rsync [OPTION]... [USER@]HOST:SRC [DEST] -rsync [OPTION]... SRC [SRC]... [USER@]HOST::DEST +rsync [OPTION]... [USER@]HOST::SRC [DEST] rsync [OPTION]... rsync://[USER@]HOST[:PORT]/SRC [DEST] -rsync [OPTION]... SRC [SRC]... rsync://[USER@]HOST[:PORT]/DEST - manpagedescription() rsync is a program that behaves in much the same way that rcp does, @@ -76,9 +76,6 @@ different remote shell by default, such as rsh or remsh. You can also specify any remote shell you like, either by using the bf(-e) command line option, or by setting the RSYNC_RSH environment variable. -One common substitute is to use ssh, which offers a high degree of -security. - Note that rsync must be installed on both the source and destination machines. @@ -186,13 +183,14 @@ that: itemize( 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 first word after the :: is a module name. + it() the first word of the "path" is actually a module name. it() the remote daemon may print a message of the day when you connect. it() if you specify no path name on the remote daemon then the list of accessible paths on the daemon will be shown. it() if you specify no local destination then a listing of the specified files on the remote daemon is provided. + it() you must not specify the bf(--rsh) (bf(-e)) option. ) An example that copies all the files in a remote module named "src": @@ -300,10 +298,10 @@ to the detailed description below for a complete description. verb( -q, --quiet suppress non-error messages -c, --checksum skip based on checksum, not mod-time & size -a, --archive archive mode; same as -rlptgoD (no -H) + --no-OPTION turn off an implied OPTION (e.g. --no-D) -r, --recursive recurse into directories -R, --relative use relative path names - --no-relative turn off --relative - --no-implied-dirs don't send implied dirs with -R + --no-implied-dirs don't send implied dirs with --relative -b, --backup make backups (see --suffix & --backup-dir) --backup-dir=DIR make backups into hierarchy based in DIR --suffix=SUFFIX backup suffix (default ~ w/o --backup-dir) @@ -326,7 +324,6 @@ to the detailed description below for a complete description. verb( -S, --sparse handle sparse files efficiently -n, --dry-run show what would have been transferred -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 @@ -371,7 +368,6 @@ to the detailed description below for a complete description. verb( --address=ADDRESS bind address for outgoing socket to daemon --port=PORT specify double-colon alternate port number --blocking-io use blocking I/O for the remote shell - --no-blocking-io turn off blocking I/O when it is default --stats give some file-transfer stats --progress show progress during transfer -P same as --partial --progress @@ -466,13 +462,33 @@ receiver are not transferred. This option can be quite slow. 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 +everything (with -H being a notable omission). +The only exception to the above equivalence is when bf(--files-from) is 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 specify bf(-H). +dit(--no-OPTION) You may turn off one or more implied options by prefixing +the option name with "no-". Not all options may be prefixed with a "no-": +only options that are implied by other options (e.g. bf(--no-D), +bf(--no-perms)) or have different defaults in various circumstances +(e.g. bf(--no-whole-file), bf(--no-blocking-io), bf(--no-dirs)). You may +specify either the short or the long option name after the "no-" prefix +(e.g. bf(--no-R) is the same as bf(--no-relative)). + +For example: if you want to use bf(-a) (bf(--archive)) but don't want +bf(-o) (bf(--owner)), instead of converting bf(-a) into bf(-rlptgD), you +could specify bf(-a --no-o) (or bf(-a --no-owner)). + +The order of the options is important: if you specify bf(--no-r -a), the +bf(-r) option would end up being turned on, the opposite of bf(-a --no-r). +Note also that the side-effects of the bf(--files-from) option are NOT +positional, as it affects the default state of several options and sligntly +changes the meaning of bf(-a) (see the bf(--files-from) option for more +details). + dit(bf(-r, --recursive)) This tells rsync to copy directories recursively. See also bf(--dirs) (bf(-d)). @@ -514,10 +530,6 @@ tt( rsync -avR --rsync-path="cd /foo; rsync" \ )nl() tt( remote:bar/baz.c /tmp/) ) -dit(bf(--no-relative)) Turn off the bf(--relative) option. This is only -needed if you want to use bf(--files-from) without its implied bf(--relative) -file processing. - dit(bf(--no-implied-dirs)) When combined with the bf(--relative) option, the implied directories in each path are not explicitly duplicated as part of the transfer. This makes the transfer more optimal and also allows @@ -590,14 +602,17 @@ side. If that is not true, the file will fail the checksum test, and the resend will do a normal bf(--inplace) update to correct the mismatched data. Only files on the receiving side that are shorter than the corresponding file on the sending side (as well as new files) are sent. -Implies bf(--inplace). +Implies bf(--inplace), but does not conflict with bf(--sparse) (though the +bf(--sparse) option will be auto-disabled if a resend of the already-existing +data is required). dit(bf(-d, --dirs)) Tell the sending side to include any directories that are encountered. Unlike bf(--recursive), a directory's contents are not copied unless the directory was specified on the command-line as either "." or a name with a trailing slash (e.g. "foo/"). Without this option or the bf(--recursive) option, rsync will skip all directories it encounters (and -output a message to that effect for each one). +output a message to that effect for each one). If you specify both +bf(--dirs) and bf(--recursive), the latter takes precedence. dit(bf(-l, --links)) When symlinks are encountered, recreate the symlink on the destination. @@ -641,9 +656,6 @@ destination machines is higher than the bandwidth to disk (especially when the "disk" is actually a networked filesystem). This is the default when both the source and destination are specified as local paths. -dit(bf(--no-whole-file)) Turn off bf(--whole-file), for use when it is the -default. - dit(bf(-p, --perms)) This option causes rsync to set the destination permissions to be the same as the source permissions. @@ -687,7 +699,8 @@ 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. dit(bf(-S, --sparse)) Try to handle sparse files efficiently so they take -up less space on the destination. +up less space on the destination. Conflicts with bf(--inplace) because it's +not possible to overwrite data in a sparse fashion. NOTE: Don't use this option when the destination is a Solaris "tmpfs" filesystem. It doesn't seem to handle seeks over null regions @@ -873,14 +886,14 @@ See the FILTER RULES section for detailed information on this option. dit(bf(-F)) The bf(-F) option is a shorthand for adding two bf(--filter) rules to your command. The first time it is used is a shorthand for this rule: -quote(tt( --filter=': /.rsync-filter')) +quote(tt( --filter='dir-merge /.rsync-filter')) This tells rsync to look for per-directory .rsync-filter files that have been sprinkled through the hierarchy and use their rules to filter the files in the transfer. If bf(-F) is repeated, it is a shorthand for this rule: -quote(tt( --filter='- .rsync-filter')) +quote(tt( --filter='exclude .rsync-filter')) This filters out the .rsync-filter files themselves from the transfer. @@ -893,11 +906,10 @@ the full rule-parsing syntax of normal filter rules. See the FILTER RULES section for detailed information on this option. -dit(bf(--exclude-from=FILE)) This option is similar to the bf(--exclude) -option, but instead it adds all exclude patterns listed in the file -FILE to the exclude list. Blank lines in FILE and lines starting with -';' or '#' are ignored. -If em(FILE) is bf(-) the list will be read from standard input. +dit(bf(--exclude-from=FILE)) This option is related to the bf(--exclude) +option, but it specifies a FILE that contains exclude patterns (one per line). +Blank lines in the file and lines starting with ';' or '#' are ignored. +If em(FILE) is bf(-), the list will be read from standard input. dit(bf(--include=PATTERN)) This option is a simplified form of the bf(--filter) option that defaults to an include rule and does not allow @@ -905,24 +917,29 @@ the full rule-parsing syntax of normal filter rules. See the FILTER RULES section for detailed information on this option. -dit(bf(--include-from=FILE)) This specifies a list of include patterns -from a file. -If em(FILE) is "-" the list will be read from standard input. +dit(bf(--include-from=FILE)) This option is related to the bf(--include) +option, but it specifies a FILE that contains include patterns (one per line). +Blank lines in the file and lines starting with ';' or '#' are ignored. +If em(FILE) is bf(-), the list will be read from standard input. dit(bf(--files-from=FILE)) Using this option allows you to specify the -exact list of files to transfer (as read from the specified FILE or "-" +exact list of files to transfer (as read from the specified FILE or bf(-) for standard input). It also tweaks the default behavior of rsync to make transferring just the specified files and directories easier: quote(itemize( it() The bf(--relative) (bf(-R)) option is implied, which preserves the path information that is specified for each item in the file (use - bf(--no-relative) if you want to turn that off). + bf(--no-relative) or bf(--no-R) if you want to turn that off). it() The bf(--dirs) (bf(-d)) option is implied, which will create directories specified in the list on the destination rather than noisily skipping - them. + them (use bf(--no-dirs) or bf(--no-d) if you want to turn that off). it() The bf(--archive) (bf(-a)) option's behavior does not imply bf(--recursive) (bf(-r)), so specify it explicitly, if you want it. + it() These side-effects change the default state of rsync, so the position + of the bf(--files-from) option on the command-line has no bearing on how + other options are parsed (e.g. bf(-a) works the same before or after + bf(--files-from), as does bf(--no-R) and all other options). )) The file names that are read from the FILE are all relative to the @@ -1082,9 +1099,6 @@ rsync defaults to using blocking I/O, otherwise it defaults to using non-blocking I/O. (Note that ssh prefers non-blocking I/O.) -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'). @@ -1246,10 +1260,13 @@ Conflicts with bf(--inplace). This option uses more memory on the receiving side (one bit per file transferred) and also requires enough free disk space on the receiving side to hold an additional copy of all the updated files. Note also that -you should not use an absolute path to bf(--partial-dir) unless there is no +you should not use an absolute path to bf(--partial-dir) unless (1) +there is no chance of any of the files in the transfer having the same name (since all the updated files will be put into a single directory if the path is -absolute). +absolute) +and (2) there are no mount points in the hierarchy (since the +delayed updates will fail if they can't be renamed into place). See also the "atomic-rsync" perl script in the "support" subdir for an update algorithm that is even more atomic (it uses bf(--link-dest) and a @@ -1330,7 +1347,7 @@ into the batch file without having to flow over the wire to the receiver dit(bf(--read-batch=FILE)) Apply all of the changes stored in FILE, a file previously generated by bf(--write-batch). -If em(FILE) is "-" the batch data will be read from standard input. +If em(FILE) is bf(-), the batch data will be read from standard input. See the "BATCH MODE" section for details. dit(bf(--protocol=NUM)) Force an older protocol version to be used. This