Fix Healthchecks tests that leak global state, breaking downstream tests (discovered in #543).

Reviewed-on: borgmatic-collective/borgmatic#540

NEWS

@@ -1,3 +1,24 @@
+1.6.3.dev0
+ * #541: Add "borgmatic list --find" flag for searching for files across multiple archives, useful
+   for hunting down that file you accidentally deleted so you can extract it. See the documentation
+   for more information:
+   https://torsion.org/borgmatic/docs/how-to/inspect-your-backups/#searching-for-a-file
+ * Deprecate "borgmatic list --successful" flag, as listing only non-checkpoint (successful)
+   archives is now the default in newer versions of Borg.
+
+1.6.2
+ * #523: Reduce the default consistency check frequency and support configuring the frequency
+   independently for each check. Also add "borgmatic check --force" flag to ignore configured
+   frequencies. See the documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/deal-with-very-large-backups/#check-frequency
+ * #536: Fix generate-borgmatic-config to support more complex schema changes like the new
+   Healthchecks configuration options when the "--source" flag is used.
+ * #538: Add support for "borgmatic borg debug" command.
+ * #539: Add "generate-borgmatic-config --overwrite" flag to replace an existing destination file.
+ * Add Bash completion script so you can tab-complete the borgmatic command-line. See the
+   documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/set-up-backups/#shell-completion
+
 1.6.1
  * #294: Add Healthchecks monitoring hook "ping_body_limit" option to configure how many bytes of
    logs to send to the Healthchecks server.

README.md

@@ -37,8 +37,9 @@ retention:
 consistency:
     # List of checks to run to validate your backups.
     checks:
-        - repository
-        - archives
+        - name: repository
+        - name: archives
+          frequency: 2 weeks
 
 hooks:
     # Custom preparation scripts to run.

borgmatic/borg/borg.py

@@ -7,6 +7,8 @@ logger = logging.getLogger(__name__)
 
 
 REPOSITORYLESS_BORG_COMMANDS = {'serve', None}
+BORG_COMMANDS_WITH_SUBCOMMANDS = {'key', 'debug'}
+BORG_SUBCOMMANDS_WITHOUT_REPOSITORY = (('debug', 'info'), ('debug', 'convert-profile'))
 
 
 def run_arbitrary_borg(
@@ -22,15 +24,20 @@ def run_arbitrary_borg(
     try:
         options = options[1:] if options[0] == '--' else options
 
-        # Borg's "key" command has a sub-command ("export", etc.) that must follow it.
-        command_options_start_index = 2 if options[0] == 'key' else 1
+        # Borg commands like "key" have a sub-command ("export", etc.) that must follow it.
+        command_options_start_index = 2 if options[0] in BORG_COMMANDS_WITH_SUBCOMMANDS else 1
         borg_command = tuple(options[:command_options_start_index])
         command_options = tuple(options[command_options_start_index:])
     except IndexError:
         borg_command = ()
         command_options = ()
 
-    repository_archive = '::'.join((repository, archive)) if repository and archive else repository
+    if borg_command in BORG_SUBCOMMANDS_WITHOUT_REPOSITORY:
+        repository_archive = None
+    else:
+        repository_archive = (
+            '::'.join((repository, archive)) if repository and archive else repository
+        )
 
     full_command = (
         (local_path,)

borgmatic/borg/check.py

@@ -1,46 +1,157 @@
+import argparse
+import datetime
+import json
 import logging
+import os
+import pathlib
 
-from borgmatic.borg import extract
+from borgmatic.borg import extract, info, state
 from borgmatic.execute import DO_NOT_CAPTURE, execute_command
 
-DEFAULT_CHECKS = ('repository', 'archives')
+DEFAULT_CHECKS = (
+    {'name': 'repository', 'frequency': '1 month'},
+    {'name': 'archives', 'frequency': '1 month'},
+)
 DEFAULT_PREFIX = '{hostname}-'
 
 
 logger = logging.getLogger(__name__)
 
 
-def _parse_checks(consistency_config, only_checks=None):
+def parse_checks(consistency_config, only_checks=None):
     '''
-    Given a consistency config with a "checks" list, and an optional list of override checks,
-    transform them a tuple of named checks to run.
+    Given a consistency config with a "checks" sequence of dicts and an optional list of override
+    checks, return a tuple of named checks to run.
 
     For example, given a retention config of:
 
-        {'checks': ['repository', 'archives']}
+        {'checks': ({'name': 'repository'}, {'name': 'archives'})}
 
     This will be returned as:
 
         ('repository', 'archives')
 
-    If no "checks" option is present in the config, return the DEFAULT_CHECKS. If the checks value
-    is the string "disabled", return an empty tuple, meaning that no checks should be run.
+    If no "checks" option is present in the config, return the DEFAULT_CHECKS. If a checks value
+    has a name of "disabled", return an empty tuple, meaning that no checks should be run.
 
-    If the "data" option is present, then make sure the "archives" option is included as well.
+    If the "data" check is present, then make sure the "archives" check is included as well.
     '''
-    checks = [
-        check.lower() for check in (only_checks or consistency_config.get('checks', []) or [])
-    ]
-    if checks == ['disabled']:
+    checks = only_checks or tuple(
+        check_config['name']
+        for check_config in (consistency_config.get('checks', None) or DEFAULT_CHECKS)
+    )
+    checks = tuple(check.lower() for check in checks)
+    if 'disabled' in checks:
+        if len(checks) > 1:
+            logger.warning(
+                'Multiple checks are configured, but one of them is "disabled"; not running any checks'
+            )
         return ()
 
     if 'data' in checks and 'archives' not in checks:
-        checks.append('archives')
+        return checks + ('archives',)
 
-    return tuple(check for check in checks if check not in ('disabled', '')) or DEFAULT_CHECKS
+    return checks
 
 
-def _make_check_flags(checks, check_last=None, prefix=None):
+def parse_frequency(frequency):
+    '''
+    Given a frequency string with a number and a unit of time, return a corresponding
+    datetime.timedelta instance or None if the frequency is None or "always".
+
+    For instance, given "3 weeks", return datetime.timedelta(weeks=3)
+
+    Raise ValueError if the given frequency cannot be parsed.
+    '''
+    if not frequency:
+        return None
+
+    frequency = frequency.strip().lower()
+
+    if frequency == 'always':
+        return None
+
+    try:
+        number, time_unit = frequency.split(' ')
+        number = int(number)
+    except ValueError:
+        raise ValueError(f"Could not parse consistency check frequency '{frequency}'")
+
+    if not time_unit.endswith('s'):
+        time_unit += 's'
+
+    if time_unit == 'months':
+        number *= 30
+        time_unit = 'days'
+    elif time_unit == 'years':
+        number *= 365
+        time_unit = 'days'
+
+    try:
+        return datetime.timedelta(**{time_unit: number})
+    except TypeError:
+        raise ValueError(f"Could not parse consistency check frequency '{frequency}'")
+
+
+def filter_checks_on_frequency(
+    location_config, consistency_config, borg_repository_id, checks, force
+):
+    '''
+    Given a location config, a consistency config with a "checks" sequence of dicts, a Borg
+    repository ID, a sequence of checks, and whether to force checks to run, filter down those
+    checks based on the configured "frequency" for each check as compared to its check time file.
+
+    In other words, a check whose check time file's timestamp is too new (based on the configured
+    frequency) will get cut from the returned sequence of checks. Example:
+
+    consistency_config = {
+        'checks': [
+            {
+                'name': 'archives',
+                'frequency': '2 weeks',
+            },
+        ]
+    }
+
+    When this function is called with that consistency_config and "archives" in checks, "archives"
+    will get filtered out of the returned result if its check time file is newer than 2 weeks old,
+    indicating that it's not yet time to run that check again.
+
+    Raise ValueError if a frequency cannot be parsed.
+    '''
+    filtered_checks = list(checks)
+
+    if force:
+        return tuple(filtered_checks)
+
+    for check_config in consistency_config.get('checks', DEFAULT_CHECKS):
+        check = check_config['name']
+        if checks and check not in checks:
+            continue
+
+        frequency_delta = parse_frequency(check_config.get('frequency'))
+        if not frequency_delta:
+            continue
+
+        check_time = read_check_time(
+            make_check_time_path(location_config, borg_repository_id, check)
+        )
+        if not check_time:
+            continue
+
+        # If we've not yet reached the time when the frequency dictates we're ready for another
+        # check, skip this check.
+        if datetime.datetime.now() < check_time + frequency_delta:
+            remaining = check_time + frequency_delta - datetime.datetime.now()
+            logger.info(
+                f"Skipping {check} check due to configured frequency; {remaining} until next check"
+            )
+            filtered_checks.remove(check)
+
+    return tuple(filtered_checks)
+
+
+def make_check_flags(checks, check_last=None, prefix=None):
     '''
     Given a parsed sequence of checks, transform it into tuple of command-line flags.
 
@@ -66,27 +177,67 @@ def _make_check_flags(checks, check_last=None, prefix=None):
         last_flags = ()
         prefix_flags = ()
         if check_last:
-            logger.warning(
-                'Ignoring check_last option, as "archives" is not in consistency checks.'
-            )
+            logger.info('Ignoring check_last option, as "archives" is not in consistency checks')
         if prefix:
-            logger.warning(
-                'Ignoring consistency prefix option, as "archives" is not in consistency checks.'
+            logger.info(
+                'Ignoring consistency prefix option, as "archives" is not in consistency checks'
             )
 
     common_flags = last_flags + prefix_flags + (('--verify-data',) if 'data' in checks else ())
 
-    if set(DEFAULT_CHECKS).issubset(set(checks)):
+    if {'repository', 'archives'}.issubset(set(checks)):
         return common_flags
 
     return (
-        tuple('--{}-only'.format(check) for check in checks if check in DEFAULT_CHECKS)
+        tuple('--{}-only'.format(check) for check in checks if check in ('repository', 'archives'))
         + common_flags
     )
 
 
+def make_check_time_path(location_config, borg_repository_id, check_type):
+    '''
+    Given a location configuration dict, a Borg repository ID, and the name of a check type
+    ("repository", "archives", etc.), return a path for recording that check's time (the time of
+    that check last occurring).
+    '''
+    return os.path.join(
+        os.path.expanduser(
+            location_config.get(
+                'borgmatic_source_directory', state.DEFAULT_BORGMATIC_SOURCE_DIRECTORY
+            )
+        ),
+        'checks',
+        borg_repository_id,
+        check_type,
+    )
+
+
+def write_check_time(path):  # pragma: no cover
+    '''
+    Record a check time of now as the modification time of the given path.
+    '''
+    logger.debug(f'Writing check time at {path}')
+
+    os.makedirs(os.path.dirname(path), mode=0o700, exist_ok=True)
+    pathlib.Path(path, mode=0o600).touch()
+
+
+def read_check_time(path):
+    '''
+    Return the check time based on the modification time of the given path. Return None if the path
+    doesn't exist.
+    '''
+    logger.debug(f'Reading check time from {path}')
+
+    try:
+        return datetime.datetime.fromtimestamp(os.stat(path).st_mtime)
+    except FileNotFoundError:
+        return None
+
+
 def check_archives(
     repository,
+    location_config,
     storage_config,
     consistency_config,
     local_path='borg',
@@ -94,6 +245,7 @@ def check_archives(
     progress=None,
     repair=None,
     only_checks=None,
+    force=None,
 ):
     '''
     Given a local or remote repository path, a storage config dict, a consistency config dict,
@@ -102,13 +254,34 @@ def check_archives(
     Borg archives for consistency.
 
     If there are no consistency checks to run, skip running them.
+
+    Raises ValueError if the Borg repository ID cannot be determined.
     '''
-    checks = _parse_checks(consistency_config, only_checks)
+    try:
+        borg_repository_id = json.loads(
+            info.display_archives_info(
+                repository,
+                storage_config,
+                argparse.Namespace(json=True, archive=None),
+                local_path,
+                remote_path,
+            )
+        )['repository']['id']
+    except (json.JSONDecodeError, KeyError):
+        raise ValueError(f'Cannot determine Borg repository ID for {repository}')
+
+    checks = filter_checks_on_frequency(
+        location_config,
+        consistency_config,
+        borg_repository_id,
+        parse_checks(consistency_config, only_checks),
+        force,
+    )
     check_last = consistency_config.get('check_last', None)
     lock_wait = None
     extra_borg_options = storage_config.get('extra_borg_options', {}).get('check', '')
 
-    if set(checks).intersection(set(DEFAULT_CHECKS + ('data',))):
+    if set(checks).intersection({'repository', 'archives', 'data'}):
         lock_wait = storage_config.get('lock_wait', None)
 
         verbosity_flags = ()
@@ -122,7 +295,7 @@ def check_archives(
         full_command = (
             (local_path, 'check')
             + (('--repair',) if repair else ())
-            + _make_check_flags(checks, check_last, prefix)
+            + make_check_flags(checks, check_last, prefix)
             + (('--remote-path', remote_path) if remote_path else ())
             + (('--lock-wait', str(lock_wait)) if lock_wait else ())
             + verbosity_flags
@@ -131,12 +304,16 @@ def check_archives(
             + (repository,)
         )
 
-        # The Borg repair option trigger an interactive prompt, which won't work when output is
+        # The Borg repair option triggers an interactive prompt, which won't work when output is
         # captured. And progress messes with the terminal directly.
         if repair or progress:
             execute_command(full_command, output_file=DO_NOT_CAPTURE)
         else:
             execute_command(full_command)
 
+        for check in checks:
+            write_check_time(make_check_time_path(location_config, borg_repository_id, check))
+
     if 'extract' in checks:
         extract.extract_last_archive_dry_run(repository, lock_wait, local_path, remote_path)
+        write_check_time(make_check_time_path(location_config, borg_repository_id, 'extract'))

borgmatic/borg/create.py

@@ -5,7 +5,7 @@ import os
 import pathlib
 import tempfile
 
-from borgmatic.borg import feature
+from borgmatic.borg import feature, state
 from borgmatic.execute import DO_NOT_CAPTURE, execute_command, execute_command_with_processes
 
 logger = logging.getLogger(__name__)
@@ -175,7 +175,7 @@ def make_exclude_flags(location_config, exclude_filename=None):
     )
 
 
-DEFAULT_BORGMATIC_SOURCE_DIRECTORY = '~/.borgmatic'
+DEFAULT_ARCHIVE_NAME_FORMAT = '{hostname}-{now:%Y-%m-%dT%H:%M:%S.%f}'
 
 
 def borgmatic_source_directories(borgmatic_source_directory):
@@ -183,7 +183,7 @@ def borgmatic_source_directories(borgmatic_source_directory):
     Return a list of borgmatic-specific source directories used for state like database backups.
     '''
     if not borgmatic_source_directory:
-        borgmatic_source_directory = DEFAULT_BORGMATIC_SOURCE_DIRECTORY
+        borgmatic_source_directory = state.DEFAULT_BORGMATIC_SOURCE_DIRECTORY
 
     return (
         [borgmatic_source_directory]
@@ -192,9 +192,6 @@ def borgmatic_source_directories(borgmatic_source_directory):
     )
 
 
-DEFAULT_ARCHIVE_NAME_FORMAT = '{hostname}-{now:%Y-%m-%dT%H:%M:%S.%f}'
-
-
 def create_archive(
     dry_run,
     repository,

borgmatic/borg/init.py

@@ -1,6 +1,8 @@
+import argparse
 import logging
 import subprocess
 
+from borgmatic.borg import info
 from borgmatic.execute import DO_NOT_CAPTURE, execute_command
 
 logger = logging.getLogger(__name__)
@@ -23,17 +25,14 @@ def initialize_repository(
     whether the repository should be append-only, and the storage quota to use, initialize the
     repository. If the repository already exists, then log and skip initialization.
     '''
-    info_command = (
-        (local_path, 'info')
-        + (('--info',) if logger.getEffectiveLevel() == logging.INFO else ())
-        + (('--debug',) if logger.isEnabledFor(logging.DEBUG) else ())
-        + (('--remote-path', remote_path) if remote_path else ())
-        + (repository,)
-    )
-    logger.debug(' '.join(info_command))
-
     try:
-        execute_command(info_command, output_log_level=None)
+        info.display_archives_info(
+            repository,
+            storage_config,
+            argparse.Namespace(json=True, archive=None),
+            local_path,
+            remote_path,
+        )
         logger.info('Repository already exists. Skipping initialization.')
         return
     except subprocess.CalledProcessError as error:

borgmatic/borg/list.py

@@ -1,4 +1,6 @@
+import copy
 import logging
+import re
 
 from borgmatic.borg.flags import make_flags, make_flags_from_arguments
 from borgmatic.execute import execute_command
@@ -6,17 +8,11 @@ from borgmatic.execute import execute_command
 logger = logging.getLogger(__name__)
 
 
-# A hack to convince Borg to exclude archives ending in ".checkpoint". This assumes that a
-# non-checkpoint archive name ends in a digit (e.g. from a timestamp).
-BORG_EXCLUDE_CHECKPOINTS_GLOB = '*[0123456789]'
-
-
 def resolve_archive_name(repository, archive, storage_config, local_path='borg', remote_path=None):
     '''
     Given a local or remote repository path, an archive name, a storage config dict, a local Borg
     path, and a remote Borg path, simply return the archive name. But if the archive name is
-    "latest", then instead introspect the repository for the latest successful (non-checkpoint)
-    archive, and return its name.
+    "latest", then instead introspect the repository for the latest archive and return its name.
 
     Raise ValueError if "latest" is given but there are no archives in the repository.
     '''
@@ -31,7 +27,6 @@ def resolve_archive_name(repository, archive, storage_config, local_path='borg',
         + (('--debug', '--show-rc') if logger.isEnabledFor(logging.DEBUG) else ())
         + make_flags('remote-path', remote_path)
         + make_flags('lock-wait', lock_wait)
-        + make_flags('glob-archives', BORG_EXCLUDE_CHECKPOINTS_GLOB)
         + make_flags('last', 1)
         + ('--short', repository)
     )
@@ -47,17 +42,20 @@ def resolve_archive_name(repository, archive, storage_config, local_path='borg',
     return latest_archive
 
 
-def list_archives(repository, storage_config, list_arguments, local_path='borg', remote_path=None):
+MAKE_FLAGS_EXCLUDES = ('repository', 'archive', 'successful', 'paths', 'find_paths')
+
+
+def make_list_command(
+    repository, storage_config, list_arguments, local_path='borg', remote_path=None
+):
     '''
-    Given a local or remote repository path, a storage config dict, and the arguments to the list
-    action, display the output of listing Borg archives in the repository or return JSON output. Or,
-    if an archive name is given, listing the files in that archive.
+    Given a local or remote repository path, a storage config dict, the arguments to the list
+    action, and local and remote Borg paths, return a command as a tuple to list archives or paths
+    within an archive.
     '''
     lock_wait = storage_config.get('lock_wait', None)
-    if list_arguments.successful:
-        list_arguments.glob_archives = BORG_EXCLUDE_CHECKPOINTS_GLOB
 
-    full_command = (
+    return (
         (local_path, 'list')
         + (
             ('--info',)
@@ -71,19 +69,92 @@ def list_archives(repository, storage_config, list_arguments, local_path='borg',
         )
         + make_flags('remote-path', remote_path)
         + make_flags('lock-wait', lock_wait)
-        + make_flags_from_arguments(
-            list_arguments, excludes=('repository', 'archive', 'paths', 'successful')
-        )
+        + make_flags_from_arguments(list_arguments, excludes=MAKE_FLAGS_EXCLUDES,)
         + (
-            '::'.join((repository, list_arguments.archive))
+            ('::'.join((repository, list_arguments.archive)),)
             if list_arguments.archive
-            else repository,
+            else (repository,)
         )
         + (tuple(list_arguments.paths) if list_arguments.paths else ())
     )
 
-    return execute_command(
-        full_command,
-        output_log_level=None if list_arguments.json else logging.WARNING,
-        borg_local_path=local_path,
+
+def make_find_paths(find_paths):
+    '''
+    Given a sequence of path fragments or patterns as passed to `--find`, transform all path
+    fragments into glob patterns. Pass through existing patterns untouched.
+
+    For example, given find_paths of:
+
+      ['foo.txt', 'pp:root/somedir']
+
+    ... transform that into:
+
+      ['sh:**/*foo.txt*/**', 'pp:root/somedir']
+    '''
+    if not find_paths:
+        return ()
+
+    return tuple(
+        find_path
+        if re.compile(r'([-!+RrPp] )|(\w\w:)').match(find_path)
+        else f'sh:**/*{find_path}*/**'
+        for find_path in find_paths
     )
+
+
+def list_archives(repository, storage_config, list_arguments, local_path='borg', remote_path=None):
+    '''
+    Given a local or remote repository path, a storage config dict, the arguments to the list
+    action, and local and remote Borg paths, display the output of listing Borg archives in the
+    repository or return JSON output. Or, if an archive name is given, list the files in that
+    archive. Or, if list_arguments.find_paths are given, list the files by searching across multiple
+    archives.
+    '''
+    # If there are any paths to find (and there's not a single archive already selected), start by
+    # getting a list of archives to search.
+    if list_arguments.find_paths and not list_arguments.archive:
+        repository_arguments = copy.copy(list_arguments)
+        repository_arguments.archive = None
+        repository_arguments.json = False
+        repository_arguments.format = None
+
+        # Ask Borg to list archives. Capture its output for use below.
+        archive_lines = tuple(
+            execute_command(
+                make_list_command(
+                    repository, storage_config, repository_arguments, local_path, remote_path
+                ),
+                output_log_level=None,
+                borg_local_path=local_path,
+            )
+            .strip('\n')
+            .split('\n')
+        )
+    else:
+        archive_lines = (list_arguments.archive,)
+
+    # For each archive listed by Borg, run list on the contents of that archive.
+    for archive_line in archive_lines:
+        try:
+            archive = archive_line.split()[0]
+        except (AttributeError, IndexError):
+            archive = None
+
+        if archive:
+            logger.warning(archive_line)
+
+        archive_arguments = copy.copy(list_arguments)
+        archive_arguments.archive = archive
+        main_command = make_list_command(
+            repository, storage_config, archive_arguments, local_path, remote_path
+        ) + make_find_paths(list_arguments.find_paths)
+
+        output = execute_command(
+            main_command,
+            output_log_level=None if list_arguments.json else logging.WARNING,
+            borg_local_path=local_path,
+        )
+
+        if list_arguments.json:
+            return output

borgmatic/borg/state.py

@@ -0,0 +1 @@
+DEFAULT_BORGMATIC_SOURCE_DIRECTORY = '~/.borgmatic'

borgmatic/commands/arguments.py

@@ -109,10 +109,9 @@ class Extend_action(Action):
             setattr(namespace, self.dest, list(values))
 
 
-def parse_arguments(*unparsed_arguments):
+def make_parsers():
     '''
-    Given command-line arguments with which this script was invoked, parse the arguments and return
-    them as a dict mapping from subparser name (or "global") to an argparse.Namespace instance.
+    Build a top-level parser and its subparsers and return them as a tuple.
     '''
     config_paths = collect.get_default_config_paths(expand_home=True)
     unexpanded_config_paths = collect.get_default_config_paths(expand_home=False)
@@ -189,6 +188,12 @@ def parse_arguments(*unparsed_arguments):
         action='extend',
         help='One or more configuration file options to override with specified values',
     )
+    global_group.add_argument(
+        '--bash-completion',
+        default=False,
+        action='store_true',
+        help='Show bash completion script and exit',
+    )
     global_group.add_argument(
         '--version',
         dest='version',
@@ -341,7 +346,7 @@ def parse_arguments(*unparsed_arguments):
         dest='repair',
         default=False,
         action='store_true',
-        help='Attempt to repair any inconsistencies found (experimental and only for interactive use)',
+        help='Attempt to repair any inconsistencies found (for interactive use)',
     )
     check_group.add_argument(
         '--only',
@@ -349,7 +354,13 @@ def parse_arguments(*unparsed_arguments):
         choices=('repository', 'archives', 'data', 'extract'),
         dest='only',
         action='append',
-        help='Run a particular consistency check (repository, archives, data, or extract) instead of configured checks; can specify flag multiple times',
+        help='Run a particular consistency check (repository, archives, data, or extract) instead of configured checks (subject to configured frequency, can specify flag multiple times)',
+    )
+    check_group.add_argument(
+        '--force',
+        default=False,
+        action='store_true',
+        help='Ignore configured check frequencies and run checks unconditionally',
     )
     check_group.add_argument('-h', '--help', action='help', help='Show this help message and exit')
 
@@ -543,7 +554,14 @@ def parse_arguments(*unparsed_arguments):
         metavar='PATH',
         nargs='+',
         dest='paths',
-        help='Paths to list from archive, defaults to the entire archive',
+        help='Paths or patterns to list from a single selected archive (via "--archive"), defaults to listing the entire archive',
+    )
+    list_group.add_argument(
+        '--find',
+        metavar='PATH',
+        nargs='+',
+        dest='find_paths',
+        help='Partial paths or patterns to search for and list across multiple archives',
     )
     list_group.add_argument(
         '--short', default=False, action='store_true', help='Output only archive or path names'
@@ -560,9 +578,9 @@ def parse_arguments(*unparsed_arguments):
     )
     list_group.add_argument(
         '--successful',
-        default=False,
+        default=True,
         action='store_true',
-        help='Only list archive names of successful (non-checkpoint) backups',
+        help='Deprecated in favor of listing successful (non-checkpoint) backups by default in newer versions of Borg',
     )
     list_group.add_argument(
         '--sort-by', metavar='KEYS', help='Comma-separated list of sorting keys'
@@ -647,6 +665,16 @@ def parse_arguments(*unparsed_arguments):
     )
     borg_group.add_argument('-h', '--help', action='help', help='Show this help message and exit')
 
+    return top_level_parser, subparsers
+
+
+def parse_arguments(*unparsed_arguments):
+    '''
+    Given command-line arguments with which this script was invoked, parse the arguments and return
+    them as a dict mapping from subparser name (or "global") to an argparse.Namespace instance.
+    '''
+    top_level_parser, subparsers = make_parsers()
+
     arguments, remaining_arguments = parse_subparser_arguments(
         unparsed_arguments, subparsers.choices
     )
@@ -660,9 +688,6 @@ def parse_arguments(*unparsed_arguments):
     if 'init' in arguments and arguments['global'].dry_run:
         raise ValueError('The init action cannot be used with the --dry-run option')
 
-    if 'list' in arguments and arguments['list'].glob_archives and arguments['list'].successful:
-        raise ValueError('The --glob-archives and --successful options cannot be used together')
-
     if (
         'list' in arguments
         and 'info' in arguments

borgmatic/commands/borgmatic.py

@@ -11,6 +11,7 @@ from subprocess import CalledProcessError
 import colorama
 import pkg_resources
 
+import borgmatic.commands.completion
 from borgmatic.borg import borg as borg_borg
 from borgmatic.borg import check as borg_check
 from borgmatic.borg import compact as borg_compact
@@ -394,6 +395,7 @@ def run_actions(
         logger.info('{}: Running consistency checks'.format(repository))
         borg_check.check_archives(
             repository,
+            location,
             storage,
             consistency,
             local_path=local_path,
@@ -401,6 +403,7 @@ def run_actions(
             progress=arguments['check'].progress,
             repair=arguments['check'].repair,
             only_checks=arguments['check'].only,
+            force=arguments['check'].force,
         )
         command.execute_hook(
             hooks.get('after_check'),
@@ -884,6 +887,9 @@ def main():  # pragma: no cover
     if global_arguments.version:
         print(pkg_resources.require('borgmatic')[0].version)
         sys.exit(0)
+    if global_arguments.bash_completion:
+        print(borgmatic.commands.completion.bash_completion())
+        sys.exit(0)
 
     config_filenames = tuple(collect.collect_config_filenames(global_arguments.config_paths))
     configs, parse_logs = load_configurations(config_filenames, global_arguments.overrides)

borgmatic/commands/completion.py

@@ -0,0 +1,58 @@
+from borgmatic.commands import arguments
+
+UPGRADE_MESSAGE = '''
+Your bash completions script is from a different version of borgmatic than is
+currently installed. Please upgrade your script so your completions match the
+command-line flags in your installed borgmatic! Try this to upgrade:
+
+    sudo sh -c "borgmatic --bash-completion > $BASH_SOURCE"
+    source $BASH_SOURCE
+'''
+
+
+def parser_flags(parser):
+    '''
+    Given an argparse.ArgumentParser instance, return its argument flags in a space-separated
+    string.
+    '''
+    return ' '.join(option for action in parser._actions for option in action.option_strings)
+
+
+def bash_completion():
+    '''
+    Return a bash completion script for the borgmatic command. Produce this by introspecting
+    borgmatic's command-line argument parsers.
+    '''
+    top_level_parser, subparsers = arguments.make_parsers()
+    global_flags = parser_flags(top_level_parser)
+    actions = ' '.join(subparsers.choices.keys())
+
+    # Avert your eyes.
+    return '\n'.join(
+        (
+            'set -uo pipefail',
+            'check_version() {',
+            '    local this_script="$(cat "$BASH_SOURCE" 2> /dev/null)"',
+            '    local installed_script="$(borgmatic --bash-completion 2> /dev/null)"',
+            '    if [ "$this_script" != "$installed_script" ] && [ "$installed_script" != "" ];'
+            '        then cat << EOF\n%s\nEOF' % UPGRADE_MESSAGE,
+            '    fi',
+            '}',
+            'complete_borgmatic() {',
+        )
+        + tuple(
+            '''    if [[ " ${COMP_WORDS[*]} " =~ " %s " ]]; then
+        COMPREPLY=($(compgen -W "%s %s %s" -- "${COMP_WORDS[COMP_CWORD]}"))
+        return 0
+    fi'''
+            % (action, parser_flags(subparser), actions, global_flags)
+            for action, subparser in subparsers.choices.items()
+        )
+        + (
+            '    COMPREPLY=($(compgen -W "%s %s" -- "${COMP_WORDS[COMP_CWORD]}"))'
+            % (actions, global_flags),
+            '    (check_version &)',
+            '}',
+            '\ncomplete -o bashdefault -o default -F complete_borgmatic borgmatic',
+        )
+    )

borgmatic/commands/generate_config.py

@@ -23,10 +23,16 @@ def parse_arguments(*arguments):
         '--destination',
         dest='destination_filename',
         default=DEFAULT_DESTINATION_CONFIG_FILENAME,
-        help='Destination YAML configuration file. Default: {}'.format(
+        help='Destination YAML configuration file, default: {}'.format(
             DEFAULT_DESTINATION_CONFIG_FILENAME
         ),
     )
+    parser.add_argument(
+        '--overwrite',
+        default=False,
+        action='store_true',
+        help='Whether to overwrite any existing destination file, defaults to false',
+    )
 
     return parser.parse_args(arguments)
 
@@ -36,7 +42,10 @@ def main():  # pragma: no cover
         args = parse_arguments(*sys.argv[1:])
 
         generate.generate_sample_configuration(
-            args.source_filename, args.destination_filename, validate.schema_filename()
+            args.source_filename,
+            args.destination_filename,
+            validate.schema_filename(),
+            overwrite=args.overwrite,
         )
 
         print('Generated a sample configuration file at {}.'.format(args.destination_filename))

borgmatic/config/generate.py

@@ -5,7 +5,7 @@ import re
 
 from ruamel import yaml
 
-from borgmatic.config import load
+from borgmatic.config import load, normalize
 
 INDENT = 4
 SEQUENCE_INDENT = 2
@@ -109,13 +109,18 @@ def render_configuration(config):
     return rendered.getvalue()
 
 
-def write_configuration(config_filename, rendered_config, mode=0o600):
+def write_configuration(config_filename, rendered_config, mode=0o600, overwrite=False):
     '''
     Given a target config filename and rendered config YAML, write it out to file. Create any
-    containing directories as needed.
+    containing directories as needed. But if the file already exists and overwrite is False,
+    abort before writing anything.
     '''
-    if os.path.exists(config_filename):
-        raise FileExistsError('{} already exists. Aborting.'.format(config_filename))
+    if not overwrite and os.path.exists(config_filename):
+        raise FileExistsError(
+            '{} already exists. Aborting. Use --overwrite to replace the file.'.format(
+                config_filename
+            )
+        )
 
     try:
         os.makedirs(os.path.dirname(config_filename), mode=0o700)
@@ -263,18 +268,22 @@ def merge_source_configuration_into_destination(destination_config, source_confi
     return destination_config
 
 
-def generate_sample_configuration(source_filename, destination_filename, schema_filename):
+def generate_sample_configuration(
+    source_filename, destination_filename, schema_filename, overwrite=False
+):
     '''
     Given an optional source configuration filename, and a required destination configuration
-    filename, and the path to a schema filename in a YAML rendition of the JSON Schema format,
-    write out a sample configuration file based on that schema. If a source filename is provided,
-    merge the parsed contents of that configuration into the generated configuration.
+    filename, the path to a schema filename in a YAML rendition of the JSON Schema format, and
+    whether to overwrite a destination file, write out a sample configuration file based on that
+    schema. If a source filename is provided, merge the parsed contents of that configuration into
+    the generated configuration.
     '''
     schema = yaml.round_trip_load(open(schema_filename))
     source_config = None
 
     if source_filename:
         source_config = load.load_configuration(source_filename)
+        normalize.normalize(source_config)
 
     destination_config = merge_source_configuration_into_destination(
         _schema_to_sample_configuration(schema), source_config
@@ -283,4 +292,5 @@ def generate_sample_configuration(source_filename, destination_filename, schema_
     write_configuration(
         destination_filename,
         _comment_out_optional_configuration(render_configuration(destination_config)),
+        overwrite=overwrite,
     )

borgmatic/config/normalize.py

@@ -24,3 +24,8 @@ def normalize(config):
     cronhub = config.get('hooks', {}).get('cronhub')
     if isinstance(cronhub, str):
         config['hooks']['cronhub'] = {'ping_url': cronhub}
+
+    # Upgrade consistency checks from a list of strings to a list of dicts.
+    checks = config.get('consistency', {}).get('checks')
+    if isinstance(checks, list) and len(checks) and isinstance(checks[0], str):
+        config['consistency']['checks'] = [{'name': check_type} for check_type in checks]

borgmatic/config/schema.yaml

@@ -447,26 +447,45 @@ properties:
             checks:
                 type: array
                 items:
-                    type: string
-                    enum:
-                        - repository
-                        - archives
-                        - data
-                        - extract
-                        - disabled
-                    uniqueItems: true
+                    type: object
+                    required: ['name']
+                    additionalProperties: false
+                    properties:
+                        name:
+                            type: string
+                            enum:
+                                - repository
+                                - archives
+                                - data
+                                - extract
+                                - disabled
+                            description: |
+                                Name of consistency check to run: "repository",
+                                "archives", "data", and/or "extract". Set to
+                                "disabled" to disable all consistency checks.
+                                "repository" checks the consistency of the
+                                repository, "archives" checks all of the
+                                archives, "data" verifies the integrity of the
+                                data within the archives, and "extract" does an
+                                extraction dry-run of the most recent archive.
+                                Note that "data" implies "archives".
+                            example: repository
+                        frequency:
+                            type: string
+                            description: |
+                                How frequently to run this type of consistency
+                                check (as a best effort). The value is a number
+                                followed by a unit of time. E.g., "2 weeks" to
+                                run this consistency check no more than every
+                                two weeks for a given repository or "1 month" to
+                                run it no more than monthly. Defaults to
+                                "always": running this check every time checks
+                                are run.
+                            example: 2 weeks
                 description: |
-                    List of one or more consistency checks to run: "repository",
-                    "archives", "data", and/or "extract". Defaults to
-                    "repository" and "archives". Set to "disabled" to disable
-                    all consistency checks. "repository" checks the consistency
-                    of the repository, "archives" checks all of the archives,
-                    "data" verifies the integrity of the data within the
-                    archives, and "extract" does an extraction dry-run of the
-                    most recent archive. Note that "data" implies "archives".
-                example:
-                    - repository
-                    - archives
+                    List of one or more consistency checks to run on a periodic
+                    basis (if "frequency" is set) or every time borgmatic runs
+                    checks (if "frequency" is omitted).
             check_repositories:
                 type: array
                 items:
@@ -859,8 +878,8 @@ properties:
                             enum: ['archive', 'directory']
                             description: |
                                 Database dump output format. One of "archive",
-                                or "directory". Defaults to "archive". See 
-                                mongodump documentation for details. Note that 
+                                or "directory". Defaults to "archive". See
+                                mongodump documentation for details. Note that
                                 format is ignored when the database name is
                                 "all".
                             example: directory

borgmatic/hooks/dump.py

@@ -2,7 +2,7 @@ import logging
 import os
 import shutil
 
-from borgmatic.borg.create import DEFAULT_BORGMATIC_SOURCE_DIRECTORY
+from borgmatic.borg.state import DEFAULT_BORGMATIC_SOURCE_DIRECTORY
 
 logger = logging.getLogger(__name__)
 

docs/how-to/deal-with-very-large-backups.md

@@ -49,7 +49,7 @@ consistency checks with `check` on a much less frequent basis (e.g. with
 
 Another option is to customize your consistency checks. The default
 consistency checks run both full-repository checks and per-archive checks
-within each repository.
+within each repository no more than once a month.
 
 But if you find that archive checks are too slow, for example, you can
 configure borgmatic to run repository checks only. Configure this in the
@@ -58,9 +58,11 @@ configure borgmatic to run repository checks only. Configure this in the
 ```yaml
 consistency:
     checks:
-        - repository
+        - name: repository
 ```
 
+(Prior to borgmatic 1.6.2, `checks` was a plain list of strings without the `name:` part.)
+
 Here are the available checks from fastest to slowest:
 
  * `repository`: Checks the consistency of the repository itself.
@@ -70,6 +72,36 @@ Here are the available checks from fastest to slowest:
 
 See [Borg's check documentation](https://borgbackup.readthedocs.io/en/stable/usage/check.html) for more information.
 
+### Check frequency
+
+As of borgmatic 1.6.2, you can optionally configure checks to run on a
+periodic basis rather than every time borgmatic runs checks. For instance:
+
+```yaml
+consistency:
+    checks:
+        - name: repository
+          frequency: 2 weeks
+```
+
+This tells borgmatic to run this consistency check at most once every two
+weeks for a given repository. The `frequency` value is a number followed by a
+unit of time, e.g. "3 days", "1 week", "2 months", etc. The `frequency`
+defaults to "always", which means run this check every time checks run.
+
+Unlike a real scheduler like cron, borgmatic only makes a best effort to run
+checks on the configured frequency. It compares that frequency with how long
+it's been since the last check for a given repository (as recorded in a file
+within `~/.borgmatic/checks`). If it hasn't been long enough, the check is
+skipped. And you still have to run `borgmatic check` (or just `borgmatic`) in
+order for checks to run, even when a `frequency` is configured!
+
+If you want to temporarily ignore your configured frequencies, you can invoke
+`borgmatic check --force` to run checks unconditionally.
+
+
+### Disabling checks
+
 If that's still too slow, you can disable consistency checks entirely,
 either for a single repository or for all repositories.
 
@@ -78,7 +110,7 @@ Disabling all consistency checks looks like this:
 ```yaml
 consistency:
     checks:
-        - disabled
+        - name: disabled
 ```
 
 Or, if you have multiple repositories in your borgmatic configuration file,
@@ -99,7 +131,8 @@ borgmatic check --only data --only extract
 ```
 
 This is useful for running slow consistency checks on an infrequent basis,
-separate from your regular checks.
+separate from your regular checks. It is still subject to any configured
+check frequencies unless the `--force` flag is used.
 
 
 ## Troubleshooting

docs/how-to/extract-a-backup.md

@@ -116,7 +116,7 @@ Omit the `--archive` flag to mount all archives (lazy-loaded):
 borgmatic mount --mount-point /mnt
 ```
 
-Or use the "latest" value for the archive to mount the latest successful archive:
+Or use the "latest" value for the archive to mount the latest archive:
 
 ```bash
 borgmatic mount --archive latest --mount-point /mnt

docs/how-to/inspect-your-backups.md

@@ -51,6 +51,31 @@ borgmatic info
 `--info`. Or upgrade borgmatic!)
 
 
+### Searching for a file
+
+Let's say you've accidentally deleted a file and want to find the backup
+archive(s) containing it. `borgmatic list` provides a `--find` flag for
+exactly this purpose (as of borgmatic 1.6.3). For instance, if you're looking
+for a `foo.txt`:
+
+```bash
+borgmatic list --find foo.txt
+```
+
+This will list your archives and indicate those with files matching
+`*foo.txt*` anywhere in the archive. The `--find` parameter can alternatively
+be a [Borg
+pattern](https://borgbackup.readthedocs.io/en/stable/usage/help.html#borg-patterns).
+
+To limit the archives searched, use the standard `list` parameters for
+filtering archives such as `--last`, `--archive`, `--glob-archives`, etc. For
+example, to search only the last five archives:
+
+```bash
+borgmatic list --find foo.txt --last 5
+```
+
+
 ## Logging
 
 By default, borgmatic logs to a local syslog-compatible daemon if one is

docs/how-to/make-per-application-backups.md

@@ -133,6 +133,11 @@ Note that this `<<` include merging syntax is only for merging in mappings
 (configuration options and their values). But if you'd like to include a
 single value directly, please see the section above about standard includes.
 
+Additionally, there is a limitation preventing multiple `<<` include merges
+per section. So for instance, that means you can do one `<<` merge at the
+global level, another `<<` within each configuration section, etc. (This is a
+YAML limitation.)
+
 
 ## Configuration overrides
 

docs/how-to/monitor-your-backups.md

@@ -286,35 +286,12 @@ output only shows up at the console, and not in syslog.
  * [Borgmacator GNOME AppIndicator](https://github.com/N-Coder/borgmacator/)
 
 
-### Successful backups
-
-`borgmatic list` includes support for a `--successful` flag that only lists
-successful (non-checkpoint) backups. This flag works via a basic heuristic: It
-assumes that non-checkpoint archive names end with a digit (e.g. from a
-timestamp), while checkpoint archive names do not. This means that if you're
-using custom archive names that do not end in a digit, the `--successful` flag
-will not work as expected.
-
-Combined with a built-in Borg flag like `--last`, you can list the last
-successful backup for use in your monitoring scripts. Here's an example
-combined with `--json`:
-
-```bash
-borgmatic list --successful --last 1 --json
-```
-
-Note that this particular combination will only work if you've got a single
-backup "series" in your repository. If you're instead backing up, say, from
-multiple different hosts into a single repository, then you'll need to get
-fancier with your archive listing. See `borg list --help` for more flags.
-
-
 ### Latest backups
 
 All borgmatic actions that accept an "--archive" flag allow you to specify an
-archive name of "latest". This lets you get the latest successful archive
-without having to first run "borgmatic list" manually, which can be handy in
-automated scripts. Here's an example:
+archive name of "latest". This lets you get the latest archive without having
+to first run "borgmatic list" manually, which can be handy in automated
+scripts. Here's an example:
 
 ```bash
 borgmatic info --archive latest

docs/how-to/set-up-backups.md

@@ -92,6 +92,7 @@ installing borgmatic:
  * [Alpine Linux](https://pkgs.alpinelinux.org/packages?name=borgmatic)
  * [OpenBSD](http://ports.su/sysutils/borgmatic)
  * [openSUSE](https://software.opensuse.org/package/borgmatic)
+ * [macOS (via Homebrew)](https://formulae.brew.sh/formula/borgmatic)
  * [Ansible role](https://github.com/borgbase/ansible-role-borgbackup)
  * [virtualenv](https://virtualenv.pypa.io/en/stable/)
 
@@ -111,6 +112,7 @@ Additionally, [rsync.net](https://www.rsync.net/products/borg.html) and
 [Hetzner](https://www.hetzner.com/storage/storage-box) have compatible storage
 offerings, but do not currently fund borgmatic development or hosting.
 
+
 ## Configuration
 
 After you install borgmatic, generate a sample configuration file:
@@ -302,9 +304,43 @@ interested in an [unofficial work-around for Full Disk
 Access](https://projects.torsion.org/borgmatic-collective/borgmatic/issues/293).
 
 
-## Colored output
+## Niceties
 
-Borgmatic produces colored terminal output by default. It is disabled when a
+
+### Shell completion
+
+borgmatic includes a shell completion script (currently only for Bash) to
+support tab-completing borgmatic command-line actions and flags. Depending on
+how you installed borgmatic, this may be enabled by default. But if it's not,
+start by installing the `bash-completion` Linux package or the
+[`bash-completion@2`](https://formulae.brew.sh/formula/bash-completion@2)
+macOS Homebrew formula. Then, install the shell completion script globally:
+
+```bash
+sudo su -c "borgmatic --bash-completion > $(pkg-config --variable=completionsdir bash-completion)/borgmatic"
+```
+
+If you don't have `pkg-config` installed, you can try the following path
+instead:
+
+```bash
+sudo su -c "borgmatic --bash-completion > /usr/share/bash-completion/completions/borgmatic"
+```
+
+Or, if you'd like to install the script for just the current user:
+
+```bash
+mkdir --parents ~/.local/share/bash-completion/completions
+borgmatic --bash-completion > ~/.local/share/bash-completion/completions/borgmatic
+```
+
+Finally, restart your shell (`exit` and open a new shell) so the completions
+take effect.
+
+
+### Colored output
+
+borgmatic produces colored terminal output by default. It is disabled when a
 non-interactive terminal is detected (like a cron job), or when you use the
 `--json` flag. Otherwise, you can disable it by passing the `--no-color` flag,
 setting the environment variable `PY_COLORS=False`, or setting the `color`

scripts/run-full-tests

@@ -11,7 +11,7 @@
 set -e
 
 apk add --no-cache python3 py3-pip borgbackup postgresql-client mariadb-client mongodb-tools \
-    py3-ruamel.yaml py3-ruamel.yaml.clib
+    py3-ruamel.yaml py3-ruamel.yaml.clib bash
 # If certain dependencies of black are available in this version of Alpine, install them.
 apk add --no-cache py3-typed-ast py3-regex || true
 python3 -m pip install --no-cache --upgrade pip==22.0.3 setuptools==60.8.1

setup.py

@@ -1,6 +1,6 @@
 from setuptools import find_packages, setup
 
-VERSION = '1.6.1'
+VERSION = '1.6.3.dev0'
 
 
 setup(
@@ -30,12 +30,12 @@ setup(
     },
     obsoletes=['atticmatic'],
     install_requires=(
+        'colorama>=0.4.1,<0.5',
         'jsonschema',
         'requests',
         'ruamel.yaml>0.15.0,<0.18.0',
         'setuptools',
-        'colorama>=0.4.1,<0.5',
     ),
     include_package_data=True,
-    python_requires='>3.7.0',
+    python_requires='>=3.7',
 )

tests/end-to-end/test_completion.py

@@ -0,0 +1,5 @@
+import subprocess
+
+
+def test_bash_completion_runs_without_error():
+    subprocess.check_call('borgmatic --bash-completion | bash', shell=True)

tests/integration/commands/test_arguments.py

@@ -296,15 +296,6 @@ def test_parse_arguments_disallows_init_and_dry_run():
         )
 
 
-def test_parse_arguments_disallows_glob_archives_with_successful():
-    flexmock(module.collect).should_receive('get_default_config_paths').and_return(['default'])
-
-    with pytest.raises(ValueError):
-        module.parse_arguments(
-            '--config', 'myconfig', 'list', '--glob-archives', '*glob*', '--successful'
-        )
-
-
 def test_parse_arguments_disallows_repository_unless_action_consumes_it():
     flexmock(module.collect).should_receive('get_default_config_paths').and_return(['default'])
 

tests/integration/commands/test_completion.py

@@ -0,0 +1,5 @@
+from borgmatic.commands import completion as module
+
+
+def test_bash_completion_does_not_raise():
+    assert module.bash_completion()

tests/integration/commands/test_generate_config.py

@@ -1,13 +1,25 @@
 from borgmatic.commands import generate_config as module
 
 
-def test_parse_arguments_with_no_arguments_uses_defaults():
+def test_parse_arguments_with_no_arguments_uses_default_destination():
     parser = module.parse_arguments()
 
     assert parser.destination_filename == module.DEFAULT_DESTINATION_CONFIG_FILENAME
 
 
-def test_parse_arguments_with_filename_argument_overrides_defaults():
+def test_parse_arguments_with_destination_argument_overrides_default():
     parser = module.parse_arguments('--destination', 'config.yaml')
 
     assert parser.destination_filename == 'config.yaml'
+
+
+def test_parse_arguments_parses_source():
+    parser = module.parse_arguments('--source', 'source.yaml', '--destination', 'config.yaml')
+
+    assert parser.source_filename == 'source.yaml'
+
+
+def test_parse_arguments_parses_overwrite():
+    parser = module.parse_arguments('--destination', 'config.yaml', '--overwrite')
+
+    assert parser.overwrite

tests/integration/config/test_generate.py

@@ -87,7 +87,7 @@ location:
     assert module._comment_out_optional_configuration(config.strip()) == expected_config.strip()
 
 
-def testrender_configuration_converts_configuration_to_yaml_string():
+def test_render_configuration_converts_configuration_to_yaml_string():
     yaml_string = module.render_configuration({'foo': 'bar'})
 
     assert yaml_string == 'foo: bar\n'
@@ -110,6 +110,12 @@ def test_write_configuration_with_already_existing_file_raises():
         module.write_configuration('config.yaml', 'config: yaml')
 
 
+def test_write_configuration_with_already_existing_file_and_overwrite_does_not_raise():
+    flexmock(os.path).should_receive('exists').and_return(True)
+
+    module.write_configuration('config.yaml', 'config: yaml', overwrite=True)
+
+
 def test_write_configuration_with_already_existing_directory_does_not_raise():
     flexmock(os.path).should_receive('exists').and_return(False)
     flexmock(os).should_receive('makedirs').and_raise(FileExistsError)
@@ -212,6 +218,7 @@ def test_generate_sample_configuration_with_source_filename_does_not_raise():
     builtins.should_receive('open').with_args('schema.yaml').and_return('')
     flexmock(module.yaml).should_receive('round_trip_load')
     flexmock(module.load).should_receive('load_configuration')
+    flexmock(module.normalize).should_receive('normalize')
     flexmock(module).should_receive('_schema_to_sample_configuration')
     flexmock(module).should_receive('merge_source_configuration_into_destination')
     flexmock(module).should_receive('render_configuration')

tests/integration/config/test_validate.py

@@ -55,8 +55,8 @@ def test_parse_configuration_transforms_file_into_mapping():
 
         consistency:
             checks:
-                - repository
-                - archives
+                - name: repository
+                - name: archives
         '''
     )
 
@@ -65,7 +65,7 @@ def test_parse_configuration_transforms_file_into_mapping():
     assert result == {
         'location': {'source_directories': ['/home', '/etc'], 'repositories': ['hostname.borg']},
         'retention': {'keep_daily': 7, 'keep_hourly': 24, 'keep_minutely': 60},
-        'consistency': {'checks': ['repository', 'archives']},
+        'consistency': {'checks': [{'name': 'repository'}, {'name': 'archives'}]},
     }
 
 

tests/unit/borg/test_borg.py

@@ -131,3 +131,37 @@ def test_run_arbitrary_borg_passes_key_sub_command_to_borg_before_repository():
     module.run_arbitrary_borg(
         repository='repo', storage_config={}, options=['key', 'export'],
     )
+
+
+def test_run_arbitrary_borg_passes_debug_sub_command_to_borg_before_repository():
+    flexmock(module).should_receive('execute_command').with_args(
+        ('borg', 'debug', 'dump-manifest', 'repo', 'path'),
+        output_log_level=logging.WARNING,
+        borg_local_path='borg',
+    )
+
+    module.run_arbitrary_borg(
+        repository='repo', storage_config={}, options=['debug', 'dump-manifest', 'path'],
+    )
+
+
+def test_run_arbitrary_borg_with_debug_info_command_does_not_pass_borg_repository():
+    flexmock(module).should_receive('execute_command').with_args(
+        ('borg', 'debug', 'info'), output_log_level=logging.WARNING, borg_local_path='borg',
+    )
+
+    module.run_arbitrary_borg(
+        repository='repo', storage_config={}, options=['debug', 'info'],
+    )
+
+
+def test_run_arbitrary_borg_with_debug_convert_profile_command_does_not_pass_borg_repository():
+    flexmock(module).should_receive('execute_command').with_args(
+        ('borg', 'debug', 'convert-profile', 'in', 'out'),
+        output_log_level=logging.WARNING,
+        borg_local_path='borg',
+    )
+
+    module.run_arbitrary_borg(
+        repository='repo', storage_config={}, options=['debug', 'convert-profile', 'in', 'out'],
+    )

tests/unit/borg/test_check.py

@@ -17,172 +17,336 @@ def insert_execute_command_never():
 
 
 def test_parse_checks_returns_them_as_tuple():
-    checks = module._parse_checks({'checks': ['foo', 'disabled', 'bar']})
+    checks = module.parse_checks({'checks': [{'name': 'foo'}, {'name': 'bar'}]})
 
     assert checks == ('foo', 'bar')
 
 
 def test_parse_checks_with_missing_value_returns_defaults():
-    checks = module._parse_checks({})
+    checks = module.parse_checks({})
 
-    assert checks == module.DEFAULT_CHECKS
+    assert checks == ('repository', 'archives')
 
 
-def test_parse_checks_with_blank_value_returns_defaults():
-    checks = module._parse_checks({'checks': []})
+def test_parse_checks_with_empty_list_returns_defaults():
+    checks = module.parse_checks({'checks': []})
 
-    assert checks == module.DEFAULT_CHECKS
+    assert checks == ('repository', 'archives')
 
 
 def test_parse_checks_with_none_value_returns_defaults():
-    checks = module._parse_checks({'checks': None})
+    checks = module.parse_checks({'checks': None})
 
-    assert checks == module.DEFAULT_CHECKS
+    assert checks == ('repository', 'archives')
 
 
 def test_parse_checks_with_disabled_returns_no_checks():
-    checks = module._parse_checks({'checks': ['disabled']})
+    checks = module.parse_checks({'checks': [{'name': 'foo'}, {'name': 'disabled'}]})
 
     assert checks == ()
 
 
 def test_parse_checks_with_data_check_also_injects_archives():
-    checks = module._parse_checks({'checks': ['data']})
+    checks = module.parse_checks({'checks': [{'name': 'data'}]})
 
     assert checks == ('data', 'archives')
 
 
 def test_parse_checks_with_data_check_passes_through_archives():
-    checks = module._parse_checks({'checks': ['data', 'archives']})
+    checks = module.parse_checks({'checks': [{'name': 'data'}, {'name': 'archives'}]})
 
     assert checks == ('data', 'archives')
 
 
 def test_parse_checks_prefers_override_checks_to_configured_checks():
-    checks = module._parse_checks({'checks': ['archives']}, only_checks=['repository', 'extract'])
+    checks = module.parse_checks(
+        {'checks': [{'name': 'archives'}]}, only_checks=['repository', 'extract']
+    )
 
     assert checks == ('repository', 'extract')
 
 
 def test_parse_checks_with_override_data_check_also_injects_archives():
-    checks = module._parse_checks({'checks': ['extract']}, only_checks=['data'])
+    checks = module.parse_checks({'checks': [{'name': 'extract'}]}, only_checks=['data'])
 
     assert checks == ('data', 'archives')
 
 
+@pytest.mark.parametrize(
+    'frequency,expected_result',
+    (
+        (None, None),
+        ('always', None),
+        ('1 hour', module.datetime.timedelta(hours=1)),
+        ('2 hours', module.datetime.timedelta(hours=2)),
+        ('1 day', module.datetime.timedelta(days=1)),
+        ('2 days', module.datetime.timedelta(days=2)),
+        ('1 week', module.datetime.timedelta(weeks=1)),
+        ('2 weeks', module.datetime.timedelta(weeks=2)),
+        ('1 month', module.datetime.timedelta(days=30)),
+        ('2 months', module.datetime.timedelta(days=60)),
+        ('1 year', module.datetime.timedelta(days=365)),
+        ('2 years', module.datetime.timedelta(days=365 * 2)),
+    ),
+)
+def test_parse_frequency_parses_into_timedeltas(frequency, expected_result):
+    assert module.parse_frequency(frequency) == expected_result
+
+
+@pytest.mark.parametrize(
+    'frequency', ('sometime', 'x days', '3 decades',),
+)
+def test_parse_frequency_raises_on_parse_error(frequency):
+    with pytest.raises(ValueError):
+        module.parse_frequency(frequency)
+
+
+def test_filter_checks_on_frequency_without_config_uses_default_checks():
+    flexmock(module).should_receive('parse_frequency').and_return(
+        module.datetime.timedelta(weeks=4)
+    )
+    flexmock(module).should_receive('make_check_time_path')
+    flexmock(module).should_receive('read_check_time').and_return(None)
+
+    assert module.filter_checks_on_frequency(
+        location_config={},
+        consistency_config={},
+        borg_repository_id='repo',
+        checks=('repository', 'archives'),
+        force=False,
+    ) == ('repository', 'archives')
+
+
+def test_filter_checks_on_frequency_retains_unconfigured_check():
+    assert module.filter_checks_on_frequency(
+        location_config={},
+        consistency_config={},
+        borg_repository_id='repo',
+        checks=('data',),
+        force=False,
+    ) == ('data',)
+
+
+def test_filter_checks_on_frequency_retains_check_without_frequency():
+    flexmock(module).should_receive('parse_frequency').and_return(None)
+
+    assert module.filter_checks_on_frequency(
+        location_config={},
+        consistency_config={'checks': [{'name': 'archives'}]},
+        borg_repository_id='repo',
+        checks=('archives',),
+        force=False,
+    ) == ('archives',)
+
+
+def test_filter_checks_on_frequency_retains_check_with_elapsed_frequency():
+    flexmock(module).should_receive('parse_frequency').and_return(
+        module.datetime.timedelta(hours=1)
+    )
+    flexmock(module).should_receive('make_check_time_path')
+    flexmock(module).should_receive('read_check_time').and_return(
+        module.datetime.datetime(year=module.datetime.MINYEAR, month=1, day=1)
+    )
+
+    assert module.filter_checks_on_frequency(
+        location_config={},
+        consistency_config={'checks': [{'name': 'archives', 'frequency': '1 hour'}]},
+        borg_repository_id='repo',
+        checks=('archives',),
+        force=False,
+    ) == ('archives',)
+
+
+def test_filter_checks_on_frequency_retains_check_with_missing_check_time_file():
+    flexmock(module).should_receive('parse_frequency').and_return(
+        module.datetime.timedelta(hours=1)
+    )
+    flexmock(module).should_receive('make_check_time_path')
+    flexmock(module).should_receive('read_check_time').and_return(None)
+
+    assert module.filter_checks_on_frequency(
+        location_config={},
+        consistency_config={'checks': [{'name': 'archives', 'frequency': '1 hour'}]},
+        borg_repository_id='repo',
+        checks=('archives',),
+        force=False,
+    ) == ('archives',)
+
+
+def test_filter_checks_on_frequency_skips_check_with_unelapsed_frequency():
+    flexmock(module).should_receive('parse_frequency').and_return(
+        module.datetime.timedelta(hours=1)
+    )
+    flexmock(module).should_receive('make_check_time_path')
+    flexmock(module).should_receive('read_check_time').and_return(module.datetime.datetime.now())
+
+    assert (
+        module.filter_checks_on_frequency(
+            location_config={},
+            consistency_config={'checks': [{'name': 'archives', 'frequency': '1 hour'}]},
+            borg_repository_id='repo',
+            checks=('archives',),
+            force=False,
+        )
+        == ()
+    )
+
+
+def test_filter_checks_on_frequency_restains_check_with_unelapsed_frequency_and_force():
+    assert module.filter_checks_on_frequency(
+        location_config={},
+        consistency_config={'checks': [{'name': 'archives', 'frequency': '1 hour'}]},
+        borg_repository_id='repo',
+        checks=('archives',),
+        force=True,
+    ) == ('archives',)
+
+
 def test_make_check_flags_with_repository_check_returns_flag():
-    flags = module._make_check_flags(('repository',))
+    flags = module.make_check_flags(('repository',))
 
     assert flags == ('--repository-only',)
 
 
 def test_make_check_flags_with_archives_check_returns_flag():
-    flags = module._make_check_flags(('archives',))
+    flags = module.make_check_flags(('archives',))
 
     assert flags == ('--archives-only',)
 
 
 def test_make_check_flags_with_data_check_returns_flag():
-    flags = module._make_check_flags(('data',))
+    flags = module.make_check_flags(('data',))
 
     assert flags == ('--verify-data',)
 
 
 def test_make_check_flags_with_extract_omits_extract_flag():
-    flags = module._make_check_flags(('extract',))
+    flags = module.make_check_flags(('extract',))
 
     assert flags == ()
 
 
 def test_make_check_flags_with_default_checks_and_default_prefix_returns_default_flags():
-    flags = module._make_check_flags(module.DEFAULT_CHECKS, prefix=module.DEFAULT_PREFIX)
+    flags = module.make_check_flags(('repository', 'archives'), prefix=module.DEFAULT_PREFIX)
 
     assert flags == ('--prefix', module.DEFAULT_PREFIX)
 
 
 def test_make_check_flags_with_all_checks_and_default_prefix_returns_default_flags():
-    flags = module._make_check_flags(
-        module.DEFAULT_CHECKS + ('extract',), prefix=module.DEFAULT_PREFIX
+    flags = module.make_check_flags(
+        ('repository', 'archives', 'extract'), prefix=module.DEFAULT_PREFIX
     )
 
     assert flags == ('--prefix', module.DEFAULT_PREFIX)
 
 
 def test_make_check_flags_with_archives_check_and_last_includes_last_flag():
-    flags = module._make_check_flags(('archives',), check_last=3)
+    flags = module.make_check_flags(('archives',), check_last=3)
 
     assert flags == ('--archives-only', '--last', '3')
 
 
 def test_make_check_flags_with_repository_check_and_last_omits_last_flag():
-    flags = module._make_check_flags(('repository',), check_last=3)
+    flags = module.make_check_flags(('repository',), check_last=3)
 
     assert flags == ('--repository-only',)
 
 
 def test_make_check_flags_with_default_checks_and_last_includes_last_flag():
-    flags = module._make_check_flags(module.DEFAULT_CHECKS, check_last=3)
+    flags = module.make_check_flags(('repository', 'archives'), check_last=3)
 
     assert flags == ('--last', '3')
 
 
 def test_make_check_flags_with_archives_check_and_prefix_includes_prefix_flag():
-    flags = module._make_check_flags(('archives',), prefix='foo-')
+    flags = module.make_check_flags(('archives',), prefix='foo-')
 
     assert flags == ('--archives-only', '--prefix', 'foo-')
 
 
 def test_make_check_flags_with_archives_check_and_empty_prefix_omits_prefix_flag():
-    flags = module._make_check_flags(('archives',), prefix='')
+    flags = module.make_check_flags(('archives',), prefix='')
 
     assert flags == ('--archives-only',)
 
 
 def test_make_check_flags_with_archives_check_and_none_prefix_omits_prefix_flag():
-    flags = module._make_check_flags(('archives',), prefix=None)
+    flags = module.make_check_flags(('archives',), prefix=None)
 
     assert flags == ('--archives-only',)
 
 
 def test_make_check_flags_with_repository_check_and_prefix_omits_prefix_flag():
-    flags = module._make_check_flags(('repository',), prefix='foo-')
+    flags = module.make_check_flags(('repository',), prefix='foo-')
 
     assert flags == ('--repository-only',)
 
 
 def test_make_check_flags_with_default_checks_and_prefix_includes_prefix_flag():
-    flags = module._make_check_flags(module.DEFAULT_CHECKS, prefix='foo-')
+    flags = module.make_check_flags(('repository', 'archives'), prefix='foo-')
 
     assert flags == ('--prefix', 'foo-')
 
 
+def test_read_check_time_does_not_raise():
+    flexmock(module.os).should_receive('stat').and_return(flexmock(st_mtime=123))
+
+    assert module.read_check_time('/path')
+
+
+def test_read_check_time_on_missing_file_does_not_raise():
+    flexmock(module.os).should_receive('stat').and_raise(FileNotFoundError)
+
+    assert module.read_check_time('/path') is None
+
+
 def test_check_archives_with_progress_calls_borg_with_progress_parameter():
     checks = ('repository',)
     consistency_config = {'check_last': None}
-    flexmock(module).should_receive('_parse_checks').and_return(checks)
-    flexmock(module).should_receive('_make_check_flags').and_return(())
+    flexmock(module).should_receive('parse_checks')
+    flexmock(module).should_receive('filter_checks_on_frequency').and_return(checks)
+    flexmock(module.info).should_receive('display_archives_info').and_return(
+        '{"repository": {"id": "repo"}}'
+    )
+    flexmock(module).should_receive('make_check_flags').and_return(())
     flexmock(module).should_receive('execute_command').never()
     flexmock(module).should_receive('execute_command').with_args(
         ('borg', 'check', '--progress', 'repo'), output_file=module.DO_NOT_CAPTURE
     ).once()
+    flexmock(module).should_receive('make_check_time_path')
+    flexmock(module).should_receive('write_check_time')
 
     module.check_archives(
-        repository='repo', storage_config={}, consistency_config=consistency_config, progress=True
+        repository='repo',
+        location_config={},
+        storage_config={},
+        consistency_config=consistency_config,
+        progress=True,
     )
 
 
 def test_check_archives_with_repair_calls_borg_with_repair_parameter():
     checks = ('repository',)
     consistency_config = {'check_last': None}
-    flexmock(module).should_receive('_parse_checks').and_return(checks)
-    flexmock(module).should_receive('_make_check_flags').and_return(())
+    flexmock(module).should_receive('parse_checks')
+    flexmock(module).should_receive('filter_checks_on_frequency').and_return(checks)
+    flexmock(module.info).should_receive('display_archives_info').and_return(
+        '{"repository": {"id": "repo"}}'
+    )
+    flexmock(module).should_receive('make_check_flags').and_return(())
     flexmock(module).should_receive('execute_command').never()
     flexmock(module).should_receive('execute_command').with_args(
         ('borg', 'check', '--repair', 'repo'), output_file=module.DO_NOT_CAPTURE
     ).once()
+    flexmock(module).should_receive('make_check_time_path')
+    flexmock(module).should_receive('write_check_time')
 
     module.check_archives(
-        repository='repo', storage_config={}, consistency_config=consistency_config, repair=True
+        repository='repo',
+        location_config={},
+        storage_config={},
+        consistency_config=consistency_config,
+        repair=True,
     )
 
 
@@ -198,64 +362,142 @@ def test_check_archives_with_repair_calls_borg_with_repair_parameter():
 def test_check_archives_calls_borg_with_parameters(checks):
     check_last = flexmock()
     consistency_config = {'check_last': check_last}
-    flexmock(module).should_receive('_parse_checks').and_return(checks)
-    flexmock(module).should_receive('_make_check_flags').with_args(
+    flexmock(module).should_receive('parse_checks')
+    flexmock(module).should_receive('filter_checks_on_frequency').and_return(checks)
+    flexmock(module.info).should_receive('display_archives_info').and_return(
+        '{"repository": {"id": "repo"}}'
+    )
+    flexmock(module).should_receive('make_check_flags').with_args(
         checks, check_last, module.DEFAULT_PREFIX
     ).and_return(())
     insert_execute_command_mock(('borg', 'check', 'repo'))
+    flexmock(module).should_receive('make_check_time_path')
+    flexmock(module).should_receive('write_check_time')
 
     module.check_archives(
-        repository='repo', storage_config={}, consistency_config=consistency_config
+        repository='repo',
+        location_config={},
+        storage_config={},
+        consistency_config=consistency_config,
     )
 
 
+def test_check_archives_with_json_error_raises():
+    checks = ('archives',)
+    check_last = flexmock()
+    consistency_config = {'check_last': check_last}
+    flexmock(module).should_receive('parse_checks')
+    flexmock(module).should_receive('filter_checks_on_frequency').and_return(checks)
+    flexmock(module.info).should_receive('display_archives_info').and_return(
+        '{"unexpected": {"id": "repo"}}'
+    )
+
+    with pytest.raises(ValueError):
+        module.check_archives(
+            repository='repo',
+            location_config={},
+            storage_config={},
+            consistency_config=consistency_config,
+        )
+
+
+def test_check_archives_with_missing_json_keys_raises():
+    checks = ('archives',)
+    check_last = flexmock()
+    consistency_config = {'check_last': check_last}
+    flexmock(module).should_receive('parse_checks')
+    flexmock(module).should_receive('filter_checks_on_frequency').and_return(checks)
+    flexmock(module.info).should_receive('display_archives_info').and_return('{invalid JSON')
+
+    with pytest.raises(ValueError):
+        module.check_archives(
+            repository='repo',
+            location_config={},
+            storage_config={},
+            consistency_config=consistency_config,
+        )
+
+
 def test_check_archives_with_extract_check_calls_extract_only():
     checks = ('extract',)
     check_last = flexmock()
     consistency_config = {'check_last': check_last}
-    flexmock(module).should_receive('_parse_checks').and_return(checks)
-    flexmock(module).should_receive('_make_check_flags').never()
+    flexmock(module).should_receive('parse_checks')
+    flexmock(module).should_receive('filter_checks_on_frequency').and_return(checks)
+    flexmock(module.info).should_receive('display_archives_info').and_return(
+        '{"repository": {"id": "repo"}}'
+    )
+    flexmock(module).should_receive('make_check_flags').never()
     flexmock(module.extract).should_receive('extract_last_archive_dry_run').once()
+    flexmock(module).should_receive('write_check_time')
     insert_execute_command_never()
 
     module.check_archives(
-        repository='repo', storage_config={}, consistency_config=consistency_config
+        repository='repo',
+        location_config={},
+        storage_config={},
+        consistency_config=consistency_config,
     )
 
 
 def test_check_archives_with_log_info_calls_borg_with_info_parameter():
     checks = ('repository',)
     consistency_config = {'check_last': None}
-    flexmock(module).should_receive('_parse_checks').and_return(checks)
-    flexmock(module).should_receive('_make_check_flags').and_return(())
+    flexmock(module).should_receive('parse_checks')
+    flexmock(module).should_receive('filter_checks_on_frequency').and_return(checks)
+    flexmock(module.info).should_receive('display_archives_info').and_return(
+        '{"repository": {"id": "repo"}}'
+    )
+    flexmock(module).should_receive('make_check_flags').and_return(())
     insert_logging_mock(logging.INFO)
     insert_execute_command_mock(('borg', 'check', '--info', 'repo'))
+    flexmock(module).should_receive('make_check_time_path')
+    flexmock(module).should_receive('write_check_time')
 
     module.check_archives(
-        repository='repo', storage_config={}, consistency_config=consistency_config
+        repository='repo',
+        location_config={},
+        storage_config={},
+        consistency_config=consistency_config,
     )
 
 
 def test_check_archives_with_log_debug_calls_borg_with_debug_parameter():
     checks = ('repository',)
     consistency_config = {'check_last': None}
-    flexmock(module).should_receive('_parse_checks').and_return(checks)
-    flexmock(module).should_receive('_make_check_flags').and_return(())
+    flexmock(module).should_receive('parse_checks')
+    flexmock(module).should_receive('filter_checks_on_frequency').and_return(checks)
+    flexmock(module.info).should_receive('display_archives_info').and_return(
+        '{"repository": {"id": "repo"}}'
+    )
+    flexmock(module).should_receive('make_check_flags').and_return(())
     insert_logging_mock(logging.DEBUG)
     insert_execute_command_mock(('borg', 'check', '--debug', '--show-rc', 'repo'))
+    flexmock(module).should_receive('make_check_time_path')
+    flexmock(module).should_receive('write_check_time')
 
     module.check_archives(
-        repository='repo', storage_config={}, consistency_config=consistency_config
+        repository='repo',
+        location_config={},
+        storage_config={},
+        consistency_config=consistency_config,
     )
 
 
 def test_check_archives_without_any_checks_bails():
     consistency_config = {'check_last': None}
-    flexmock(module).should_receive('_parse_checks').and_return(())
+    flexmock(module).should_receive('parse_checks')
+    flexmock(module).should_receive('filter_checks_on_frequency').and_return(())
+    flexmock(module.info).should_receive('display_archives_info').and_return(
+        '{"repository": {"id": "repo"}}'
+    )
     insert_execute_command_never()
 
     module.check_archives(
-        repository='repo', storage_config={}, consistency_config=consistency_config
+        repository='repo',
+        location_config={},
+        storage_config={},
+        consistency_config=consistency_config,
     )
 
 
@@ -263,14 +505,21 @@ def test_check_archives_with_local_path_calls_borg_via_local_path():
     checks = ('repository',)
     check_last = flexmock()
     consistency_config = {'check_last': check_last}
-    flexmock(module).should_receive('_parse_checks').and_return(checks)
-    flexmock(module).should_receive('_make_check_flags').with_args(
+    flexmock(module).should_receive('parse_checks')
+    flexmock(module).should_receive('filter_checks_on_frequency').and_return(checks)
+    flexmock(module.info).should_receive('display_archives_info').and_return(
+        '{"repository": {"id": "repo"}}'
+    )
+    flexmock(module).should_receive('make_check_flags').with_args(
         checks, check_last, module.DEFAULT_PREFIX
     ).and_return(())
     insert_execute_command_mock(('borg1', 'check', 'repo'))
+    flexmock(module).should_receive('make_check_time_path')
+    flexmock(module).should_receive('write_check_time')
 
     module.check_archives(
         repository='repo',
+        location_config={},
         storage_config={},
         consistency_config=consistency_config,
         local_path='borg1',
@@ -281,14 +530,21 @@ def test_check_archives_with_remote_path_calls_borg_with_remote_path_parameters(
     checks = ('repository',)
     check_last = flexmock()
     consistency_config = {'check_last': check_last}
-    flexmock(module).should_receive('_parse_checks').and_return(checks)
-    flexmock(module).should_receive('_make_check_flags').with_args(
+    flexmock(module).should_receive('parse_checks')
+    flexmock(module).should_receive('filter_checks_on_frequency').and_return(checks)
+    flexmock(module.info).should_receive('display_archives_info').and_return(
+        '{"repository": {"id": "repo"}}'
+    )
+    flexmock(module).should_receive('make_check_flags').with_args(
         checks, check_last, module.DEFAULT_PREFIX
     ).and_return(())
     insert_execute_command_mock(('borg', 'check', '--remote-path', 'borg1', 'repo'))
+    flexmock(module).should_receive('make_check_time_path')
+    flexmock(module).should_receive('write_check_time')
 
     module.check_archives(
         repository='repo',
+        location_config={},
         storage_config={},
         consistency_config=consistency_config,
         remote_path='borg1',
@@ -299,14 +555,23 @@ def test_check_archives_with_lock_wait_calls_borg_with_lock_wait_parameters():
     checks = ('repository',)
     check_last = flexmock()
     consistency_config = {'check_last': check_last}
-    flexmock(module).should_receive('_parse_checks').and_return(checks)
-    flexmock(module).should_receive('_make_check_flags').with_args(
+    flexmock(module).should_receive('parse_checks')
+    flexmock(module).should_receive('filter_checks_on_frequency').and_return(checks)
+    flexmock(module.info).should_receive('display_archives_info').and_return(
+        '{"repository": {"id": "repo"}}'
+    )
+    flexmock(module).should_receive('make_check_flags').with_args(
         checks, check_last, module.DEFAULT_PREFIX
     ).and_return(())
     insert_execute_command_mock(('borg', 'check', '--lock-wait', '5', 'repo'))
+    flexmock(module).should_receive('make_check_time_path')
+    flexmock(module).should_receive('write_check_time')
 
     module.check_archives(
-        repository='repo', storage_config={'lock_wait': 5}, consistency_config=consistency_config
+        repository='repo',
+        location_config={},
+        storage_config={'lock_wait': 5},
+        consistency_config=consistency_config,
     )
 
 
@@ -315,26 +580,42 @@ def test_check_archives_with_retention_prefix():
     check_last = flexmock()
     prefix = 'foo-'
     consistency_config = {'check_last': check_last, 'prefix': prefix}
-    flexmock(module).should_receive('_parse_checks').and_return(checks)
-    flexmock(module).should_receive('_make_check_flags').with_args(
+    flexmock(module).should_receive('parse_checks')
+    flexmock(module).should_receive('filter_checks_on_frequency').and_return(checks)
+    flexmock(module.info).should_receive('display_archives_info').and_return(
+        '{"repository": {"id": "repo"}}'
+    )
+    flexmock(module).should_receive('make_check_flags').with_args(
         checks, check_last, prefix
     ).and_return(())
     insert_execute_command_mock(('borg', 'check', 'repo'))
+    flexmock(module).should_receive('make_check_time_path')
+    flexmock(module).should_receive('write_check_time')
 
     module.check_archives(
-        repository='repo', storage_config={}, consistency_config=consistency_config
+        repository='repo',
+        location_config={},
+        storage_config={},
+        consistency_config=consistency_config,
     )
 
 
 def test_check_archives_with_extra_borg_options_calls_borg_with_extra_options():
     checks = ('repository',)
     consistency_config = {'check_last': None}
-    flexmock(module).should_receive('_parse_checks').and_return(checks)
-    flexmock(module).should_receive('_make_check_flags').and_return(())
+    flexmock(module).should_receive('parse_checks')
+    flexmock(module).should_receive('filter_checks_on_frequency').and_return(checks)
+    flexmock(module.info).should_receive('display_archives_info').and_return(
+        '{"repository": {"id": "repo"}}'
+    )
+    flexmock(module).should_receive('make_check_flags').and_return(())
     insert_execute_command_mock(('borg', 'check', '--extra', '--options', 'repo'))
+    flexmock(module).should_receive('make_check_time_path')
+    flexmock(module).should_receive('write_check_time')
 
     module.check_archives(
         repository='repo',
+        location_config={},
         storage_config={'extra_borg_options': {'check': '--extra --options'}},
         consistency_config=consistency_config,
     )

tests/unit/borg/test_create.py

@@ -271,7 +271,9 @@ def test_borgmatic_source_directories_defaults_when_directory_not_given():
     flexmock(module.os.path).should_receive('exists').and_return(True)
     flexmock(module.os.path).should_receive('expanduser')
 
-    assert module.borgmatic_source_directories(None) == [module.DEFAULT_BORGMATIC_SOURCE_DIRECTORY]
+    assert module.borgmatic_source_directories(None) == [
+        module.state.DEFAULT_BORGMATIC_SOURCE_DIRECTORY
+    ]
 
 
 DEFAULT_ARCHIVE_NAME = '{hostname}-{now:%Y-%m-%dT%H:%M:%S.%f}'

tests/unit/borg/test_init.py

@@ -13,11 +13,11 @@ INIT_COMMAND = ('borg', 'init', '--encryption', 'repokey')
 
 
 def insert_info_command_found_mock():
-    flexmock(module).should_receive('execute_command')
+    flexmock(module.info).should_receive('display_archives_info')
 
 
 def insert_info_command_not_found_mock():
-    flexmock(module).should_receive('execute_command').and_raise(
+    flexmock(module.info).should_receive('display_archives_info').and_raise(
         subprocess.CalledProcessError(module.INFO_REPOSITORY_NOT_FOUND_EXIT_CODE, [])
     )
 
@@ -48,13 +48,13 @@ def test_initialize_repository_raises_for_borg_init_error():
 
 
 def test_initialize_repository_skips_initialization_when_repository_already_exists():
-    flexmock(module).should_receive('execute_command').once()
+    insert_info_command_found_mock()
 
     module.initialize_repository(repository='repo', storage_config={}, encryption_mode='repokey')
 
 
 def test_initialize_repository_raises_for_unknown_info_command_error():
-    flexmock(module).should_receive('execute_command').and_raise(
+    flexmock(module.info).should_receive('display_archives_info').and_raise(
         subprocess.CalledProcessError(INFO_SOME_UNKNOWN_EXIT_CODE, [])
     )
 

tests/unit/borg/test_list.py

@@ -1,3 +1,4 @@
+import argparse
 import logging
 
 import pytest
@@ -8,8 +9,6 @@ from borgmatic.borg import list as module
 from ..test_verbosity import insert_logging_mock
 
 BORG_LIST_LATEST_ARGUMENTS = (
-    '--glob-archives',
-    module.BORG_EXCLUDE_CHECKPOINTS_GLOB,
     '--last',
     '1',
     '--short',
@@ -108,156 +107,125 @@ def test_resolve_archive_name_with_lock_wait_calls_borg_with_lock_wait_parameter
     )
 
 
-def test_list_archives_calls_borg_with_parameters():
-    flexmock(module).should_receive('execute_command').with_args(
-        ('borg', 'list', 'repo'), output_log_level=logging.WARNING, borg_local_path='borg'
-    )
-
-    module.list_archives(
-        repository='repo',
-        storage_config={},
-        list_arguments=flexmock(archive=None, paths=None, json=False, successful=False),
-    )
-
-
-def test_list_archives_with_log_info_calls_borg_with_info_parameter():
-    flexmock(module).should_receive('execute_command').with_args(
-        ('borg', 'list', '--info', 'repo'), output_log_level=logging.WARNING, borg_local_path='borg'
-    )
+def test_make_list_command_includes_log_info():
     insert_logging_mock(logging.INFO)
 
-    module.list_archives(
+    command = module.make_list_command(
         repository='repo',
         storage_config={},
-        list_arguments=flexmock(archive=None, paths=None, json=False, successful=False),
+        list_arguments=flexmock(archive=None, paths=None, json=False),
     )
 
+    assert command == ('borg', 'list', '--info', 'repo')
 
-def test_list_archives_with_log_info_and_json_suppresses_most_borg_output():
-    flexmock(module).should_receive('execute_command').with_args(
-        ('borg', 'list', '--json', 'repo'), output_log_level=None, borg_local_path='borg'
-    )
+
+def test_make_list_command_includes_json_but_not_info():
     insert_logging_mock(logging.INFO)
 
-    module.list_archives(
+    command = module.make_list_command(
         repository='repo',
         storage_config={},
-        list_arguments=flexmock(archive=None, paths=None, json=True, successful=False),
+        list_arguments=flexmock(archive=None, paths=None, json=True),
     )
 
+    assert command == ('borg', 'list', '--json', 'repo')
 
-def test_list_archives_with_log_debug_calls_borg_with_debug_parameter():
-    flexmock(module).should_receive('execute_command').with_args(
-        ('borg', 'list', '--debug', '--show-rc', 'repo'),
-        output_log_level=logging.WARNING,
-        borg_local_path='borg',
-    )
+
+def test_make_list_command_includes_log_debug():
     insert_logging_mock(logging.DEBUG)
 
-    module.list_archives(
+    command = module.make_list_command(
         repository='repo',
         storage_config={},
-        list_arguments=flexmock(archive=None, paths=None, json=False, successful=False),
+        list_arguments=flexmock(archive=None, paths=None, json=False),
     )
 
+    assert command == ('borg', 'list', '--debug', '--show-rc', 'repo')
 
-def test_list_archives_with_log_debug_and_json_suppresses_most_borg_output():
-    flexmock(module).should_receive('execute_command').with_args(
-        ('borg', 'list', '--json', 'repo'), output_log_level=None, borg_local_path='borg'
-    )
+
+def test_make_list_command_includes_json_but_not_debug():
     insert_logging_mock(logging.DEBUG)
 
-    module.list_archives(
+    command = module.make_list_command(
         repository='repo',
         storage_config={},
-        list_arguments=flexmock(archive=None, paths=None, json=True, successful=False),
+        list_arguments=flexmock(archive=None, paths=None, json=True),
     )
 
-
-def test_list_archives_with_lock_wait_calls_borg_with_lock_wait_parameters():
-    storage_config = {'lock_wait': 5}
-    flexmock(module).should_receive('execute_command').with_args(
-        ('borg', 'list', '--lock-wait', '5', 'repo'),
-        output_log_level=logging.WARNING,
-        borg_local_path='borg',
-    )
-
-    module.list_archives(
-        repository='repo',
-        storage_config=storage_config,
-        list_arguments=flexmock(archive=None, paths=None, json=False, successful=False),
-    )
+    assert command == ('borg', 'list', '--json', 'repo')
 
 
-def test_list_archives_with_archive_calls_borg_with_archive_parameter():
-    storage_config = {}
-    flexmock(module).should_receive('execute_command').with_args(
-        ('borg', 'list', 'repo::archive'), output_log_level=logging.WARNING, borg_local_path='borg'
-    )
-
-    module.list_archives(
-        repository='repo',
-        storage_config=storage_config,
-        list_arguments=flexmock(archive='archive', paths=None, json=False, successful=False),
-    )
-
-
-def test_list_archives_with_path_calls_borg_with_path_parameter():
-    storage_config = {}
-    flexmock(module).should_receive('execute_command').with_args(
-        ('borg', 'list', 'repo::archive', 'var/lib'),
-        output_log_level=logging.WARNING,
-        borg_local_path='borg',
-    )
-
-    module.list_archives(
-        repository='repo',
-        storage_config=storage_config,
-        list_arguments=flexmock(archive='archive', paths=['var/lib'], json=False, successful=False),
-    )
-
-
-def test_list_archives_with_local_path_calls_borg_via_local_path():
-    flexmock(module).should_receive('execute_command').with_args(
-        ('borg1', 'list', 'repo'), output_log_level=logging.WARNING, borg_local_path='borg1'
-    )
-
-    module.list_archives(
+def test_make_list_command_includes_json():
+    command = module.make_list_command(
         repository='repo',
         storage_config={},
-        list_arguments=flexmock(archive=None, paths=None, json=False, successful=False),
-        local_path='borg1',
+        list_arguments=flexmock(archive=None, paths=None, json=True),
     )
 
+    assert command == ('borg', 'list', '--json', 'repo')
 
-def test_list_archives_with_remote_path_calls_borg_with_remote_path_parameters():
-    flexmock(module).should_receive('execute_command').with_args(
-        ('borg', 'list', '--remote-path', 'borg1', 'repo'),
-        output_log_level=logging.WARNING,
-        borg_local_path='borg',
+
+def test_make_list_command_includes_lock_wait():
+    command = module.make_list_command(
+        repository='repo',
+        storage_config={'lock_wait': 5},
+        list_arguments=flexmock(archive=None, paths=None, json=False),
     )
 
-    module.list_archives(
+    assert command == ('borg', 'list', '--lock-wait', '5', 'repo')
+
+
+def test_make_list_command_includes_archive():
+    command = module.make_list_command(
         repository='repo',
         storage_config={},
-        list_arguments=flexmock(archive=None, paths=None, json=False, successful=False),
-        remote_path='borg1',
+        list_arguments=flexmock(archive='archive', paths=None, json=False),
     )
 
+    assert command == ('borg', 'list', 'repo::archive')
 
-def test_list_archives_with_short_calls_borg_with_short_parameter():
-    flexmock(module).should_receive('execute_command').with_args(
-        ('borg', 'list', '--short', 'repo'),
-        output_log_level=logging.WARNING,
-        borg_local_path='borg',
-    ).and_return('[]')
 
-    module.list_archives(
+def test_make_list_command_includes_archive_and_path():
+    command = module.make_list_command(
         repository='repo',
         storage_config={},
-        list_arguments=flexmock(archive=None, paths=None, json=False, successful=False, short=True),
+        list_arguments=flexmock(archive='archive', paths=['var/lib'], json=False),
     )
 
+    assert command == ('borg', 'list', 'repo::archive', 'var/lib')
+
+
+def test_make_list_command_includes_local_path():
+    command = module.make_list_command(
+        repository='repo',
+        storage_config={},
+        list_arguments=flexmock(archive=None, paths=None, json=False),
+        local_path='borg2',
+    )
+
+    assert command == ('borg2', 'list', 'repo')
+
+
+def test_make_list_command_includes_remote_path():
+    command = module.make_list_command(
+        repository='repo',
+        storage_config={},
+        list_arguments=flexmock(archive=None, paths=None, json=False),
+        remote_path='borg2',
+    )
+
+    assert command == ('borg', 'list', '--remote-path', 'borg2', 'repo')
+
+
+def test_make_list_command_includes_short():
+    command = module.make_list_command(
+        repository='repo',
+        storage_config={},
+        list_arguments=flexmock(archive=None, paths=None, json=False, short=True),
+    )
+
+    assert command == ('borg', 'list', '--short', 'repo')
+
 
 @pytest.mark.parametrize(
     'argument_name',
@@ -273,45 +241,156 @@ def test_list_archives_with_short_calls_borg_with_short_parameter():
         'patterns_from',
     ),
 )
-def test_list_archives_passes_through_arguments_to_borg(argument_name):
-    flexmock(module).should_receive('execute_command').with_args(
-        ('borg', 'list', '--' + argument_name.replace('_', '-'), 'value', 'repo'),
-        output_log_level=logging.WARNING,
-        borg_local_path='borg',
-    ).and_return('[]')
-
-    module.list_archives(
+def test_make_list_command_includes_additional_flags(argument_name):
+    command = module.make_list_command(
         repository='repo',
         storage_config={},
         list_arguments=flexmock(
-            archive=None, paths=None, json=False, successful=False, **{argument_name: 'value'}
+            archive=None,
+            paths=None,
+            json=False,
+            find_paths=None,
+            format=None,
+            **{argument_name: 'value'}
         ),
     )
 
+    assert command == ('borg', 'list', '--' + argument_name.replace('_', '-'), 'value', 'repo')
 
-def test_list_archives_with_successful_calls_borg_to_exclude_checkpoints():
+
+def test_make_find_paths_considers_none_as_empty_paths():
+    assert module.make_find_paths(None) == ()
+
+
+def test_make_find_paths_passes_through_patterns():
+    find_paths = (
+        'fm:*',
+        'sh:**/*.txt',
+        're:^.*$',
+        'pp:root/somedir',
+        'pf:root/foo.txt',
+        'R /',
+        'r /',
+        'p /',
+        'P /',
+        '+ /',
+        '- /',
+        '! /',
+    )
+
+    assert module.make_find_paths(find_paths) == find_paths
+
+
+def test_make_find_paths_adds_globs_to_path_fragments():
+    assert module.make_find_paths(('foo.txt',)) == ('sh:**/*foo.txt*/**',)
+
+
+def test_list_archives_calls_borg_with_parameters():
+    list_arguments = argparse.Namespace(archive=None, paths=None, json=False, find_paths=None)
+
+    flexmock(module).should_receive('make_list_command').with_args(
+        repository='repo',
+        storage_config={},
+        list_arguments=list_arguments,
+        local_path='borg',
+        remote_path=None,
+    ).and_return(('borg', 'list', 'repo'))
+    flexmock(module).should_receive('make_find_paths').and_return(())
     flexmock(module).should_receive('execute_command').with_args(
-        ('borg', 'list', '--glob-archives', module.BORG_EXCLUDE_CHECKPOINTS_GLOB, 'repo'),
-        output_log_level=logging.WARNING,
-        borg_local_path='borg',
-    ).and_return('[]')
+        ('borg', 'list', 'repo'), output_log_level=logging.WARNING, borg_local_path='borg'
+    ).once()
 
     module.list_archives(
-        repository='repo',
-        storage_config={},
-        list_arguments=flexmock(archive=None, paths=None, json=False, successful=True),
+        repository='repo', storage_config={}, list_arguments=list_arguments,
     )
 
 
-def test_list_archives_with_json_calls_borg_with_json_parameter():
+def test_list_archives_with_json_suppresses_most_borg_output():
+    list_arguments = argparse.Namespace(archive=None, paths=None, json=True, find_paths=None)
+
+    flexmock(module).should_receive('make_list_command').with_args(
+        repository='repo',
+        storage_config={},
+        list_arguments=list_arguments,
+        local_path='borg',
+        remote_path=None,
+    ).and_return(('borg', 'list', 'repo'))
+    flexmock(module).should_receive('make_find_paths').and_return(())
     flexmock(module).should_receive('execute_command').with_args(
-        ('borg', 'list', '--json', 'repo'), output_log_level=None, borg_local_path='borg'
-    ).and_return('[]')
+        ('borg', 'list', 'repo'), output_log_level=None, borg_local_path='borg'
+    ).once()
 
-    json_output = module.list_archives(
-        repository='repo',
-        storage_config={},
-        list_arguments=flexmock(archive=None, paths=None, json=True, successful=False),
+    module.list_archives(
+        repository='repo', storage_config={}, list_arguments=list_arguments,
     )
 
-    assert json_output == '[]'
+
+def test_list_archives_calls_borg_with_local_path():
+    list_arguments = argparse.Namespace(archive=None, paths=None, json=False, find_paths=None)
+
+    flexmock(module).should_receive('make_list_command').with_args(
+        repository='repo',
+        storage_config={},
+        list_arguments=list_arguments,
+        local_path='borg2',
+        remote_path=None,
+    ).and_return(('borg2', 'list', 'repo'))
+    flexmock(module).should_receive('make_find_paths').and_return(())
+    flexmock(module).should_receive('execute_command').with_args(
+        ('borg2', 'list', 'repo'), output_log_level=logging.WARNING, borg_local_path='borg2'
+    ).once()
+
+    module.list_archives(
+        repository='repo', storage_config={}, list_arguments=list_arguments, local_path='borg2',
+    )
+
+
+def test_list_archives_calls_borg_multiple_times_with_find_paths():
+    glob_paths = ('**/*foo.txt*/**',)
+    list_arguments = argparse.Namespace(
+        archive=None, paths=None, json=False, find_paths=['foo.txt'], format=None
+    )
+
+    flexmock(module).should_receive('make_list_command').and_return(
+        ('borg', 'list', 'repo')
+    ).and_return(('borg', 'list', 'repo::archive1')).and_return(('borg', 'list', 'repo::archive2'))
+    flexmock(module).should_receive('make_find_paths').and_return(glob_paths)
+    flexmock(module).should_receive('execute_command').with_args(
+        ('borg', 'list', 'repo'), output_log_level=None, borg_local_path='borg'
+    ).and_return(
+        'archive1   Sun, 2022-05-29 15:27:04 [abc]\narchive2   Mon, 2022-05-30 19:47:15 [xyz]'
+    ).once()
+    flexmock(module).should_receive('execute_command').with_args(
+        ('borg', 'list', 'repo::archive1') + glob_paths,
+        output_log_level=logging.WARNING,
+        borg_local_path='borg',
+    ).once()
+    flexmock(module).should_receive('execute_command').with_args(
+        ('borg', 'list', 'repo::archive2') + glob_paths,
+        output_log_level=logging.WARNING,
+        borg_local_path='borg',
+    ).once()
+
+    module.list_archives(
+        repository='repo', storage_config={}, list_arguments=list_arguments,
+    )
+
+
+def test_list_archives_calls_borg_with_archive():
+    list_arguments = argparse.Namespace(archive='archive', paths=None, json=False, find_paths=None)
+
+    flexmock(module).should_receive('make_list_command').with_args(
+        repository='repo',
+        storage_config={},
+        list_arguments=list_arguments,
+        local_path='borg',
+        remote_path=None,
+    ).and_return(('borg', 'list', 'repo::archive'))
+    flexmock(module).should_receive('make_find_paths').and_return(())
+    flexmock(module).should_receive('execute_command').with_args(
+        ('borg', 'list', 'repo::archive'), output_log_level=logging.WARNING, borg_local_path='borg'
+    ).once()
+
+    module.list_archives(
+        repository='repo', storage_config={}, list_arguments=list_arguments,
+    )

tests/unit/commands/test_borgmatic.py

@@ -468,7 +468,9 @@ def test_run_actions_calls_hooks_for_check_action():
     flexmock(module.command).should_receive('execute_hook').twice()
     arguments = {
         'global': flexmock(monitoring_verbosity=1, dry_run=False),
-        'check': flexmock(progress=flexmock(), repair=flexmock(), only=flexmock()),
+        'check': flexmock(
+            progress=flexmock(), repair=flexmock(), only=flexmock(), force=flexmock()
+        ),
     }
 
     list(

tests/unit/config/test_normalize.py

@@ -35,6 +35,10 @@ from borgmatic.config import normalize as module
             {'hooks': {'cronhub': 'https://example.com'}},
             {'hooks': {'cronhub': {'ping_url': 'https://example.com'}}},
         ),
+        (
+            {'consistency': {'checks': ['archives']}},
+            {'consistency': {'checks': [{'name': 'archives'}]}},
+        ),
     ),
 )
 def test_normalize_applies_hard_coded_normalization_to_config(config, expected_config):

tests/unit/hooks/test_healthchecks.py

@@ -69,10 +69,18 @@ def test_format_buffered_logs_for_payload_without_handler_produces_empty_payload
     assert payload == ''
 
 
+def mock_logger():
+    logger = flexmock()
+    logger.should_receive('addHandler')
+    logger.should_receive('removeHandler')
+    flexmock(module.logging).should_receive('getLogger').and_return(logger)
+
+
 def test_initialize_monitor_creates_log_handler_with_ping_body_limit():
     ping_body_limit = 100
     monitoring_log_level = 1
 
+    mock_logger()
     flexmock(module).should_receive('Forgetful_buffering_handler').with_args(
         ping_body_limit - len(module.PAYLOAD_TRUNCATION_INDICATOR), monitoring_log_level
     ).once()
@@ -85,6 +93,7 @@ def test_initialize_monitor_creates_log_handler_with_ping_body_limit():
 def test_initialize_monitor_creates_log_handler_with_default_ping_body_limit():
     monitoring_log_level = 1
 
+    mock_logger()
     flexmock(module).should_receive('Forgetful_buffering_handler').with_args(
         module.DEFAULT_PING_BODY_LIMIT_BYTES - len(module.PAYLOAD_TRUNCATION_INDICATOR),
         monitoring_log_level,
@@ -97,6 +106,7 @@ def test_initialize_monitor_creates_log_handler_with_zero_ping_body_limit():
     ping_body_limit = 0
     monitoring_log_level = 1
 
+    mock_logger()
     flexmock(module).should_receive('Forgetful_buffering_handler').with_args(
         ping_body_limit, monitoring_log_level
     ).once()
@@ -107,6 +117,7 @@ def test_initialize_monitor_creates_log_handler_with_zero_ping_body_limit():
 
 
 def test_initialize_monitor_creates_log_handler_when_send_logs_true():
+    mock_logger()
     flexmock(module).should_receive('Forgetful_buffering_handler').once()
 
     module.initialize_monitor(
@@ -115,6 +126,7 @@ def test_initialize_monitor_creates_log_handler_when_send_logs_true():
 
 
 def test_initialize_monitor_bails_when_send_logs_false():
+    mock_logger()
     flexmock(module).should_receive('Forgetful_buffering_handler').never()
 
     module.initialize_monitor(