From e4391dec54287bc72a939003c15943f888d127d9 Mon Sep 17 00:00:00 2001 From: Mark Edgington Date: Tue, 7 Mar 2017 19:55:46 -0500 Subject: [PATCH] docs: improve --exclude-if-present and --keep-exclude-tags --- src/borg/archiver.py | 31 ++++++++++++++++++++----------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/src/borg/archiver.py b/src/borg/archiver.py index 357defa74..cb4350a1d 100644 --- a/src/borg/archiver.py +++ b/src/borg/archiver.py @@ -2254,6 +2254,15 @@ def process_epilog(epilog): '\*/.bundler/gems' to get the same effect. See ``borg help patterns`` for more information. + In addition to using ``--exclude`` patterns, it is possible to use + ``--exclude-if-present`` to specify the name of a filesystem object (e.g. a file + or folder name) which, when contained within another folder, will prevent the + containing folder from being backed up. By default, the containing folder and + all of its contents will be omitted from the backup. If, however, you wish to + only include the objects specified by ``--exclude-if-present`` in your backup, + and not include any other contents of the containing folder, this can be enabled + through using the ``--keep-exclude-tags`` option. + Item flags ++++++++++ @@ -2337,8 +2346,8 @@ def process_epilog(epilog): 'the given NAME') exclude_group.add_argument('--keep-exclude-tags', '--keep-tag-files', dest='keep_exclude_tags', action='store_true', default=False, - help='keep tag objects (i.e.: arguments to --exclude-if-present) in otherwise ' - 'excluded caches/directories') + help='if tag objects are specified with --exclude-if-present, don\'t omit the tag ' + 'objects themselves from the backup archive') exclude_group.add_argument('--pattern', action=ArgparsePatternAction, metavar="PATTERN", help='include/exclude paths matching PATTERN') @@ -2510,8 +2519,8 @@ def process_epilog(epilog): 'the given NAME') exclude_group.add_argument('--keep-exclude-tags', '--keep-tag-files', dest='keep_exclude_tags', action='store_true', default=False, - help='keep tag objects (i.e.: arguments to --exclude-if-present) in otherwise ' - 'excluded caches/directories') + help='if tag objects are specified with --exclude-if-present, don\'t omit the tag ' + 'objects themselves from the backup archive') exclude_group.add_argument('--pattern', action=ArgparsePatternAction, metavar="PATTERN", help='include/exclude paths matching PATTERN') @@ -2626,8 +2635,8 @@ def process_epilog(epilog): 'the given NAME') exclude_group.add_argument('--keep-exclude-tags', '--keep-tag-files', dest='keep_exclude_tags', action='store_true', default=False, - help='keep tag objects (i.e.: arguments to --exclude-if-present) in otherwise ' - 'excluded caches/directories') + help='if tag objects are specified with --exclude-if-present, don\'t omit the tag ' + 'objects themselves from the backup archive') exclude_group.add_argument('--pattern', action=ArgparsePatternAction, metavar="PATTERN", help='include/exclude paths matching PATTERN') @@ -2921,9 +2930,9 @@ def process_epilog(epilog): This is an *experimental* feature. Do *not* use this on your only backup. - --exclude, --exclude-from and PATH have the exact same semantics - as in "borg create". If PATHs are specified the resulting archive - will only contain files from these PATHs. + --exclude, --exclude-from, --exclude-if-present, --keep-exclude-tags, and PATH + have the exact same semantics as in "borg create". If PATHs are specified the + resulting archive will only contain files from these PATHs. Note that all paths in an archive are relative, therefore absolute patterns/paths will *not* match (--exclude, --exclude-from, --compression-from, PATHs). @@ -2991,8 +3000,8 @@ def process_epilog(epilog): 'the given NAME') exclude_group.add_argument('--keep-exclude-tags', '--keep-tag-files', dest='keep_exclude_tags', action='store_true', default=False, - help='keep tag objects (i.e.: arguments to --exclude-if-present) in otherwise ' - 'excluded caches/directories') + help='if tag objects are specified with --exclude-if-present, don\'t omit the tag ' + 'objects themselves from the backup archive') exclude_group.add_argument('--pattern', action=ArgparsePatternAction, metavar="PATTERN", help='include/exclude paths matching PATTERN')