X-Git-Url: https://mattmccutchen.net/rsync/rsync.git/blobdiff_plain/5e1f082d0c0af5fdb8096023772eb4f5013f78a0..42c6b139019f7417a5067cdb93ad3f2452a69e7c:/rsync.yo diff --git a/rsync.yo b/rsync.yo index 9acfc238..b4fcb261 100644 --- a/rsync.yo +++ b/rsync.yo @@ -1,5 +1,5 @@ mailto(rsync-bugs@samba.org) -manpage(rsync)(1)(22 Apr 2006)()() +manpage(rsync)(1)(6 Nov 2006)()() manpagename(rsync)(faster, flexible replacement for rcp) manpagesynopsis() @@ -33,7 +33,7 @@ report that accompanies this package. Some of the additional features of rsync are: -itemize( +itemization( it() support for copying links, devices, owners, groups, and permissions it() exclude and exclude-from options similar to GNU tar it() a CVS exclude mode for ignoring the same files that CVS would ignore @@ -182,7 +182,7 @@ CONNECTIONS section below for information on that.) Using rsync in this way is the same as using it with a remote shell except that: -itemize( +itemization( 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 of the "path" is actually a module name. @@ -299,6 +299,7 @@ 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 + --no-motd suppress daemon-mode MOTD (see caveat) -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) @@ -321,7 +322,7 @@ to the detailed description below for a complete description. verb( -H, --hard-links preserve hard links -p, --perms preserve permissions -E, --executability preserve executability - --chmod=CHMOD change destination permissions + --chmod=CHMOD affect file and/or directory permissions -o, --owner preserve owner (super-user only) -g, --group preserve group --devices preserve device files (super-user only) @@ -344,6 +345,7 @@ to the detailed description below for a complete description. verb( --delete delete extraneous files from dest dirs --delete-before receiver deletes before transfer (default) --delete-during receiver deletes during xfer, not before + --delete-delay find deletions during, delete after --delete-after receiver deletes after transfer, not before --delete-excluded also delete excluded files from dest dirs --ignore-errors delete even if there are I/O errors @@ -390,7 +392,7 @@ to the detailed description below for a complete description. verb( --out-format=FORMAT output updates using the specified FORMAT --log-file=FILE log what we're doing to the specified FILE --log-file-format=FMT log updates using the specified FMT - --password-file=FILE read password from FILE + --password-file=FILE read daemon-access password from FILE --list-only list the files instead of copying them --bwlimit=KBPS limit I/O bandwidth; KBytes per second --write-batch=FILE write a batched update to FILE @@ -401,8 +403,7 @@ to the detailed description below for a complete description. verb( -4, --ipv4 prefer IPv4 -6, --ipv6 prefer IPv6 --version print version number -(-h) --help show this help (see below for -h comment) -) +(-h) --help show this help (see below for -h comment)) Rsync can also be run as a daemon, in which case the following options are accepted: verb( @@ -418,8 +419,7 @@ accepted: verb( -v, --verbose increase verbosity -4, --ipv4 prefer IPv4 -6, --ipv6 prefer IPv6 - -h, --help show this help (if used after --daemon) -) + -h, --help show this help (if used after --daemon)) manpageoptions() @@ -459,9 +459,17 @@ are given during the transfer, notably suppressing information messages from the remote server. This flag is useful when invoking rsync from cron. +dit(bf(--no-motd)) This option affects the information that is output +by the client at the start of a daemon transfer. This suppresses the +message-of-the-day (MOTD) text, but it also affects the list of modules +that the daemon sends in response to the "rsync host::" request (due to +a limitation in the rsync protocol), so omit this option if you want to +request the list of modules from the deamon. + dit(bf(-I, --ignore-times)) Normally rsync will skip any files that are already the same size and have the same modification time-stamp. -This option turns off this "quick check" behavior. +This option turns off this "quick check" behavior, causing all files to +be updated. dit(bf(--size-only)) Normally rsync will not transfer any files that are already the same size and have the same modification time-stamp. With the @@ -603,7 +611,7 @@ Note that if you don't specify bf(--backup-dir), (1) the bf(--omit-dir-times) option will be implied, and (2) if bf(--delete) is also in effect (without bf(--delete-excluded)), rsync will add a "protect" filter-rule for the backup suffix to the end of all your existing excludes -(e.g. -f "P *~"). This will prevent previously backed-up files from being +(e.g. bf(-f "P *~")). This will prevent previously backed-up files from being deleted. Note that if you are supplying your own filter rules, you may need to manually insert your own exclude/protect rule somewhere higher up in the list so that it has a high enough priority to be effective (e.g., if @@ -611,8 +619,8 @@ your rules specify a trailing inclusion/exclusion of '*', the auto-added rule would never be reached). 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 -very useful for incremental backups. You can additionally +tells rsync to store all backups in the specified directory on the receiving +side. This can be used for incremental backups. You can additionally specify a backup suffix using the bf(--suffix) option (otherwise the files backed up in the specified directory will keep their original filenames). @@ -741,7 +749,7 @@ be the source permissions.) When this option is em(off), permissions are set as follows: -quote(itemize( +quote(itemization( it() Existing files (including updated files) retain their existing permissions, though the bf(--executability) option might change just the execute permission for the file. @@ -788,7 +796,7 @@ not enabled. A regular file is considered to be executable if at least one executability differs from that of the corresponding source file, rsync modifies the destination file's permissions as follows: -quote(itemize( +quote(itemization( it() To make a file non-executable, rsync turns off all its 'x' permissions. it() To make a file executable, rsync turns on each 'x' permission that @@ -970,6 +978,12 @@ a faster method than choosing the before- or after-transfer algorithm, but it is only supported beginning with rsync version 2.6.4. See bf(--delete) (which is implied) for more details on file-deletion. +dit(bf(--delete-delay)) Request that the file-deletions on the receiving +side be computed incrementally as the transfer happens, and then removed +after the transfer completes. A temporary file will be created on the +receiving side to hold the names, but it is removed while open, so you +won't see it during the transfer. + dit(bf(--delete-after)) Request that the file-deletions on the receiving side be done after the transfer has completed. This is useful if you are sending new per-directory merge files as a part of the transfer and @@ -997,7 +1011,12 @@ using bf(--delete-after), and it used to be non-functional unless the bf(--recursive) option was also enabled. dit(bf(--max-delete=NUM)) This tells rsync not to delete more than NUM -files or directories (NUM must be non-zero). +files or directories. +Beginning with version 3.0.0, you may specify bf(--max-delete=0) to +be warned about any extraneous files in the destination, but be very +careful to never specify a 0 value to an older rsync client, or the +option will be silently ignored. (A 3.0.0 client will die with an +error if the remote rsync is not new enough to handle the situation.) This is useful when mirroring very large trees to prevent disasters. dit(bf(--max-size=SIZE)) This tells rsync to avoid transferring any @@ -1074,16 +1093,17 @@ 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 -systems. It uses the same algorithm that CVS uses to determine if +systems. It uses a similar algorithm to CVS to determine if a file should be ignored. -The exclude list is initialized to: +The exclude list is initialized to exclude the following items (these +initial items are marked as perishable -- see the FILTER RULES section): quote(quote(tt(RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state .nse_depinfo *~ #* .#* ,* _$* *$ *.old *.bak *.BAK *.orig *.rej -.del-* *.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln core .svn/))) +.del-* *.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln core .svn/ .bzr/))) -then files listed in a $HOME/.cvsignore are added to the list and any +then, files listed in a $HOME/.cvsignore are added to the list and any files listed in the CVSIGNORE environment variable (all cvsignore names are delimited by whitespace). @@ -1157,7 +1177,7 @@ 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( +quote(itemization( 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) or bf(--no-R) if you want to turn that off). @@ -1302,6 +1322,11 @@ 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. +Note that if you combine this option with bf(--ignore-times), rsync will not +link any files together because it only links identical files together as a +substitute for transferring the file, never as an additional check after the +file is updated. + If em(DIR) is a relative path, it is relative to the destination directory. See also bf(--compare-dest) and bf(--copy-dest). @@ -1385,7 +1410,7 @@ modified. The update types that replace the bf(Y) are as follows: -quote(itemize( +quote(itemization( it() A bf(<) means that a file is being transferred to the remote host (sent). it() A bf(>) means that a file is being transferred to the local host @@ -1411,7 +1436,7 @@ a "?" (this can happen when talking to an older rsync). The attribute that is associated with each letter is as follows: -quote(itemize( +quote(itemization( it() A bf(c) means the checksum of the file is different and will be updated by the file transfer (requires bf(--checksum)). it() A bf(s) means the size of the file is different and will be updated @@ -1486,7 +1511,7 @@ 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 algorithm is for your data. -The current statistics are as follows: quote(itemize( +The current statistics are as follows: quote(itemization( it() bf(Number of files) is the count of all "files" (in the generic sense), which includes directories, symlinks, etc. it() bf(Number of files transferred) is the count of normal files that @@ -1651,7 +1676,7 @@ that any superfluous files and directories in the destination are removed quote( rsync -avm --del --include='*.pdf' -f 'hide,! */' src/ dest) If you didn't want to remove superfluous destination files, the more -time-honored options of "--include='*/' --exclude='*'" would work fine +time-honored options of "bf(--include='*/' --exclude='*')" would work fine in place of the hide-filter (if that is more natural to you). dit(bf(--progress)) This option tells rsync to print information @@ -1692,12 +1717,14 @@ dit(bf(-P)) The bf(-P) option is equivalent to bf(--partial) bf(--progress). It purpose is to make it much easier to specify these two options for a long transfer that may be interrupted. -dit(bf(--password-file)) This option allows you to provide a password -in a file for accessing a remote rsync daemon. Note that this option -is only useful when accessing an rsync daemon using the built in -transport, not when using a remote shell as the transport. The file -must not be world readable. It should contain just the password as a -single line. +dit(bf(--password-file)) This option allows you to provide a password in a +file for accessing an rsync daemon. The file must not be world readable. +It should contain just the password as a single line. + +When accessing an rsync daemon using a remote shell as the transport, this +option only comes into effect after the remote shell finishes its +authentication (i.e. if you have also specified a password in the daemon's +config file). dit(bf(--list-only)) This option will cause the source files to be listed instead of transferred. This option is inferred if there is a single source @@ -1913,7 +1940,7 @@ 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( +itemization( it() if the pattern starts with a / then it is anchored to a particular spot in the hierarchy of files, otherwise it is matched against the end of the pathname. This is similar to a leading ^ in @@ -1950,8 +1977,8 @@ itemize( down.) it() a trailing "dir_name/***" will match both the directory (as if "dir_name/" had been specified) and all the files in the directory - (as if "dir_name/**" had been specified). (This behavior is new for - version 2.6.7.) + (as if "dir_name/**" had been specified). This behavior was added in + version 2.6.7. ) Note that, when using the bf(--recursive) (bf(-r)) option (which is implied by @@ -1991,7 +2018,7 @@ tt(- *)nl() Here are some examples of exclude/include matching: -itemize( +itemization( it() "- *.o" would exclude all filenames matching *.o it() "- /foo" would exclude a file (or directory) named foo in the transfer-root directory @@ -2038,7 +2065,7 @@ tt(:n- .non-inherited-per-dir-excludes)nl() The following modifiers are accepted after a merge or dir-merge rule: -itemize( +itemization( it() A bf(-) specifies that the file should consist of only exclude patterns, with no other rule-parsing except for in-file comments. it() A bf(+) specifies that the file should consist of only include @@ -2065,14 +2092,14 @@ itemize( The following modifiers are accepted after a "+" or "-": -itemize( - it() A "/" specifies that the include/exclude rule should be matched +itemization( + it() A bf(/) specifies that the include/exclude rule should be matched against the absolute pathname of the current item. For example, "-/ /etc/passwd" would exclude the passwd file any time the transfer was sending files from the "/etc" directory, and "-/ subdir/foo" would always exclude "foo" when it is in a dir named "subdir", even if "foo" is at the root of the current transfer. - it() A "!" specifies that the include/exclude should take effect if + it() A bf(!) specifies that the include/exclude should take effect if the pattern fails to match. For instance, "-! */" would exclude all non-directories. it() A bf(C) is used to indicate that all the global CVS-exclude rules @@ -2089,6 +2116,11 @@ itemize( 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. + it() A bf(p) indicates that a rule is perishable, meaning that it is + ignored in directories that are being deleted. For instance, the bf(-C) + option's default rules that exclude things like "CVS" and "*.o" are + marked as perishable, and will not prevent a directory that was removed + on the source from being deleted on the destination. ) Per-directory rules are inherited in all subdirectories of the directory @@ -2176,7 +2208,7 @@ that follow the :C instead of being subservient to all your rules. To affect the other CVS exclude rules (i.e. the default list of exclusions, the contents of $HOME/.cvsignore, and the value of $CVSIGNORE) you should omit the bf(-C) command-line option and instead insert a "-C" rule into -your filter rules; e.g. "--filter=-C". +your filter rules; e.g. "bf(--filter=-C)". manpagesection(LIST-CLEARING FILTER RULE) @@ -2340,7 +2372,7 @@ and the information to repeat this operation is stored in "foo" and into the directory /bdest/dir. The differences between the two examples reveals some of the flexibility you have in how you deal with batches: -itemize( +itemization( it() The first example shows that the initial copy doesn't have to be local -- you can push or pull data to/from a remote host using either the remote-shell syntax or rsync daemon syntax, as desired. @@ -2422,7 +2454,7 @@ unsafe links to be omitted altogether. (Note that you must specify bf(--links) for bf(--safe-links) to have any effect.) Symbolic links are considered unsafe if they are absolute symlinks -(start with bf(/)), empty, or if they contain enough bf("..") +(start with bf(/)), empty, or if they contain enough ".." components to ascend from the directory being copied. Here's a summary of how the symlink options are interpreted. The list is @@ -2544,7 +2576,7 @@ url(http://rsync.samba.org/)(http://rsync.samba.org/) manpagesection(VERSION) -This man page is current for version 2.6.8 of rsync. +This man page is current for version 2.6.9 of rsync. manpagesection(INTERNAL OPTIONS)