|
|
@@ -24,10 +24,14 @@ patterns when matching archive content in commands like ``extract`` or
|
|
|
``mount``. Starting with Borg 1.2 this behaviour will be changed to
|
|
|
accept both absolute and relative paths.
|
|
|
|
|
|
+A directory exclusion pattern can end either with or without a slash ('/').
|
|
|
+If it ends with a slash, such as `some/path/`, the directory will be
|
|
|
+included but not its content. If it does not end with a slash, such as
|
|
|
+`some/path`, both the directory and content will be excluded.
|
|
|
+
|
|
|
File patterns support these styles: fnmatch, shell, regular expressions,
|
|
|
path prefixes and path full-matches. By default, fnmatch is used for
|
|
|
-``--exclude`` patterns and shell-style is used for the experimental
|
|
|
-``--pattern`` option.
|
|
|
+``--exclude`` patterns and shell-style is used for the ``--pattern`` option.
|
|
|
|
|
|
If followed by a colon (':') the first two characters of a pattern are
|
|
|
used as a style selector. Explicit style selection is necessary when a
|
|
|
@@ -140,60 +144,85 @@ Examples::
|
|
|
EOF
|
|
|
$ borg create --exclude-from exclude.txt backup /
|
|
|
|
|
|
-.. container:: experimental
|
|
|
-
|
|
|
- A more general and easier to use way to define filename matching patterns exists
|
|
|
- with the experimental ``--pattern`` and ``--patterns-from`` options. Using these, you
|
|
|
- may specify the backup roots (starting points) and patterns for inclusion/exclusion.
|
|
|
- A root path starts with the prefix `R`, followed by a path (a plain path, not a
|
|
|
- file pattern). An include rule starts with the prefix +, an exclude rule starts
|
|
|
- with the prefix -, an exclude-norecurse rule starts with !, all followed by a pattern.
|
|
|
-
|
|
|
- .. note::
|
|
|
-
|
|
|
- Via ``--pattern`` or ``--patterns-from`` you can define BOTH inclusion and exclusion
|
|
|
- of files using pattern prefixes ``+`` and ``-``. With ``--exclude`` and
|
|
|
- ``--exclude-from`` ONLY excludes are defined.
|
|
|
-
|
|
|
- Inclusion patterns are useful to include paths that are contained in an excluded
|
|
|
- path. The first matching pattern is used so if an include pattern matches before
|
|
|
- an exclude pattern, the file is backed up. If an exclude-norecurse pattern matches
|
|
|
- a directory, it won't recurse into it and won't discover any potential matches for
|
|
|
- include rules below that directory.
|
|
|
-
|
|
|
- Note that the default pattern style for ``--pattern`` and ``--patterns-from`` is
|
|
|
- shell style (`sh:`), so those patterns behave similar to rsync include/exclude
|
|
|
- patterns. The pattern style can be set via the `P` prefix.
|
|
|
-
|
|
|
- Patterns (``--pattern``) and excludes (``--exclude``) from the command line are
|
|
|
- considered first (in the order of appearance). Then patterns from ``--patterns-from``
|
|
|
- are added. Exclusion patterns from ``--exclude-from`` files are appended last.
|
|
|
-
|
|
|
- Examples::
|
|
|
-
|
|
|
- # backup pics, but not the ones from 2018, except the good ones:
|
|
|
- # note: using = is essential to avoid cmdline argument parsing issues.
|
|
|
- borg create --pattern=+pics/2018/good --pattern=-pics/2018 repo::arch pics
|
|
|
-
|
|
|
- # use a file with patterns:
|
|
|
- borg create --patterns-from patterns.lst repo::arch
|
|
|
-
|
|
|
- The patterns.lst file could look like that::
|
|
|
-
|
|
|
- # "sh:" pattern style is the default, so the following line is not needed:
|
|
|
- P sh
|
|
|
- R /
|
|
|
- # can be rebuild
|
|
|
- - /home/*/.cache
|
|
|
- # they're downloads for a reason
|
|
|
- - /home/*/Downloads
|
|
|
- # susan is a nice person
|
|
|
- # include susans home
|
|
|
- + /home/susan
|
|
|
- # don't backup the other home directories
|
|
|
- - /home/*
|
|
|
- # don't even look in /proc
|
|
|
- ! /proc
|
|
|
+A more general and easier to use way to define filename matching patterns exists
|
|
|
+with the ``--pattern`` and ``--patterns-from`` options. Using these, you may
|
|
|
+specify the backup roots (starting points) and patterns for inclusion/exclusion.
|
|
|
+A root path starts with the prefix `R`, followed by a path (a plain path, not a
|
|
|
+file pattern). An include rule starts with the prefix +, an exclude rule starts
|
|
|
+with the prefix -, an exclude-norecurse rule starts with !, all followed by a pattern.
|
|
|
+
|
|
|
+.. note::
|
|
|
+
|
|
|
+ Via ``--pattern`` or ``--patterns-from`` you can define BOTH inclusion and exclusion
|
|
|
+ of files using pattern prefixes ``+`` and ``-``. With ``--exclude`` and
|
|
|
+ ``--exclude-from`` ONLY excludes are defined.
|
|
|
+
|
|
|
+Inclusion patterns are useful to include paths that are contained in an excluded
|
|
|
+path. The first matching pattern is used so if an include pattern matches before
|
|
|
+an exclude pattern, the file is backed up. If an exclude-norecurse pattern matches
|
|
|
+a directory, it won't recurse into it and won't discover any potential matches for
|
|
|
+include rules below that directory.
|
|
|
+
|
|
|
+.. note::
|
|
|
+
|
|
|
+ It's possible that a sub-directory/file is matched while parent directories are not.
|
|
|
+ In that case, parent directories are not backed up thus their user, group, permission,
|
|
|
+ etc. can not be restored.
|
|
|
+
|
|
|
+Note that the default pattern style for ``--pattern`` and ``--patterns-from`` is
|
|
|
+shell style (`sh:`), so those patterns behave similar to rsync include/exclude
|
|
|
+patterns. The pattern style can be set via the `P` prefix.
|
|
|
+
|
|
|
+Patterns (``--pattern``) and excludes (``--exclude``) from the command line are
|
|
|
+considered first (in the order of appearance). Then patterns from ``--patterns-from``
|
|
|
+are added. Exclusion patterns from ``--exclude-from`` files are appended last.
|
|
|
+
|
|
|
+Examples::
|
|
|
+
|
|
|
+ # backup pics, but not the ones from 2018, except the good ones:
|
|
|
+ # note: using = is essential to avoid cmdline argument parsing issues.
|
|
|
+ borg create --pattern=+pics/2018/good --pattern=-pics/2018 repo::arch pics
|
|
|
+
|
|
|
+ # use a file with patterns:
|
|
|
+ borg create --patterns-from patterns.lst repo::arch
|
|
|
+
|
|
|
+The patterns.lst file could look like that::
|
|
|
+
|
|
|
+ # "sh:" pattern style is the default, so the following line is not needed:
|
|
|
+ P sh
|
|
|
+ R /
|
|
|
+ # can be rebuild
|
|
|
+ - /home/*/.cache
|
|
|
+ # they're downloads for a reason
|
|
|
+ - /home/*/Downloads
|
|
|
+ # susan is a nice person
|
|
|
+ # include susans home
|
|
|
+ + /home/susan
|
|
|
+ # also back up this exact file
|
|
|
+ + pf:/home/bobby/specialfile.txt
|
|
|
+ # don't backup the other home directories
|
|
|
+ - /home/*
|
|
|
+ # don't even look in /proc
|
|
|
+ ! /proc
|
|
|
+
|
|
|
+You can specify recursion roots either on the command line or in a patternfile::
|
|
|
+
|
|
|
+ # these two commands do the same thing
|
|
|
+ borg create --exclude /home/bobby/junk repo::arch /home/bobby /home/susan
|
|
|
+ borg create --patterns-from patternfile.lst repo::arch
|
|
|
+
|
|
|
+The patternfile::
|
|
|
+
|
|
|
+ # note that excludes use fm: by default and patternfiles use sh: by default.
|
|
|
+ # therefore, we need to specify fm: to have the same exact behavior.
|
|
|
+ P fm
|
|
|
+ R /home/bobby
|
|
|
+ R /home/susan
|
|
|
+
|
|
|
+ - /home/bobby/junk
|
|
|
+
|
|
|
+This allows you to share the same patterns between multiple repositories
|
|
|
+without needing to specify them on the command line.
|
|
|
|
|
|
.. _borg_placeholders:
|
|
|
|
Thomas Waldmann