X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/397a344364b1b2ca73669f1085ea44eefd92fe77..69864a5ccf1f2d66c8b807888e16fbe158ad3562:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 8aacc1e1..7bc0e4c0 100644 --- a/rsync.yo +++ b/rsync.yo @@ -324,7 +324,7 @@ to the detailed description below for a complete description. verb( -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 @@ -350,21 +350,22 @@ to the detailed description below for a complete description. verb( -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 + -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 @@ -372,6 +373,7 @@ to the detailed description below for a complete description. verb( --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 @@ -379,8 +381,8 @@ to the detailed description below for a complete description. verb( --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 @@ -392,8 +394,8 @@ accepted: verb( --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() @@ -434,12 +436,13 @@ regardless of timestamp. This is useful when starting to use rsync after using another mirroring system which may not preserve timestamps exactly. -dit(bf(--modify-window)) When comparing two timestamps rsync treats -the timestamps as being equal if they are within the value of -modify_window. This is normally zero, but you may find it useful to -set this to a larger value in some situations. In particular, when -transferring to Windows FAT filesystems which cannot represent times -with a 1 second resolution bf(--modify-window=1) is useful. +dit(bf(--modify-window)) When comparing two timestamps, rsync treats the +timestamps as being equal if they differ by no more than the modify-window +value. This is normally 0 (for an exact match), but you may find it useful +to set this to a larger value in some situations. In particular, when +transferring to or from an MS Windows FAT filesystem (which represents +times with a 2-second resolution), bf(--modify-window=1) is useful +(allowing times to differ by up to 1 second). dit(bf(-c, --checksum)) This forces the sender to checksum all files using a 128-bit MD4 checksum before transfer. The checksum is then @@ -678,7 +681,9 @@ send the whole directory (e.g. "dir" or "dir/") without using a wildcard for the directory's contents (e.g. "dir/*") since the wildcard is expanded by the shell and rsync thus gets a request to transfer individual files, not the files' parent directory. Files that are excluded from transfer are -excluded from being deleted unless you use bf(--delete-excluded). +also excluded from being deleted unless you use the bf(--delete-excluded) +option or mark the rules as only matching on the sending side (see the +include/exclude modifiers in the FILTER RULES section). This option has no effect unless directory recursion is enabled. @@ -725,6 +730,9 @@ See bf(--delete) (which is implied) for more details on file-deletion. dit(bf(--delete-excluded)) In addition to deleting the files on the receiving side that are not on the sending side, this tells rsync to also delete any files on the receiving side that are excluded (see bf(--exclude)). +See the FILTER RULES section for a way to make individual exclusions behave +this way on the receiver, and for a way to protect files from +bf(--delete-excluded). See bf(--delete) (which is implied) for more details on file-deletion. dit(bf(--ignore-errors)) Tells bf(--delete) to go ahead and delete files @@ -903,6 +911,16 @@ scratch directory when creating temporary copies of the files 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 @@ -950,15 +968,14 @@ bf(--link-dest) from working properly for a non-root user when bf(-o) was specif (or implied by bf(-a)). You can work-around this bug by avoiding the bf(-o) option when sending to an old rsync. -dit(bf(-z, --compress)) With this option, rsync compresses any data from -the files that it sends to the destination machine. This -option is useful on slow connections. The compression method used is the -same method that gzip uses. +dit(bf(-z, --compress)) With this option, rsync compresses the file data +as it is sent to the destination machine, which reduces the amount of data +being transmitted -- something that is useful over a slow connection. -Note this this option typically achieves better compression ratios -that can be achieved by using a compressing remote shell, or a -compressing transport, as it takes advantage of the implicit -information sent for matching data blocks. +Note this this option typically achieves better compression ratios that can +be achieved by using a compressing remote shell or a compressing transport +because it takes advantage of the implicit information in the matching data +blocks that are not explicitly sent over the connection. dit(bf(--numeric-ids)) With this option rsync will transfer numeric group and user IDs rather than using user and group names and mapping them @@ -995,6 +1012,39 @@ 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)) Outputs a change-summary for each updated +item. The format is as follows: + +quote(tt( *XcstpogDL ITEM_NAME)) + +The bf(*) will be present if this is a file that is being transferred, +otherwise it will be replaced with a space. 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; if not the letter will be replaced +by either a "-" if no change is occurring, or a "+" if this is a new item. +The meanings of the attribute letters are 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 modified time is being updated to the server's + value (requires --times, but transferred files without --times will be + marked with a bf(T) because the time is updated to the transfer time). + it() A bf(p) means the permissions are being updated (requires + bf(--perms)). + it() An bf(o) means the owner is being updated (requires bf(--owner) and + root privileges). + it() A bf(g) means the group is being updated (requires bf(--group)). + it() A bf(D) means the device is being updated (requires bf(--devices) + and root privileges). + it() An bf(L) means the symlink value is being updated (requires + --links). +)) + 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 @@ -1010,23 +1060,24 @@ it is more desirable to keep partially transferred files. Using the bf(--partial) option tells rsync to keep the partial file which should make a subsequent transfer of the rest of the file much faster. -dit(bf(--partial-dir=DIR)) Turns on bf(--partial) mode, but tells rsync to -put a partially transferred file into em(DIR) instead of writing out the -file to the destination dir. Rsync will also use a file found in this -dir as data to speed up the transfer (i.e. when you redo the send after -rsync creates a partial file) and delete such a file after it has served -its purpose. Note that if bf(--whole-file) is specified (or implied) that an -existing partial-dir file will not be used to speedup the transfer (since +dit(bf(--partial-dir=DIR)) A better way to keep partial files than the +bf(--partial) option is to specify a em(DIR) that will be used to hold the +partial data (instead of writing it out to the destination file). +On the next transfer, rsync will use a file found in this +dir as data to speed up the resumption of the transfer and then deletes it +after it has served its purpose. +Note that if bf(--whole-file) is specified (or implied), any partial-dir +file that is found for a file that is being updated will simply be removed +(since rsync is sending files without using the incremental rsync algorithm). -Rsync will create the dir if it is missing (just the last dir -- not the -whole path). This makes it easy to use a relative path (such as -"bf(--partial-dir=.rsync-partial)") to have rsync create the partial-directory -in the destination file's directory (rsync will also try to remove the em(DIR) -if a partial file was found to exist at the start of the transfer and the -DIR was specified as a relative path). +Rsync will create the em(DIR) if it is missing (just the last dir -- not +the whole path). This makes it easy to use a relative path (such as +"bf(--partial-dir=.rsync-partial)") to have rsync create the +partial-directory in the destination file's directory when needed, and then +remove it again when the partial file is deleted. -If the partial-dir value is not an absolute path, rsync will also add an +If the partial-dir value is not an absolute path, rsync will also add a directory bf(--exclude) of this value at the end of all your existing excludes. This will prevent partial-dir files from being transferred and also prevent the untimely deletion of partial-dir items on the receiving side. An example: @@ -1035,7 +1086,8 @@ rule at the end of any other filter rules. Note that if you are supplying your own filter rules, you may need to manually insert a rule for this directory exclusion somewhere higher up in the list so that it has a high enough priority to be effective (e.g., if your rules specify -a trailing bf(--exclude='*') rule, the auto-added rule will be ineffective). +a trailing bf(--exclude='*') rule, the auto-added rule would never be +reached). IMPORTANT: the bf(--partial-dir) should not be writable by other users or it is a security risk. E.g. AVOID "/tmp". @@ -1051,13 +1103,22 @@ option does not look for this environment value is (1) when bf(--inplace) was specified (since bf(--inplace) conflicts with bf(--partial-dir)), or (2) when bf(--delay-updates) was specified (see below). +For the purposes of the server-config's "refuse options" setting, +bf(--partial-dir) does em(not) imply bf(--partial). This is so that a +refusal of the bf(--partial) option can be used to disallow the overwriting +of destination files with a partial transfer, while still allowing the +safer idiom provided by bf(--partial-dir). + dit(bf(--delay-updates)) This option puts the temporary file from each -updated file into the file's partial-dir (see above) until the end of the +updated file into a holding directory until the end of the transfer, at which time all the files are renamed into place in rapid succession. This attempts to make the updating of the files a little more -atomic. If you don't specify the bf(--partial-dir) option, this option will -cause it to default to ".~tmp~" (RSYNC_PARTIAL_DIR is not consulted for -this value). Conflicts with bf(--inplace). +atomic. By default the files are placed into a directory named ".~tmp~" in +each file's destination directory, but you can override this by specifying +the bf(--partial-dir) option. (Note that RSYNC_PARTIAL_DIR has no effect +on this value, nor is bf(--partial-dir) considered to be implied for the +purposes of the server-config's "refuse options" setting.) +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 @@ -1074,7 +1135,7 @@ parallel hierarchy of files). dit(bf(--progress)) This option tells rsync to print information showing the progress of the transfer. This gives a bored user something to watch. -Implies bf(--verbose) without incrementing verbosity. +Implies bf(--verbose) if it wasn't already specified. When the file is transferring, the data looks like this: @@ -1228,45 +1289,54 @@ Rsync builds an ordered list of filter rules as specified on the command-line. Filter rules have the following syntax: quote( -tt(x [PATTERN_OR_FILE])nl() -tt(xMODIFIERS [PATTERN_OR_FILE])nl() +tt(RULE [PATTERN_OR_FILENAME])nl() +tt(RULE,MODIFIERS [PATTERN_OR_FILENAME])nl() ) -The 'x' is a single-letter that specifies the kind of rule to create. It -can have trailing modifiers, and is separated from its arg by either a -single space or an underscore (_). Here are the available rule prefixes: +You have your choice of using either short or long RULE names, as described +below. If you use a short-named rule, the ',' separating the RULE from the +MODIFIERS is optional. The PATTERN or FILENAME that follows (when present) +must come after either a single space or an underscore (_). +Here are the available rule prefixes: quote( -bf(-) specifies an exclude pattern. nl() -bf(+) specifies an include pattern. nl() -bf(.) specifies a merge-file to read for more rules. nl() -bf(:) specifies a per-directory merge-file. nl() -bf(!) clears the current include/exclude list (takes no arg) nl() +bf(exclude, -) specifies an exclude pattern. nl() +bf(include, +) specifies an include pattern. nl() +bf(merge, .) specifies a merge-file to read for more rules. nl() +bf(dir-merge, :) specifies a per-directory merge-file. nl() +bf(hide, H) specifies a pattern for hiding files from the transfer. nl() +bf(show, S) files that match the pattern are not hidden. nl() +bf(protect, P) specifies a pattern for protecting files from deletion. nl() +bf(risk, R) files that match the pattern are not protected. nl() +bf(clear, !) clears the current include/exclude list (takes no arg) nl() ) +When rules are being read from a file, empty lines are ignored, as are +comment lines that start with a "#". + Note that the bf(--include)/bf(--exclude) command-line options do not allow the full range of rule parsing as described above -- they only allow the -specification of include/exclude patterns and the "!" token (not to -mention the comment lines when reading rules from a file). If a pattern +specification of include/exclude patterns plus a "!" token to clear the +list (and the normal comment parsing when rules are read from a file). +If a pattern does not begin with "- " (dash, space) or "+ " (plus, space), then the rule will be interpreted as if "+ " (for an include option) or "- " (for an exclude option) were prefixed to the string. A bf(--filter) option, on -the other hand, must always contain one of the prefixes above. +the other hand, must always contain either a short or long rule name at the +start of the rule. Note also that the bf(--filter), bf(--include), and bf(--exclude) options take one rule/pattern each. To add multiple ones, you can repeat the options on the command-line, use the merge-file syntax of the bf(--filter) option, or the bf(--include-from)/bf(--exclude-from) options. -When rules are being read from a file, empty lines are ignored, as are -comment lines that start with a "#". - manpagesection(INCLUDE/EXCLUDE PATTERN RULES) -You can include and exclude files by specifying patterns using the "+" and -"-" filter rules (as introduced in the FILTER RULES section above). These -rules specify a pattern that is matched against the names of the files -that are going to be transferred. These patterns can take several forms: +You can include and exclude files by specifying patterns using the "+", +"-", etc. filter rules (as introduced in the FILTER RULES section above). +The include/exclude rules each specify a pattern that is matched against +the names of the files that are going to be transferred. These patterns +can take several forms: itemize( it() if the pattern starts with a / then it is anchored to a @@ -1322,8 +1392,8 @@ tt(- *)nl() This fails because the parent directory "some" is excluded by the '*' rule, so rsync never visits any of the files in the "some" or "some/path" directories. One solution is to ask for all directories in the hierarchy -to be included by using a single rule: "+_*/" (put it somewhere before the -"-_*" rule). Another solution is to add specific include rules for all +to be included by using a single rule: "+ */" (put it somewhere before the +"- *" rule). Another solution is to add specific include rules for all the parent dirs that need to be visited. For instance, this set of rules works fine: @@ -1355,8 +1425,8 @@ itemize( manpagesection(MERGE-FILE FILTER RULES) You can merge whole files into your filter rules by specifying either a -"." or a ":" filter rule (as introduced in the FILTER RULES section -above). +merge (.) or a dir-merge (:) filter rule (as introduced in the FILTER RULES +section above). There are two kinds of merged files -- single-instance ('.') and per-directory (':'). A single-instance merge file is read one time, and @@ -1373,31 +1443,38 @@ below). Some examples: quote( +tt(merge /etc/rsync/default.rules)nl() tt(. /etc/rsync/default.rules)nl() -tt(: .per-dir-filter)nl() +tt(dir-merge .per-dir-filter)nl() +tt(dir-merge,n- .non-inherited-per-dir-excludes)nl() tt(:n- .non-inherited-per-dir-excludes)nl() ) -The following modifiers are accepted after a "." or ":": +The following modifiers are accepted after a merge or dir-merge rule: itemize( it() A bf(-) specifies that the file should consist of only exclude - patterns, with no other rule-parsing except for the list-clearing - token ("!"). + patterns, with no other rule-parsing except for in-file comments. it() A bf(+) specifies that the file should consist of only include - patterns, with no other rule-parsing except for the list-clearing - token ("!"). - it() A bf(C) is a shorthand for the modifiers bf(nw-), which makes the - parsing compatible with the way CVS parses their exclude files. If no - filename is specified, ".cvsignore" is assumed. - it() A bf(e) will exclude the merge-file from the transfer; e.g. - ":e_.rules" is like ":_.rules" and "-_.rules". + patterns, with no other rule-parsing except for in-file comments. + it() A bf(C) is a way to specify that the file should be read in a + CVS-compatible manner. This turns on 'n', 'w', and '-', but also + allows the list-clearing token (!) to be specified. If no filename is + provided, ".cvsignore" is assumed. + it() A bf(e) will exclude the merge-file name from the transfer; e.g. + "dir-merge,e .rules" is like "dir-merge .rules" and "- .rules". it() An bf(n) specifies that the rules are not inherited by subdirectories. it() A bf(w) specifies that the rules are word-split on whitespace instead of the normal line-splitting. This also turns off comments. Note: the space that separates the prefix from the rule is treated specially, so - "- foo + bar" is parsed as two rules (assuming that bf(-) or bf(+) was not - specified to turn off the parsing of prefixes). + "- foo + bar" is parsed as two rules (assuming that prefix-parsing wasn't + also disabled). + it() You may also specify any of the modifiers for the "+" or "-" rules + (below) in order to have the rules that are read-in from the file + default to having that modifier set. For instance, "merge,-/ .excl" would + treat the contents of .excl as absolute-path excludes, + while "dir-merge,s .filt" and ":sC" would each make all their + per-directory rules apply only on the server side. ) The following modifiers are accepted after a "+" or "-": @@ -1405,7 +1482,7 @@ The following modifiers are accepted after a "+" or "-": itemize( it() A "/" specifies that the include/exclude should be treated as an absolute path, relative to the root of the filesystem. For example, - "-/_/etc/passwd" would exclude the passwd file any time the transfer + "-/ /etc/passwd" would exclude the passwd file any time the transfer was sending files from the "/etc" directory. it() A "!" specifies that the include/exclude should take effect if the pattern fails to match. For instance, "-! */" would exclude all @@ -1413,30 +1490,41 @@ itemize( it() A bf(C) is used to indicate that all the global CVS-exclude rules should be inserted as excludes in place of the "-C". No arg should follow. + it() An bf(s) is used to indicate that the rule applies to the sending + side. When a rule affects the sending side, it prevents files from + being transferred. The default is for a rule to affect both sides + unless bf(--delete-excluded) was specified, in which case default rules + become sender-side only. See also the hide (H) and show (S) rules, + which are an alternate way to specify server-side includes/excludes. + it() An bf(r) is used to indicate that the rule applies to the receiving + side. When a rule affects the receiving side, it prevents files from + being deleted. See the bf(s) modifier for more info. See also the + protect (P) and risk (R) rules, which are an alternate way to + specify receiver-side includes/excludes. ) Per-directory rules are inherited in all subdirectories of the directory where the merge-file was found unless the 'n' modifier was used. Each subdirectory's rules are prefixed to the inherited per-directory rules from its parents, which gives the newest rules a higher priority than the -inherited rules. The entire set of per-dir rules is grouped together in +inherited rules. The entire set of dir-merge rules are grouped together in the spot where the merge-file was specified, so it is possible to override -per-dir rules via a rule that got specified earlier in the list of global +dir-merge rules via a rule that got specified earlier in the list of global rules. When the list-clearing rule ("!") is read from a per-directory file, it only clears the inherited rules for the current merge file. -Another way to prevent a single per-dir rule from being inherited is to +Another way to prevent a single rule from a dir-merge file from being inherited is to anchor it with a leading slash. Anchored rules in a per-directory merge-file are relative to the merge-file's directory, so a pattern "/foo" -would only match the file "foo" in the directory where the per-dir filter +would only match the file "foo" in the directory where the dir-merge filter file was found. Here's an example filter file which you'd specify via bf(--filter=". file":) quote( -tt(. /home/user/.global-filter)nl() +tt(merge /home/user/.global-filter)nl() tt(- *.gz)nl() -tt(: .rules)nl() +tt(dir-merge .rules)nl() tt(+ *.[ch])nl() tt(- *.o)nl() ) @@ -1475,13 +1563,12 @@ and only looks for the ".rsync-filter" files in each directory that is a part of the transfer. If you want to include the contents of a ".cvsignore" in your patterns, -you should use the rule ":C" -- this is a short-hand for the rule -":nw-_.cvsignore", and ensures that the .cvsignore file's contents are -interpreted according to the same parsing rules that CVS uses. You can +you should use the rule ":C", which creates a dir-merge of the .cvsignore +file, but parsed in a CVS-compatible manner. You can use this to affect where the bf(--cvs-exclude) (bf(-C)) option's inclusion of the -per-directory .cvsignore file gets placed into your rules by putting a +per-directory .cvsignore file gets placed into your rules by putting the ":C" wherever you like in your filter rules. Without this, rsync would -add the per-dir rule for the .cvsignore file at the end of all your other +add the dir-merge rule for the .cvsignore file at the end of all your other rules (giving it a lower priority than your command-line rules). For example: @@ -1706,10 +1793,10 @@ error. When reading a batch file, rsync will force the value of certain options to match the data in the batch file if you didn't set them to the same as the batch-writing command. Other options can (and should) be changed. -For instance -bf(--write-batch) changes to bf(--read-batch), bf(--files-from) is dropped, and the -bf(--filter)/bf(--include)/bf(--exclude) options are not needed unless one of the -bf(--delete) options is specified without bf(--delete-excluded). +For instance bf(--write-batch) changes to bf(--read-batch), +bf(--files-from) is dropped, and the +bf(--filter)/bf(--include)/bf(--exclude) options are not needed unless +one of the bf(--delete) options is specified. The code that creates the BATCH.sh file transforms any filter/include/exclude options into a single list that is appended as a "here" document to the