-The exclude list is initialized to:
-
-quote(RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state
-.nse_depinfo *~ #* .#* ,* *.old *.bak *.BAK *.orig *.rej .del-*
-*.a *.o *.obj *.so *.Z *.elc *.ln core)
-
-then files listed in a $HOME/.cvsignore are added to the list and any
-files listed in the CVSIGNORE environment variable (space delimited).
-
-Finally in each directory any files listed in the .cvsignore file in
-that directory are added to the list.
-
-dit(bf(--suffix SUFFIX)) This option allows you to override the default
-backup suffix used with the -b option. The default is a ~.
-
-dit(bf(--csum-length LENGTH)) By default the primary checksum used in
-rsync is a very strong 16 byte MD4 checksum. In most cases you will
-find that a truncated version of this checksum is quite efficient, and
-this will decrease the size of the checksum data sent over the link,
-making things faster.
-
-You can choose the number of bytes in the truncated checksum using the
---csum-length option. Any value less than or equal to 16 is valid.
-
-Note that if you use this option then you run the risk of ending up
-with an incorrect target file. The risk with a value of 16 is
-microscopic and can be safely ignored (the universe will probably end
-before it fails) but with smaller values the risk is higher.
-
-Current versions of rsync actually use an adaptive algorithm for the
-checksum length by default, using a 16 byte file checksum to determine
-if a 2nd pass is required with a longer block checksum. Only use this
-option if you have read the source code and know what you are doing.
-
-dit(bf(-T, --temp-dir DIR)) This option instructs rsync to use DIR as a
-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(--compare-dest DIR)) This option instructs rsync to use DIR as an
-additional directory to compare destination files against when doing
-transfers. 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 transfered (for example by moving directories
-around and removing the old directory). This option increases the
-usefulness of --partial because partially transferred files will remain in
-the new temporary destination until they have a chance to be completed.
-If DIR is a relative path, it is relative to the destination directory.
-
-dit(bf(-z, --compress)) With this option, rsync compresses any data from
-the source file(s) which it sends to the destination machine. This
-option is useful on slow links. The compression method used is the
-same method that gzip uses.
-
-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.
+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/ .bzr/)))
+
+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).
+
+Finally, any file is ignored if it is in the same directory as a
+.cvsignore file and matches one of the patterns listed therein. Unlike
+rsync's filter/exclude files, these patterns are split on whitespace.
+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 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
+bf(--filter=:C) and bf(--filter=-C) (either on your command-line or by
+putting the ":C" and "-C" rules into a filter file with your other rules).
+The first option turns on the per-directory scanning for the .cvsignore
+file. The second option does a one-time import of the CVS excludes
+mentioned above.
+
+dit(bf(-f, --filter=RULE)) This option allows you to add rules to selectively
+exclude certain files from the list of files to be transferred. This is
+most useful in combination with a recursive transfer.
+
+You may use as many bf(--filter) options on the command line as you like
+to build up the list of files to exclude.
+
+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='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='exclude .rsync-filter'))
+
+This filters out the .rsync-filter files themselves from the transfer.
+
+See the FILTER RULES section for detailed information on how these options
+work.
+
+dit(bf(--exclude=PATTERN)) This option is a simplified form of the
+bf(--filter) option that defaults to an exclude rule and does not allow
+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 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
+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 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 bf(-)
+for standard input). It also tweaks the default behavior of rsync to make
+transferring just the specified files and directories easier:
+
+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).
+ 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 (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 filenames that are read from the FILE are all relative to the
+source dir -- any leading slashes are removed and no ".." references are
+allowed to go higher than the source dir. For example, take this
+command:
+
+quote(tt( rsync -a --files-from=/tmp/foo /usr remote:/backup))
+
+If /tmp/foo contains the string "bin" (or even "/bin"), the /usr/bin
+directory will be created as /backup/bin on the remote host. If it
+contains "bin/" (note the trailing slash), the immediate contents of
+the directory would also be sent (without needing to be explicitly
+mentioned in the file -- this began in version 2.6.4). In both cases,
+if the bf(-r) option was enabled, that dir's entire hierarchy would
+also be transferred (keep in mind that bf(-r) needs to be specified
+explicitly with bf(--files-from), since it is not implied by bf(-a)).
+Also note
+that the effect of the (enabled by default) bf(--relative) option is to
+duplicate only the path info that is read from the file -- it does not
+force the duplication of the source-spec path (/usr in this case).
+
+In addition, the bf(--files-from) file can be read from the remote host
+instead of the local host if you specify a "host:" in front of the file
+(the host must match one end of the transfer). As a short-cut, you can
+specify just a prefix of ":" to mean "use the remote end of the
+transfer". For example:
+
+quote(tt( rsync -a --files-from=:/path/file-list src:/ /tmp/copy))
+
+This would copy all the files specified in the /path/file-list file that
+was located on the remote "src" host.
+
+dit(bf(-0, --from0)) This tells rsync that the rules/filenames it reads from a
+file are terminated by a null ('\0') character, not a NL, CR, or CR+LF.
+This affects bf(--exclude-from), bf(--include-from), bf(--files-from), and any
+merged files specified in a bf(--filter) rule.
+It does not affect bf(--cvs-exclude) (since all names read from a .cvsignore
+file are split on whitespace).
+
+dit(bf(-T, --temp-dir=DIR)) This option instructs rsync to use DIR as a
+scratch directory when creating temporary copies of the files transferred
+on the receiving side. The default behavior is to create each temporary
+file in the same directory as the associated destination file.
+
+This option is most often used when the receiving disk partition does not
+have enough free space to hold a copy of the largest file in the transfer.
+In this case (i.e. when the scratch directory in on a different disk
+partition), rsync will not be able to rename each received temporary file
+over the top of the associated destination file, but instead must copy it
+into place. Rsync does this by copying the file over the top of the
+destination file, which means that the destination file will contain
+truncated data during this copy. If this were not done this way (even if
+the destination file were first removed, the data locally copied to a
+temporary file in the destination directory, and then renamed into place)
+it would be possible for the old file to continue taking up disk space (if
+someone had it open), and thus there might not be enough room to fit the
+new version on the disk at the same time.
+
+If you are using this option for reasons other than a shortage of disk
+space, you may wish to combine it with the bf(--delay-updates) option,
+which will ensure that all copied files get put into subdirectories in the
+destination hierarchy, awaiting the end of the transfer. If you don't
+have enough room to duplicate all the arriving files on the destination
+partition, another way to tell rsync that you aren't overly concerned
+about disk space is to use the bf(--partial-dir) option with a relative
+path; because this tells rsync that it is OK to stash off a copy of a
+single file in a subdir in the destination hierarchy, rsync will use the
+partial-dir as a staging area to bring over the copied file, and then
+rename it into place from there. (Specifying a bf(--partial-dir) with
+an absolute path does not have this side-effect.)
+
+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
+directory). If a file is found in em(DIR) that is identical to the
+sender's file, the file will NOT be transferred to the destination
+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, 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 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).
+
+dit(bf(--link-dest=DIR)) This option behaves like bf(--copy-dest), but
+unchanged files are hard linked from em(DIR) to the destination directory.
+The files must be identical in all preserved attributes (e.g. permissions,
+possibly ownership) in order for the files to be linked together.
+An example:
+
+quote(tt( rsync -av --link-dest=$PWD/prior_dir host:src_dir/ new_dir/))
+
+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.
+
+This option works best when copying into an empty destination hierarchy, as
+rsync treats existing files as definitive (so it never looks in the link-dest
+dirs when a destination file already exists), and as malleable (so it might
+change the attributes of a destination file, which affects all the hard-linked
+versions).
+
+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).
+
+Note that rsync versions prior to 2.6.1 had a bug that could prevent
+bf(--link-dest) from working properly for a non-super-user when bf(-o) was
+specified (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 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 that this option typically achieves better compression ratios than 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.
+
+See the bf(--skip-compress) option for the default list of file suffixes
+that will not be compressed.
+
+dit(bf(--compress-level=NUM)) Explicitly set the compression level to use
+(see bf(--compress)) instead of letting it default. If NUM is non-zero,
+the bf(--compress) option is implied.
+
+dit(bf(--skip-compress=LIST)) Override the list of file suffixes that will
+not be compressed. The bf(LIST) should be one or more file suffixes
+(without the dot) separated by slashes (/).
+
+You may specify an empty string to indicate that no file should be skipped.
+
+Simple character-class matching is supported: each must consist of a list
+of letters inside the square brackets (e.g. no special classes, such as
+"[:alpha:]", are supported).
+
+The characters asterisk (*) and question-mark (?) have no special meaning.
+
+Here's an example that specifies 6 suffixes to skip (since 1 of the 5 rules
+matches 2 suffixes):
+
+verb( --skip-compress=gz/jpg/mp[34]/7z/bz2)
+
+The default list of suffixes that will not be compressed is this (several
+of these are newly added for 3.0.0):
+
+verb( gz/zip/z/rpm/deb/iso/bz2/t[gb]z/7z/mp[34]/mov/avi/ogg/jpg/jpeg)
+
+This list will be replaced by your bf(--skip-compress) list in all but one
+situation: a copy from a daemon rsync will add your skipped suffixes to
+its list of non-compressing files (and its list may be configured to a
+different default).