doc/exclude.rst

   1 Cumulus File Selection (Includes/Excludes)
   2 ==========================================
   3
   4 A backup tool should support a flexible mechanism for selecting which
   5 files should be included in or excluded from the backup.  This file
   6 describes the mechanism used by Cumulus.  It is loosely based on the
   7 mechanism used by rsync, though greatly simplified, and it allows for
   8 users to specify include/exclude rules on a per-directory basis (if
   9 enabled when running a backup).
  10
  11 Cumulus will back up, recursively, each of the files or directories
  12 specified on the command-line, subject to include/exclude rules which
  13 may cause some files to be skipped.  Each file is matched against the
  14 list of rules in sequence.  The first rule which matches determines
  15 whether the file should be included or excluded--thus, more specific
  16 rules should be listed before more general rules.
  17
  18 There are four types of rules, modeled after those in rsync:
  19
  20 exclude (``-``)
  21     matches files which should not be backed up
  22
  23 include (``+``)
  24     matches files to be backed up (even if a later exclude rule would
  25     match)
  26
  27 dir-merge (``:``)
  28     specify a file which, if found in a directory during the backup
  29     process, will be read to insert additional rules for that directory
  30     and its subdirectories
  31
  32 merge (``.``)
  33     immediately read a file containing additional rules and insert those
  34     in the current ruleset **(not yet implemented)**
  35
  36 Patterns found in the rules are interpreted as follows:
  37
  38 - Most characters are treated literally and must match exactly.
  39 - A ``*`` matches zero or more characters, but not ``/``.
  40 - A ``**`` matches zero or more characters, including ``/``.
  41 - A ``?`` matches any single character, except for ``/``.
  42 - A pattern starting with a ``/`` is matched against the complete path
  43   to the file.  A pattern without a leading ``/`` can match any suffix
  44   of the directory components.
  45 - A pattern ending in a ``/`` matches directories only.
  46
  47 Note that dotfiles are not considered specially by these rules: a
  48 pattern of "*" matches all files in a directory, including those
  49 starting with a '.'.  This is different from the handling of the shell.
  50
  51 Merged Patterns
  52 ---------------
  53
  54 If a file matching a dir-merge rule is encountered, that file is parsed
  55 to yield additional filter rules; those filter rules are inserted
  56 immediately after the dir-merge rule, then removed when leaving the
  57 directory containing the dir-merge file.
  58
  59 Blank lines and lines beginning with ``#`` in the file are ignored.
  60 Otherwise, lines should consist of a single character indicating the
  61 rule type (``+``, ``-``, or ``:`` for include, exclude, or dir-merge), a
  62 space, and a file pattern.
  63
  64 Any patterns added by a dir-merge rule are matched relative to the
  65 directory with the patterns file: so, for example, a pattern
  66 "``+ /file.txt``" would match ``file.txt`` in the same directory as the
  67 merge file, not at the root.
  68
  69 Example
  70 -------
  71
  72 Suppose that cumulus is launched with a single filter argument:
  73 ``--dir-merge=/.cumulus-root-filter``.
  74
  75 ``/.cumulus-root-filter``::
  76
  77     # Ignore pseudo-filesystems and temporary directories
  78     - /proc/
  79     - /sys/
  80     # Exclude anywhere directories named tmp (except /var/tmp).
  81     # Files named tmp will still be included.
  82     + /var/tmp/
  83     - tmp/
  84     # Merge any user-provided rules in a file named .cumulus-filter here
  85     : .cumulus-filter
  86     # Ignore backup files anywhere in the file system
  87     - *~
  88     - *.bak
  89     # Ignore per-user cache directories
  90     - /home/*/.cache/
  91
  92 ``/home/user/.cumulus-filter``::
  93
  94     # Ignore the /home/user/scratch directory
  95     - /scratch/
  96     # Ignore vim swap files (in /home/user only)
  97     - .*.swp
  98     # Do keep backup files (overrides the global exclude rule)
  99     + *~
 100     # This rule ineffective: the top-level tmp/ rule has a higher precedence
 101     + tmp/
 102
 103 ``/home/user/workspace/.cumulus-filter``::
 104
 105     # Exclude backup files again in /home/user/workspace: this has a
 106     # higher precedence than the rules in /home/user/.cumulus-filter
 107     - *~
 108