From 89c0cd0af69c98ec1db854af9ce706c2c4bc429c Mon Sep 17 00:00:00 2001 From: Dan Helfman Date: Sat, 1 Nov 2025 21:18:22 -0700 Subject: [PATCH] Add documentation on patterns and excludes. --- .../configuration/patterns-and-excludes.md | 159 ++++++++++++++++++ 1 file changed, 159 insertions(+) create mode 100644 docs/reference/configuration/patterns-and-excludes.md diff --git a/docs/reference/configuration/patterns-and-excludes.md b/docs/reference/configuration/patterns-and-excludes.md new file mode 100644 index 00000000..6029f3d7 --- /dev/null +++ b/docs/reference/configuration/patterns-and-excludes.md @@ -0,0 +1,159 @@ +--- +title: Patterns and excludes +eleventyNavigation: + key: ⛔ Patterns and excludes + parent: ⚙️ Configuration +--- + +borgmatic's configuration has multiple options for specifying the source files +to include in your backups. Which of these options you use depends on how +complex your file matching needs are. + +## Source directories + +The `source_directories` option is the simplest way to specify the files and +directories to include in your backups. Globs (`*`) allow you to match multiple +paths at once, and tildes (`~`) get expanded to the current user's home +directory. Here's an example: + +```yaml +source_directories: + - /home + - /etc + - /var/log/syslog* + - /home/user/path with spaces + - ~/.config +``` + +## Excludes + +The `exclude_patterns` options lists particular paths to exclude from your +backups, paths that would otherwise get included by `source_directories`. Globs +and tildes are also supported here. Use quotes as needed. For example: + +```yaml +exclude_patterns: + - '*.pyc' + - '/home/*/.cache' + - '*/.vim*.tmp' + - /etc/ssl + - /home/user/path with spaces +``` + +See the [Borg patterns +documentation](https://borgbackup.readthedocs.io/en/stable/usage/help.html#borg-patterns) +for more details about the specific "fnmatch"-style syntax used by excludes. + +The `exclude_from` option is similar to `exclude_patterns`, but with your patterns +listed in an external file instead of directly within borgmatic's configuration. +Here's an example: + +```yaml +exclude_from: + - /etc/borgmatic/excludes +``` + +Also see the [borgmatic configuration +reference](https://torsion.org/borgmatic/reference/configuration/) for +additional exclude-related options. + + +## Patterns + +When you have more complex needs for including and excluding files to backup, +the `patterns` option is available. The definitive documentation on patterns is +the [Borg patterns +documentation](https://borgbackup.readthedocs.io/en/stable/usage/help.html#borg-patterns), +but here are the basics. + +First, unless you have `source_directories`, you need root patterns. In fact, +root patterns are just another way to specify the same paths as in +`source_directories`; they tell Borg the starting point for recursing into +directories to find files to backup. Root patterns are prefixed with "`R `". For +instance: + +```yaml +patterns: + - R /home + - R /etc +``` + +You can also add excludes and includes to your patterns. Excludes are prefixed +with "`- `". If you're defining these directly in the borgmatic's configuration +file, use quotes around the pattern. For example: + +```yaml +patterns: + - R /home + - '- /home/user/.cache' + - R /etc +``` + +How this works is that when Borg discovers a particular file path as it's +recursing into root directories, it tries to match that path against any +excludes and includes in your patterns *in order*, one at a time. If the first +match is to an exclude, then Borg excludes the file from the backup. But if the +first match is to an include, Borg includes it—even if there's a subsequent +exclude. + +The respective order of root patterns vs. exclude and include patterns doesn't +matter to Borg, so organize root patterns how you like. + +Here's an example of an include, which is prefixed with "`+ `": + +```yaml +patterns: + - R /home + - '+ /home/user/.cache/keep-me' + - '- /home/user/.cache' + - R /etc +``` + +This example excludes all of the `.cache` directory—except for the `keep-me` +subdirectory, which gets included since it's listed first. + +There's also a different kind of exclude pattern—a no-recurse exclude. That's +prefixed with "`! `" and tells Borg to not only exclude any matching paths but +also to ignore any subdirectories, saving file processing time. Here's an +example: + +```yaml +patterns: + - R /home + - '! /home/user/.cache' + - R /etc +``` + +The `patterns_from` option is similar to `patterns`, but with your patterns +listed in an external file instead of directly within borgmatic's configuration. +Here's an example: + +```yaml +patterns_from: + - /etc/borgmatic/patterns +``` + +## Debugging + +Under the hood, borgmatic actually converts `source_directories`, +`exclude_patterns`, and `exclude_from` values to Borg patterns and merges them +with any `patterns` and `patterns_from` values you've configured—passing the +resulting processed patterns to Borg. + +To see the combined patterns that borgmatic passes to Borg, run borgmatic with +[`--verbosity 2`](https://torsion.org/borgmatic/reference/command-line/logging/) +(and optionally `--dry-run`) and look for `Writing patterns to ...` in the +output. For instance: + +``` +repo: Writing patterns to /tmp/borgmatic-xzwb6s07/borgmatic/tmp61shymp0: +R /tmp/borgmatic-xzwb6s07/./borgmatic/sqlite_databases ++ /tmp/borgmatic-xzwb6s07/./borgmatic/sqlite_databases +R /home +R /etc +! fm:/home/.cache +``` + +You'll notice that borgmatic prepends your patterns with its own to support +use cases like streaming database dumps to Borg, creating filesystem snapshots, +saving bootstrap metadata, and so on.