Exclude Patterns

Any number of items can be excluded from capture by creating an exclude pattern that describes the file and directory names to omit, using either glob (shell) name matching syntax or regular expressions.

Patterns can be added to an archive's settings, where they apply only to that archive. See archive settings:

pref_patterns_arch

Exclude patterns can also be attached to a folder, where they apply to all archives. See per-item capture preferences:

pref_patterns_dir

As an alternative, exclude patterns can also be stored in a special .qrecall_exclude_patterns.txt file.

Recalling folders containing excluded items Warning

QRecall remembers which items were excluded during the capture. If you later restore (overwrite) a folder that contained excluded items, then…

existing items are replaced by captured items
existing items that were excluded are unaltered
items that did not exist when the folder was captured are deleted

Simple Patterns

A simple pattern consists of three parts: an optional path, a single pattern (either a glob or regular expression), and a repetition option.

Simple patterns can be added to archive settings and the per-user capture preferences of folders; click the + button and choose either

New glob Pattern
New Regular Expression Pattern

Path

The path portion determines the target directory, or directories, where the pattern will be applied. The path can be absolute (Archive settings only) or relative. Absolute paths specify a specific directory on the volume, while relative paths target every directory ending with that path.

For example, the absolute path /Users/amber/Documents targets the following directory:

/Users/amber/Documents

In contrast, the relative path Library/Preferences targets all of these directories:

/Library/Preferences
/System/Library/Preferences
/Users/amber/Library/Preferences
/Users/guest/Library/Preferences
/Users/james/Library/Preferences
…

Entering an existing folder Tip

Pro Tip: to enter the path of an existing folder, click in the path field to edit it, then drag the target folder into the field.

If there is no path, the pattern is applied to the directory it is attached to. In the case the Archive settings, the pattern is applied to the volume's root directory.

Pattern

The pattern portion matches the item names within a target directory. It can be either a glob pattern or a regular expression.

Repetition

The repetition option (∞) applies the pattern to either the target directory only (off) or to the target directory and every subdirectory it contains (on).

Examples

Here are a couple of simple pattern examples:

/Users/amber/Documents // *.bak ∞ glob
Exclude every file with a .bak extension in amber's Documents folder, and every subfolder.

Library/Preferences // \.plist\.[a-zA-Z0-9]{6,8}+$ regex
In every Preferences folder contained inside a Library folder, exclude every file that ends in .plist. followed by between six and eight alphanumeric characters (names typical of preference semaphore files). This would exclude the file com.apple.calc.plist.PZ9lJQz, but not com.parallels.plist.sdb.

Complete Patterns

A complete (or "expert") pattern is a path-like construct that describes an arbitrary sequence of literal (name) components and pattern (matching) components. Complete patterns can express more complex matching rules than a simple pattern.

Complete patterns can be defined in the Archive settings or in per-folder capture preferences (choose Add "Expert" Pattern). Complete patterns can also be stored in a .qrecall_exclude_patterns.txt file, where they apply to the directory that contains the file.

.qrecall_exclude_patterns.txt Details

A .qrecall_exclude_patterns.txt file must be a plain text document using UTF-8 encoding.

Each line of text defines a complete pattern. Empty lines and invalid patterns are ignored.

Pattern components can be either glob or regular expressions, but you can't mix both in the same pattern.

Like components (literal/literal or pattern/pattern) are separated by a single /. A double // alternates between component types (literal//pattern or pattern//literal).

Simplified Pattern Railroad Diagram

Options

The final pattern component can (optionally) be a set of options. Options consist of a combination of:

A depth, indicating how many subdirectory levels the last component is applied to:
- 0 means the pattern is applied only to the directory the pattern specifies
- 1 means the pattern is applied to the directory, and its immediately subdirectories, but no deeper
- 2 means the directory, its subdirectories, and their subdirectories
- … and so on
- + means the last component is applied to all subdirectories (same as ∞)
:glob all pattern components are glob expressions
:re all pattern components are regular expressions

If the depth is omitted it defaults to 0. If the type is omitted it defaults to :glob.

Examples

Here are the simple pattern examples shown earlier, written as complete patterns (all simple patterns can be expressed as complete patterns):

/Users/amber/Documents//*.bak/+:glob

Library/Preferences//\.plist\.[a-zA-Z0-9]{6,8}+$/:re

Complete patterns can express an arbitrarily combination of literal and pattern components, as shown in this example:

/Users//*//Drop Box//*
Exclude the contents of the Drop Box folder from every user's home folder.
Note that the trailing options were omitted and defaulted to /0:glob.

The first component is assumed to be a literal. If you want the first component to be a pattern, start the pattern with // (or /// for an absolute path), as in:

//*.bak/+

Similarly, if the last component is literal, but you want to include options, end the pattern with //, as in:

.DS_Store//+

glob

Wikipedia has a good summary of the POSIX glob language

Regular Expressions

QRecall uses the ICU Regular Expression language with Unicode matching rules.

Pattern Notes

Exclusion patterns are independent of the exclude and exclude contents capture preferences, are not affected by the "Items Excluded by QRecall Capture Preferences" archive setting, and do not get logged.
QRecall enforces the rule that a glob pattern must explicitly match a leading period. In other words, the glob pattern *.lock will not match the file .invisible.lock.
Regular expressions are not anchored. If a regular expression matches any portion of an item's name it is considered a match. As an example, the regular expression \.doc will match both Sales.doc and Newly.doctored.jpg. To match the beginning, end, or entire item name, anchor the pattern using the ^ and/or $ operators: \.doc$
Literal, glob, and regular expression patterns are applied with the case sensitivity of the underlaying filesystem. If the filesystem is case insensitive, literal, glob, and regular expression patterns will use case-insensitive matching rules.
Literal components are just names that match (or not) a single item. They are not POSIX path elements (., .., and ~ have no special meaning), and they do not follow symbolic links.