Replace boost::scoped_ptr with std::unique_ptr.
[cumulus.git] / 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