From 2cdf0df14d6f5a607e1e1a1977f8cddd7772a2ae Mon Sep 17 00:00:00 2001 From: bobthebadguy Date: Mon, 7 Feb 2022 11:53:25 -0800 Subject: [PATCH 1/2] Clarify usage of patternfile roots (#6242) --- src/borg/archiver.py | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/src/borg/archiver.py b/src/borg/archiver.py index 9f3e35240..543c74c92 100644 --- a/src/borg/archiver.py +++ b/src/borg/archiver.py @@ -2429,10 +2429,31 @@ class Archiver: # 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\n\n''') + ! /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.\n\n''') helptext['placeholders'] = textwrap.dedent(''' Repository (or Archive) URLs, ``--prefix``, ``--glob-archives``, ``--comment`` and ``--remote-path`` values support these placeholders: From 8bba72b3aace2d6e3c0f2e01b98901367170ac03 Mon Sep 17 00:00:00 2001 From: Andrey Bienkowski Date: Tue, 8 Feb 2022 18:02:05 +0300 Subject: [PATCH 2/2] Fix indentation This fixes an indentation error in src/borg/archiver.py that caused the HTML help to look bad (the tail end of the page ended up *inside* of a code block instead of after it) --- src/borg/archiver.py | 122 +++++++++++++++++++++---------------------- 1 file changed, 61 insertions(+), 61 deletions(-) diff --git a/src/borg/archiver.py b/src/borg/archiver.py index 543c74c92..fa02f037e 100644 --- a/src/borg/archiver.py +++ b/src/borg/archiver.py @@ -2375,85 +2375,85 @@ class Archiver: 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 (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:: + .. 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. + 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. + 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:: + .. 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. + 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. + 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. + 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:: + 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 + # 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 + # use a file with patterns: + borg create --patterns-from patterns.lst repo::arch - The patterns.lst file could look like that:: + 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 + # "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:: + 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 + # 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:: + 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 + # 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 + - /home/bobby/junk - This allows you to share the same patterns between multiple repositories - without needing to specify them on the command line.\n\n''') + This allows you to share the same patterns between multiple repositories + without needing to specify them on the command line.\n\n''') helptext['placeholders'] = textwrap.dedent(''' Repository (or Archive) URLs, ``--prefix``, ``--glob-archives``, ``--comment`` and ``--remote-path`` values support these placeholders: