From 952d778bc1c7c0898345e20d4979bfdaaa31841b Mon Sep 17 00:00:00 2001 From: eoli3n Date: Sun, 11 Jun 2023 11:08:31 +0200 Subject: [PATCH 1/4] Improve patterns help --- src/borg/archiver.py | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/src/borg/archiver.py b/src/borg/archiver.py index 4400fc3f2..8d8cd9752 100644 --- a/src/borg/archiver.py +++ b/src/borg/archiver.py @@ -2311,12 +2311,11 @@ def do_break_lock(self, args, repository): currently active recursion root. You usually give the recursion root(s) when invoking borg and these can be either relative or absolute paths. - If you give `/absolute/` as root, the paths going into the matcher will - look relative like `absolute/.../file.ext`, because file paths in Borg - archives are always stored normalized and relative. This means that e.g. - ``borg create /path/to/repo ../some/path`` will store all files as - `some/path/.../file.ext` and ``borg create /path/to/repo /home/user`` - will store all files as `home/user/.../file.ext`. + Starting with Borg 1.2, paths that are matched against patterns always + appear relative. If you give ``/absolute/`` as root, the paths going + into the matcher will start with ``absolute/``. + If you give ``../../relative`` as root, the paths will be normalized + as ``relative/``. 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 @@ -2329,12 +2328,6 @@ def do_break_lock(self, args, repository): option. For commands that support patterns in their ``PATH`` argument like (``borg list``), the default pattern is path prefix. - Starting with Borg 1.2, discovered fs paths are normalised, have leading - slashes removed and then are matched against your patterns. - Note: You need to review your include / exclude patterns and make - sure they do not expect leading slashes. Borg can only deal with this - for some very simple patterns by removing leading slashes there also. - 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 non-default style is desired or when the desired pattern starts with From 3e8b0da8be62511db441ca60045c498c3a00183c Mon Sep 17 00:00:00 2001 From: eoli3n Date: Sun, 11 Jun 2023 11:09:41 +0200 Subject: [PATCH 2/4] improve patterns help: define a pattern style --- src/borg/archiver.py | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) diff --git a/src/borg/archiver.py b/src/borg/archiver.py index 8d8cd9752..37ccee1cd 100644 --- a/src/borg/archiver.py +++ b/src/borg/archiver.py @@ -2322,16 +2322,9 @@ def do_break_lock(self, args, repository): 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 ``--pattern`` - option. For commands that support patterns in their ``PATH`` argument - like (``borg list``), the default pattern is path prefix. - - 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 - non-default style is desired or when the desired pattern starts with - two alphanumeric characters followed by a colon (i.e. `aa:something/*`). + Borg supports different pattern styles. To define a non-default + style for a specific pattern, prefix it with two characters followed + by a colon ':' (i.e. ``fm:path/*``, ``sh:path/**``). `Fnmatch `_, selector `fm:` This is the default style for ``--exclude`` and ``--exclude-from``. From 099f23032e86608b235e6b363bc66c7962d4f3d5 Mon Sep 17 00:00:00 2001 From: eoli3n Date: Sun, 11 Jun 2023 11:12:49 +0200 Subject: [PATCH 3/4] improve patterns help: added pattern prefixes --- src/borg/archiver.py | 35 +++++++++++++++++++++++++++++------ 1 file changed, 29 insertions(+), 6 deletions(-) diff --git a/src/borg/archiver.py b/src/borg/archiver.py index 37ccee1cd..33f2b2c40 100644 --- a/src/borg/archiver.py +++ b/src/borg/archiver.py @@ -2434,12 +2434,35 @@ def do_break_lock(self, args, repository): EOF $ borg create --exclude-from exclude.txt backup / - 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. + 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, default pattern styles and + patterns for inclusion and exclusion. + + Root path prefix ``R`` + A recursion root path starts with the prefix ``R``, followed by a path + (a plain path, not a file pattern). Use this prefix to have the root + paths in the patterns file rather than as command line arguments. + + Pattern style prefix ``P`` + To change the default pattern style, use the ``P`` prefix, followed by + the pattern style abbreviation (``fm``, ``pf``, ``pp``, ``re``, ``sh``). + All patterns following this line will use this style until another style + is specified. + + Exclude pattern prefix ``-`` + Use the prefix ``-``, followed by a pattern, to define an exclusion. + This has the same effect as the ``--exclude`` option. + + Exclude no-recurse pattern prefix ``!`` + Use the prefix ``!``, followed by a pattern, to define an exclusion + that does not recurse into subdirectories. This saves time, but + prevents include patterns to match any files in subdirectories. + + Include pattern prefix ``+`` + Use the prefix ``+``, followed by a pattern, to define inclusions. + This is useful to include paths that are covered in an exclude + pattern and would otherwise not be backed up. .. note:: From 91547e98443d7e22d94458191378011ae005f56e Mon Sep 17 00:00:00 2001 From: eoli3n Date: Sun, 11 Jun 2023 11:14:24 +0200 Subject: [PATCH 4/4] improve patterns help: declarative includes sample --- src/borg/archiver.py | 28 +++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/src/borg/archiver.py b/src/borg/archiver.py index 33f2b2c40..bce7c226d 100644 --- a/src/borg/archiver.py +++ b/src/borg/archiver.py @@ -2470,11 +2470,29 @@ def do_break_lock(self, args, repository): 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. + The first matching pattern is used, so if an include pattern matches + before an exclude pattern, the file is backed up. Note that a no-recurse + exclude stops examination of subdirectories so that potential includes + will not match - use normal excludes for such use cases. + + Example:: + + # Define the recursion root + R / + # Exclude all iso files in any directory + - **/*.iso + # Explicitly include all inside etc and root + + etc/** + + root/** + # Exclude a specific directory under each user's home directories + - home/*/.cache + # Explicitly include everything in /home + + home/** + # Explicitly exclude some directories without recursing into them + ! re:^(dev|proc|run|sys|tmp) + # Exclude all other files and directories + # that are not specifically included earlier. + - ** .. note::