Bump version for release.

Reviewed-on: https://projects.torsion.org/borgmatic-collective/borgmatic/pulls/893

NEWS

@@ -1,3 +1,56 @@
+1.8.13
+ * #298: Add "delete" and "rdelete" actions to delete archives or entire repositories.
+ * #785: Add an "only_run_on" option to consistency checks so you can limit a check to running on
+   particular days of the week. See the documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/deal-with-very-large-backups/#check-days
+ * #885: Add an Uptime Kuma monitoring hook. See the documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#uptime-kuma-hook
+ * #886: Fix a PagerDuty hook traceback with Python < 3.10.
+ * #889: Fix the Healthchecks ping body size limit, restoring it to the documented 100,000 bytes.
+
+1.8.12
+ * #817: Add a "--max-duration" flag to the "check" action and a "max_duration" option to the
+   repository check configuration. This tells Borg to interrupt a repository check after a certain
+   duration.
+ * #860: Fix interaction between environment variable interpolation in constants and shell escaping.
+ * #863: When color output is disabled (explicitly or implicitly), don't prefix each log line with
+   the log level.
+ * #865: Add an "upload_buffer_size" option to set the size of the upload buffer used in "create"
+   action.
+ * #866: Fix "Argument list too long" error in the "spot" check when checking hundreds of thousands
+   of files at once.
+ * #874: Add the configured repository label as "repository_label" to the interpolated variables
+   passed to before/after command hooks.
+ * #881: Fix "Unrecognized argument" error when the same value is used with different command-line
+   flags.
+ * In the "spot" check, don't try to hash symlinked directories.
+
+1.8.11
+ * #815: Add optional Healthchecks auto-provisioning via "create_slug" option.
+ * #851: Fix lack of file extraction when using "extract --strip-components all" on a path with a
+   leading slash.
+ * #854: Fix a traceback when the "data" consistency check is used.
+ * #857: Fix a traceback with "check --only spot" when the "spot" check is unconfigured.
+
+1.8.10
+ * #656 (beta): Add a "spot" consistency check that compares file counts and contents between your
+   source files and the latest archive, ensuring they fall within configured tolerances. This can
+   catch problems like incorrect excludes, inadvertent deletes, files changed by malware, etc. See
+   the documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/deal-with-very-large-backups/#spot-check
+ * #779: When "--match-archives *" is used with "check" action, don't skip Borg's orphaned objects
+   check.
+ * #842: When a command hook exits with a soft failure, ping the log and finish states for any
+   configured monitoring hooks.
+ * #843: Add documentation link to Loki dashboard for borgmatic:
+   https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#loki-hook
+ * #847: Fix "--json" error when Borg includes non-JSON warnings in JSON output.
+ * #848: SECURITY: Mask the password when logging a MongoDB dump or restore command.
+ * Fix handling of the NO_COLOR environment variable to ignore an empty value.
+ * Add documentation about backing up containerized databases by configuring borgmatic to exec into
+   a container to run a dump command:
+   https://torsion.org/borgmatic/docs/how-to/backup-your-databases/#containers
+
 1.8.9
  * #311: Add custom dump/restore command options for MySQL and MariaDB.
  * #811: Add an "access_token" option to the ntfy monitoring hook for authenticating

README.md

@@ -62,6 +62,7 @@ borgmatic is powered by [Borg Backup](https://www.borgbackup.org/).
 <a href="https://www.mongodb.com/"><img src="docs/static/mongodb.png" alt="MongoDB" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
 <a href="https://sqlite.org/"><img src="docs/static/sqlite.png" alt="SQLite" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
 <a href="https://healthchecks.io/"><img src="docs/static/healthchecks.png" alt="Healthchecks" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
+<a href="https://uptime.kuma.pet/"><img src="docs/static/uptimekuma.png" alt="Uptime Kuma" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
 <a href="https://cronitor.io/"><img src="docs/static/cronitor.png" alt="Cronitor" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
 <a href="https://cronhub.io/"><img src="docs/static/cronhub.png" alt="Cronhub" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
 <a href="https://www.pagerduty.com/"><img src="docs/static/pagerduty.png" alt="PagerDuty" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>

borgmatic/actions/check.py

@@ -1,12 +1,631 @@
+import calendar
+import datetime
+import hashlib
+import itertools
 import logging
+import os
+import pathlib
+import random
 
 import borgmatic.borg.check
+import borgmatic.borg.create
+import borgmatic.borg.environment
+import borgmatic.borg.extract
+import borgmatic.borg.list
+import borgmatic.borg.rlist
+import borgmatic.borg.state
 import borgmatic.config.validate
+import borgmatic.execute
 import borgmatic.hooks.command
 
+DEFAULT_CHECKS = (
+    {'name': 'repository', 'frequency': '1 month'},
+    {'name': 'archives', 'frequency': '1 month'},
+)
+
+
 logger = logging.getLogger(__name__)
 
 
+def parse_checks(config, only_checks=None):
+    '''
+    Given a configuration dict 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 config of:
+
+        {'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 a checks value
+    has a name of "disabled", return an empty tuple, meaning that no checks should be run.
+    '''
+    checks = only_checks or tuple(
+        check_config['name'] for check_config in (config.get('checks', None) or DEFAULT_CHECKS)
+    )
+    checks = tuple(check.lower() for check in checks)
+
+    if 'disabled' in checks:
+        logger.warning(
+            'The "disabled" value for the "checks" option is deprecated and will be removed from a future release; use "skip_actions" instead'
+        )
+        if len(checks) > 1:
+            logger.warning(
+                'Multiple checks are configured, but one of them is "disabled"; not running any checks'
+            )
+        return ()
+
+    return checks
+
+
+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}'")
+
+
+WEEKDAY_DAYS = calendar.day_name[0:5]
+WEEKEND_DAYS = calendar.day_name[5:7]
+
+
+def filter_checks_on_frequency(
+    config,
+    borg_repository_id,
+    checks,
+    force,
+    archives_check_id=None,
+    datetime_now=datetime.datetime.now,
+):
+    '''
+    Given a configuration dict with a "checks" sequence of dicts, a Borg repository ID, a sequence
+    of checks, whether to force checks to run, and an ID for the archives check potentially being
+    run (if any), 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:
+
+    config = {
+        'checks': [
+            {
+                'name': 'archives',
+                'frequency': '2 weeks',
+            },
+        ]
+    }
+
+    When this function is called with that 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.
+    '''
+    if not checks:
+        return checks
+
+    filtered_checks = list(checks)
+
+    if force:
+        return tuple(filtered_checks)
+
+    for check_config in config.get('checks', DEFAULT_CHECKS):
+        check = check_config['name']
+        if checks and check not in checks:
+            continue
+
+        only_run_on = check_config.get('only_run_on')
+        if only_run_on:
+            # Use a dict instead of a set to preserve ordering.
+            days = dict.fromkeys(only_run_on)
+
+            if 'weekday' in days:
+                days = {
+                    **dict.fromkeys(day for day in days if day != 'weekday'),
+                    **dict.fromkeys(WEEKDAY_DAYS),
+                }
+            if 'weekend' in days:
+                days = {
+                    **dict.fromkeys(day for day in days if day != 'weekend'),
+                    **dict.fromkeys(WEEKEND_DAYS),
+                }
+
+            if calendar.day_name[datetime_now().weekday()] not in days:
+                logger.info(
+                    f"Skipping {check} check due to day of the week; check only runs on {'/'.join(days)} (use --force to check anyway)"
+                )
+                filtered_checks.remove(check)
+                continue
+
+        frequency_delta = parse_frequency(check_config.get('frequency'))
+        if not frequency_delta:
+            continue
+
+        check_time = probe_for_check_time(config, borg_repository_id, check, archives_check_id)
+        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_now() < check_time + frequency_delta:
+            remaining = check_time + frequency_delta - datetime_now()
+            logger.info(
+                f'Skipping {check} check due to configured frequency; {remaining} until next check (use --force to check anyway)'
+            )
+            filtered_checks.remove(check)
+
+    return tuple(filtered_checks)
+
+
+def make_archives_check_id(archive_filter_flags):
+    '''
+    Given a sequence of flags to filter archives, return a unique hash corresponding to those
+    particular flags. If there are no flags, return None.
+    '''
+    if not archive_filter_flags:
+        return None
+
+    return hashlib.sha256(' '.join(archive_filter_flags).encode()).hexdigest()
+
+
+def make_check_time_path(config, borg_repository_id, check_type, archives_check_id=None):
+    '''
+    Given a configuration dict, a Borg repository ID, the name of a check type ("repository",
+    "archives", etc.), and a unique hash of the archives filter flags, return a path for recording
+    that check's time (the time of that check last occurring).
+    '''
+    borgmatic_source_directory = os.path.expanduser(
+        config.get(
+            'borgmatic_source_directory', borgmatic.borg.state.DEFAULT_BORGMATIC_SOURCE_DIRECTORY
+        )
+    )
+
+    if check_type in ('archives', 'data'):
+        return os.path.join(
+            borgmatic_source_directory,
+            'checks',
+            borg_repository_id,
+            check_type,
+            archives_check_id if archives_check_id else 'all',
+        )
+
+    return os.path.join(
+        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 probe_for_check_time(config, borg_repository_id, check, archives_check_id):
+    '''
+    Given a configuration dict, a Borg repository ID, the name of a check type ("repository",
+    "archives", etc.), and a unique hash of the archives filter flags, return a the corresponding
+    check time or None if such a check time does not exist.
+
+    When the check type is "archives" or "data", this function probes two different paths to find
+    the check time, e.g.:
+
+      ~/.borgmatic/checks/1234567890/archives/9876543210
+      ~/.borgmatic/checks/1234567890/archives/all
+
+    ... and returns the maximum modification time of the files found (if any). The first path
+    represents a more specific archives check time (a check on a subset of archives), and the second
+    is a fallback to the last "all" archives check.
+
+    For other check types, this function reads from a single check time path, e.g.:
+
+      ~/.borgmatic/checks/1234567890/repository
+    '''
+    check_times = (
+        read_check_time(group[0])
+        for group in itertools.groupby(
+            (
+                make_check_time_path(config, borg_repository_id, check, archives_check_id),
+                make_check_time_path(config, borg_repository_id, check),
+            )
+        )
+    )
+
+    try:
+        return max(check_time for check_time in check_times if check_time)
+    except ValueError:
+        return None
+
+
+def upgrade_check_times(config, borg_repository_id):
+    '''
+    Given a configuration dict and a Borg repository ID, upgrade any corresponding check times on
+    disk from old-style paths to new-style paths.
+
+    Currently, the only upgrade performed is renaming an archive or data check path that looks like:
+
+      ~/.borgmatic/checks/1234567890/archives
+
+    to:
+
+      ~/.borgmatic/checks/1234567890/archives/all
+    '''
+    for check_type in ('archives', 'data'):
+        new_path = make_check_time_path(config, borg_repository_id, check_type, 'all')
+        old_path = os.path.dirname(new_path)
+        temporary_path = f'{old_path}.temp'
+
+        if not os.path.isfile(old_path) and not os.path.isfile(temporary_path):
+            continue
+
+        logger.debug(f'Upgrading archives check time from {old_path} to {new_path}')
+
+        try:
+            os.rename(old_path, temporary_path)
+        except FileNotFoundError:
+            pass
+
+        os.mkdir(old_path)
+        os.rename(temporary_path, new_path)
+
+
+def collect_spot_check_source_paths(
+    repository, config, local_borg_version, global_arguments, local_path, remote_path
+):
+    '''
+    Given a repository configuration dict, a configuration dict, the local Borg version, global
+    arguments as an argparse.Namespace instance, the local Borg path, and the remote Borg path,
+    collect the source paths that Borg would use in an actual create (but only include files).
+    '''
+    stream_processes = any(
+        borgmatic.hooks.dispatch.call_hooks(
+            'use_streaming',
+            config,
+            repository['path'],
+            borgmatic.hooks.dump.DATA_SOURCE_HOOK_NAMES,
+        ).values()
+    )
+
+    (create_flags, create_positional_arguments, pattern_file, exclude_file) = (
+        borgmatic.borg.create.make_base_create_command(
+            dry_run=True,
+            repository_path=repository['path'],
+            config=config,
+            config_paths=(),
+            local_borg_version=local_borg_version,
+            global_arguments=global_arguments,
+            borgmatic_source_directories=(),
+            local_path=local_path,
+            remote_path=remote_path,
+            list_files=True,
+            stream_processes=stream_processes,
+        )
+    )
+    borg_environment = borgmatic.borg.environment.make_environment(config)
+
+    try:
+        working_directory = os.path.expanduser(config.get('working_directory'))
+    except TypeError:
+        working_directory = None
+
+    paths_output = borgmatic.execute.execute_command_and_capture_output(
+        create_flags + create_positional_arguments,
+        capture_stderr=True,
+        working_directory=working_directory,
+        extra_environment=borg_environment,
+        borg_local_path=local_path,
+        borg_exit_codes=config.get('borg_exit_codes'),
+    )
+
+    paths = tuple(
+        path_line.split(' ', 1)[1]
+        for path_line in paths_output.split('\n')
+        if path_line and path_line.startswith('- ') or path_line.startswith('+ ')
+    )
+
+    return tuple(path for path in paths if os.path.isfile(path))
+
+
+BORG_DIRECTORY_FILE_TYPE = 'd'
+
+
+def collect_spot_check_archive_paths(
+    repository, archive, config, local_borg_version, global_arguments, local_path, remote_path
+):
+    '''
+    Given a repository configuration dict, the name of the latest archive, a configuration dict, the
+    local Borg version, global arguments as an argparse.Namespace instance, the local Borg path, and
+    the remote Borg path, collect the paths from the given archive (but only include files and
+    symlinks).
+    '''
+    borgmatic_source_directory = os.path.expanduser(
+        config.get(
+            'borgmatic_source_directory', borgmatic.borg.state.DEFAULT_BORGMATIC_SOURCE_DIRECTORY
+        )
+    )
+
+    return tuple(
+        path
+        for line in borgmatic.borg.list.capture_archive_listing(
+            repository['path'],
+            archive,
+            config,
+            local_borg_version,
+            global_arguments,
+            path_format='{type} /{path}{NL}',  # noqa: FS003
+            local_path=local_path,
+            remote_path=remote_path,
+        )
+        for (file_type, path) in (line.split(' ', 1),)
+        if file_type != BORG_DIRECTORY_FILE_TYPE
+        if pathlib.Path(borgmatic_source_directory) not in pathlib.Path(path).parents
+    )
+
+
+SAMPLE_PATHS_SUBSET_COUNT = 10000
+
+
+def compare_spot_check_hashes(
+    repository,
+    archive,
+    config,
+    local_borg_version,
+    global_arguments,
+    local_path,
+    remote_path,
+    log_label,
+    source_paths,
+):
+    '''
+    Given a repository configuration dict, the name of the latest archive, a configuration dict, the
+    local Borg version, global arguments as an argparse.Namespace instance, the local Borg path, the
+    remote Borg path, a log label, and spot check source paths, compare the hashes for a sampling of
+    the source paths with hashes from corresponding paths in the given archive. Return a sequence of
+    the paths that fail that hash comparison.
+    '''
+    # Based on the configured sample percentage, come up with a list of random sample files from the
+    # source directories.
+    spot_check_config = next(check for check in config['checks'] if check['name'] == 'spot')
+    sample_count = max(
+        int(len(source_paths) * (min(spot_check_config['data_sample_percentage'], 100) / 100)), 1
+    )
+    source_sample_paths = tuple(random.sample(source_paths, sample_count))
+    existing_source_sample_paths = {
+        source_path for source_path in source_sample_paths if os.path.exists(source_path)
+    }
+    logger.debug(
+        f'{log_label}: Sampling {sample_count} source paths (~{spot_check_config["data_sample_percentage"]}%) for spot check'
+    )
+
+    source_sample_paths_iterator = iter(source_sample_paths)
+    source_hashes = {}
+    archive_hashes = {}
+
+    # Only hash a few thousand files at a time (a subset of the total paths) to avoid an "Argument
+    # list too long" shell error.
+    while True:
+        # Hash each file in the sample paths (if it exists).
+        source_sample_paths_subset = tuple(
+            itertools.islice(source_sample_paths_iterator, SAMPLE_PATHS_SUBSET_COUNT)
+        )
+        if not source_sample_paths_subset:
+            break
+
+        hash_output = borgmatic.execute.execute_command_and_capture_output(
+            (spot_check_config.get('xxh64sum_command', 'xxh64sum'),)
+            + tuple(
+                path for path in source_sample_paths_subset if path in existing_source_sample_paths
+            )
+        )
+
+        source_hashes.update(
+            **dict(
+                (reversed(line.split('  ', 1)) for line in hash_output.splitlines()),
+                # Represent non-existent files as having empty hashes so the comparison below still works.
+                **{
+                    path: ''
+                    for path in source_sample_paths_subset
+                    if path not in existing_source_sample_paths
+                },
+            )
+        )
+
+        # Get the hash for each file in the archive.
+        archive_hashes.update(
+            **dict(
+                reversed(line.split(' ', 1))
+                for line in borgmatic.borg.list.capture_archive_listing(
+                    repository['path'],
+                    archive,
+                    config,
+                    local_borg_version,
+                    global_arguments,
+                    list_paths=source_sample_paths_subset,
+                    path_format='{xxh64} /{path}{NL}',  # noqa: FS003
+                    local_path=local_path,
+                    remote_path=remote_path,
+                )
+                if line
+            )
+        )
+
+    # Compare the source hashes with the archive hashes to see how many match.
+    failing_paths = []
+
+    for path, source_hash in source_hashes.items():
+        archive_hash = archive_hashes.get(path)
+
+        if archive_hash is not None and archive_hash == source_hash:
+            continue
+
+        failing_paths.append(path)
+
+    return tuple(failing_paths)
+
+
+def spot_check(
+    repository,
+    config,
+    local_borg_version,
+    global_arguments,
+    local_path,
+    remote_path,
+):
+    '''
+    Given a repository dict, a loaded configuration dict, the local Borg version, global arguments
+    as an argparse.Namespace instance, the local Borg path, and the remote Borg path, perform a spot
+    check for the latest archive in the given repository.
+
+    A spot check compares file counts and also the hashes for a random sampling of source files on
+    disk to those stored in the latest archive. If any differences are beyond configured tolerances,
+    then the check fails.
+    '''
+    log_label = f'{repository.get("label", repository["path"])}'
+    logger.debug(f'{log_label}: Running spot check')
+
+    try:
+        spot_check_config = next(
+            check for check in config.get('checks', ()) if check.get('name') == 'spot'
+        )
+    except StopIteration:
+        raise ValueError('Cannot run spot check because it is unconfigured')
+
+    if spot_check_config['data_tolerance_percentage'] > spot_check_config['data_sample_percentage']:
+        raise ValueError(
+            'The data_tolerance_percentage must be less than or equal to the data_sample_percentage'
+        )
+
+    source_paths = collect_spot_check_source_paths(
+        repository,
+        config,
+        local_borg_version,
+        global_arguments,
+        local_path,
+        remote_path,
+    )
+    logger.debug(f'{log_label}: {len(source_paths)} total source paths for spot check')
+
+    archive = borgmatic.borg.rlist.resolve_archive_name(
+        repository['path'],
+        'latest',
+        config,
+        local_borg_version,
+        global_arguments,
+        local_path,
+        remote_path,
+    )
+    logger.debug(f'{log_label}: Using archive {archive} for spot check')
+
+    archive_paths = collect_spot_check_archive_paths(
+        repository,
+        archive,
+        config,
+        local_borg_version,
+        global_arguments,
+        local_path,
+        remote_path,
+    )
+    logger.debug(f'{log_label}: {len(archive_paths)} total archive paths for spot check')
+
+    # Calculate the percentage delta between the source paths count and the archive paths count, and
+    # compare that delta to the configured count tolerance percentage.
+    count_delta_percentage = abs(len(source_paths) - len(archive_paths)) / len(source_paths) * 100
+
+    if count_delta_percentage > spot_check_config['count_tolerance_percentage']:
+        logger.debug(
+            f'{log_label}: Paths in source paths but not latest archive: {", ".join(set(source_paths) - set(archive_paths)) or "none"}'
+        )
+        logger.debug(
+            f'{log_label}: Paths in latest archive but not source paths: {", ".join(set(archive_paths) - set(source_paths)) or "none"}'
+        )
+        raise ValueError(
+            f'Spot check failed: {count_delta_percentage:.2f}% file count delta between source paths and latest archive (tolerance is {spot_check_config["count_tolerance_percentage"]}%)'
+        )
+
+    failing_paths = compare_spot_check_hashes(
+        repository,
+        archive,
+        config,
+        local_borg_version,
+        global_arguments,
+        local_path,
+        remote_path,
+        log_label,
+        source_paths,
+    )
+
+    # Error if the percentage of failing hashes exceeds the configured tolerance percentage.
+    logger.debug(f'{log_label}: {len(failing_paths)} non-matching spot check hashes')
+    data_tolerance_percentage = spot_check_config['data_tolerance_percentage']
+    failing_percentage = (len(failing_paths) / len(source_paths)) * 100
+
+    if failing_percentage > data_tolerance_percentage:
+        logger.debug(
+            f'{log_label}: Source paths with data not matching the latest archive: {", ".join(failing_paths)}'
+        )
+        raise ValueError(
+            f'Spot check failed: {failing_percentage:.2f}% of source paths with data not matching the latest archive (tolerance is {data_tolerance_percentage}%)'
+        )
+
+    logger.info(
+        f'{log_label}: Spot check passed with a {count_delta_percentage:.2f}% file count delta and a {failing_percentage:.2f}% file data delta'
+    )
+
+
 def run_check(
     config_filename,
     repository,
@@ -20,6 +639,8 @@ def run_check(
 ):
     '''
     Run the "check" action for the given repository.
+
+    Raise ValueError if the Borg repository ID cannot be determined.
     '''
     if check_arguments.repository and not borgmatic.config.validate.repositories_match(
         repository, check_arguments.repository
@@ -34,16 +655,69 @@ def run_check(
         global_arguments.dry_run,
         **hook_context,
     )
+
     logger.info(f'{repository.get("label", repository["path"])}: Running consistency checks')
-    borgmatic.borg.check.check_archives(
+    repository_id = borgmatic.borg.check.get_repository_id(
         repository['path'],
         config,
         local_borg_version,
-        check_arguments,
         global_arguments,
         local_path=local_path,
         remote_path=remote_path,
     )
+    upgrade_check_times(config, repository_id)
+    configured_checks = parse_checks(config, check_arguments.only_checks)
+    archive_filter_flags = borgmatic.borg.check.make_archive_filter_flags(
+        local_borg_version, config, configured_checks, check_arguments
+    )
+    archives_check_id = make_archives_check_id(archive_filter_flags)
+    checks = filter_checks_on_frequency(
+        config,
+        repository_id,
+        configured_checks,
+        check_arguments.force,
+        archives_check_id,
+    )
+    borg_specific_checks = set(checks).intersection({'repository', 'archives', 'data'})
+
+    if borg_specific_checks:
+        borgmatic.borg.check.check_archives(
+            repository['path'],
+            config,
+            local_borg_version,
+            check_arguments,
+            global_arguments,
+            borg_specific_checks,
+            archive_filter_flags,
+            local_path=local_path,
+            remote_path=remote_path,
+        )
+        for check in borg_specific_checks:
+            write_check_time(make_check_time_path(config, repository_id, check, archives_check_id))
+
+    if 'extract' in checks:
+        borgmatic.borg.extract.extract_last_archive_dry_run(
+            config,
+            local_borg_version,
+            global_arguments,
+            repository['path'],
+            config.get('lock_wait'),
+            local_path,
+            remote_path,
+        )
+        write_check_time(make_check_time_path(config, repository_id, 'extract'))
+
+    if 'spot' in checks:
+        spot_check(
+            repository,
+            config,
+            local_borg_version,
+            global_arguments,
+            local_path,
+            remote_path,
+        )
+        write_check_time(make_check_time_path(config, repository_id, 'spot'))
+
     borgmatic.hooks.command.execute_hook(
         config.get('after_check'),
         config.get('umask'),

borgmatic/actions/delete.py

@@ -0,0 +1,50 @@
+import logging
+
+import borgmatic.actions.arguments
+import borgmatic.borg.delete
+import borgmatic.borg.rdelete
+import borgmatic.borg.rlist
+
+logger = logging.getLogger(__name__)
+
+
+def run_delete(
+    repository,
+    config,
+    local_borg_version,
+    delete_arguments,
+    global_arguments,
+    local_path,
+    remote_path,
+):
+    '''
+    Run the "delete" action for the given repository and archive(s).
+    '''
+    if delete_arguments.repository is None or borgmatic.config.validate.repositories_match(
+        repository, delete_arguments.repository
+    ):
+        logger.answer(f'{repository.get("label", repository["path"])}: Deleting archives')
+
+        archive_name = (
+            borgmatic.borg.rlist.resolve_archive_name(
+                repository['path'],
+                delete_arguments.archive,
+                config,
+                local_borg_version,
+                global_arguments,
+                local_path,
+                remote_path,
+            )
+            if delete_arguments.archive
+            else None
+        )
+
+        borgmatic.borg.delete.delete_archives(
+            repository,
+            config,
+            local_borg_version,
+            borgmatic.actions.arguments.update_arguments(delete_arguments, archive=archive_name),
+            global_arguments,
+            local_path,
+            remote_path,
+        )

borgmatic/actions/json.py

@@ -1,12 +1,26 @@
 import json
+import logging
+
+logger = logging.getLogger(__name__)
 
 
 def parse_json(borg_json_output, label):
     '''
     Given a Borg JSON output string, parse it as JSON into a dict. Inject the given borgmatic
     repository label into it and return the dict.
+
+    Raise JSONDecodeError if the JSON output cannot be parsed.
     '''
-    json_data = json.loads(borg_json_output)
+    lines = borg_json_output.splitlines()
+    start_line_index = 0
+
+    # Scan forward to find the first line starting with "{" and assume that's where the JSON starts.
+    for line_index, line in enumerate(lines):
+        if line.startswith('{'):
+            start_line_index = line_index
+            break
+
+    json_data = json.loads('\n'.join(lines[start_line_index:]))
 
     if 'repository' not in json_data:
         return json_data

borgmatic/actions/rdelete.py

@@ -0,0 +1,36 @@
+import logging
+
+import borgmatic.borg.rdelete
+
+logger = logging.getLogger(__name__)
+
+
+def run_rdelete(
+    repository,
+    config,
+    local_borg_version,
+    rdelete_arguments,
+    global_arguments,
+    local_path,
+    remote_path,
+):
+    '''
+    Run the "rdelete" action for the given repository.
+    '''
+    if rdelete_arguments.repository is None or borgmatic.config.validate.repositories_match(
+        repository, rdelete_arguments.repository
+    ):
+        logger.answer(
+            f'{repository.get("label", repository["path"])}: Deleting repository'
+            + (' cache' if rdelete_arguments.cache_only else '')
+        )
+
+        borgmatic.borg.rdelete.delete_repository(
+            repository,
+            config,
+            local_borg_version,
+            rdelete_arguments,
+            global_arguments,
+            local_path,
+            remote_path,
+        )

borgmatic/borg/check.py

@@ -1,172 +1,26 @@
 import argparse
-import datetime
-import hashlib
-import itertools
 import json
 import logging
-import os
-import pathlib
 
-from borgmatic.borg import environment, extract, feature, flags, rinfo, state
+from borgmatic.borg import environment, feature, flags, rinfo
 from borgmatic.execute import DO_NOT_CAPTURE, execute_command
 
-DEFAULT_CHECKS = (
-    {'name': 'repository', 'frequency': '1 month'},
-    {'name': 'archives', 'frequency': '1 month'},
-)
-
-
 logger = logging.getLogger(__name__)
 
 
-def parse_checks(config, only_checks=None):
+def make_archive_filter_flags(local_borg_version, config, checks, check_arguments):
     '''
-    Given a configuration dict with a "checks" sequence of dicts and an optional list of override
-    checks, return a tuple of named checks to run.
+    Given the local Borg version, a configuration dict, a parsed sequence of checks, and check
+    arguments as an argparse.Namespace instance, transform the checks into tuple of command-line
+    flags for filtering archives in a check command.
 
-    For example, given a config of:
-
-        {'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 a checks value
-    has a name of "disabled", return an empty tuple, meaning that no checks should be run.
+    If "check_last" is set in the configuration and "archives" is in checks, then include a "--last"
+    flag. And if "prefix" is set in configuration and "archives" is in checks, then include a
+    "--match-archives" flag.
     '''
-    checks = only_checks or tuple(
-        check_config['name'] for check_config in (config.get('checks', None) or DEFAULT_CHECKS)
-    )
-    checks = tuple(check.lower() for check in checks)
+    check_last = config.get('check_last', None)
+    prefix = config.get('prefix')
 
-    if 'disabled' in checks:
-        logger.warning(
-            'The "disabled" value for the "checks" option is deprecated and will be removed from a future release; use "skip_actions" instead'
-        )
-        if len(checks) > 1:
-            logger.warning(
-                'Multiple checks are configured, but one of them is "disabled"; not running any checks'
-            )
-        return ()
-
-    return checks
-
-
-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(
-    config,
-    borg_repository_id,
-    checks,
-    force,
-    archives_check_id=None,
-):
-    '''
-    Given a configuration dict with a "checks" sequence of dicts, a Borg repository ID, a sequence
-    of checks, whether to force checks to run, and an ID for the archives check potentially being
-    run (if any), 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:
-
-    config = {
-        'checks': [
-            {
-                'name': 'archives',
-                'frequency': '2 weeks',
-            },
-        ]
-    }
-
-    When this function is called with that 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.
-    '''
-    if not checks:
-        return checks
-
-    filtered_checks = list(checks)
-
-    if force:
-        return tuple(filtered_checks)
-
-    for check_config in 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 = probe_for_check_time(config, borg_repository_id, check, archives_check_id)
-        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 (use --force to check anyway)'
-            )
-            filtered_checks.remove(check)
-
-    return tuple(filtered_checks)
-
-
-def make_archive_filter_flags(
-    local_borg_version, config, checks, check_arguments, check_last=None, prefix=None
-):
-    '''
-    Given the local Borg version, a configuration dict, a parsed sequence of checks, check arguments
-    as an argparse.Namespace instance, the check last value, and a consistency check prefix,
-    transform the checks into tuple of command-line flags for filtering archives in a check command.
-
-    If a check_last value is given and "archives" is in checks, then include a "--last" flag. And if
-    a prefix value is given and "archives" is in checks, then include a "--match-archives" flag.
-    '''
     if 'archives' in checks or 'data' in checks:
         return (('--last', str(check_last)) if check_last else ()) + (
             (
@@ -196,21 +50,10 @@ def make_archive_filter_flags(
     return ()
 
 
-def make_archives_check_id(archive_filter_flags):
+def make_check_name_flags(checks, archive_filter_flags):
     '''
-    Given a sequence of flags to filter archives, return a unique hash corresponding to those
-    particular flags. If there are no flags, return None.
-    '''
-    if not archive_filter_flags:
-        return None
-
-    return hashlib.sha256(' '.join(archive_filter_flags).encode()).hexdigest()
-
-
-def make_check_flags(checks, archive_filter_flags):
-    '''
-    Given a parsed sequence of checks and a sequence of flags to filter archives, transform the
-    checks into tuple of command-line check flags.
+    Given parsed checks set and a sequence of flags to filter archives, transform the checks into
+    tuple of command-line check flags.
 
     For example, given parsed checks of:
 
@@ -225,13 +68,13 @@ def make_check_flags(checks, archive_filter_flags):
     '''
     if 'data' in checks:
         data_flags = ('--verify-data',)
-        checks += ('archives',)
+        checks.update({'archives'})
     else:
         data_flags = ()
 
     common_flags = (archive_filter_flags if 'archives' in checks else ()) + data_flags
 
-    if {'repository', 'archives'}.issubset(set(checks)):
+    if {'repository', 'archives'}.issubset(checks):
         return common_flags
 
     return (
@@ -240,144 +83,17 @@ def make_check_flags(checks, archive_filter_flags):
     )
 
 
-def make_check_time_path(config, borg_repository_id, check_type, archives_check_id=None):
-    '''
-    Given a configuration dict, a Borg repository ID, the name of a check type ("repository",
-    "archives", etc.), and a unique hash of the archives filter flags, return a path for recording
-    that check's time (the time of that check last occurring).
-    '''
-    borgmatic_source_directory = os.path.expanduser(
-        config.get('borgmatic_source_directory', state.DEFAULT_BORGMATIC_SOURCE_DIRECTORY)
-    )
-
-    if check_type in ('archives', 'data'):
-        return os.path.join(
-            borgmatic_source_directory,
-            'checks',
-            borg_repository_id,
-            check_type,
-            archives_check_id if archives_check_id else 'all',
-        )
-
-    return os.path.join(
-        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 probe_for_check_time(config, borg_repository_id, check, archives_check_id):
-    '''
-    Given a configuration dict, a Borg repository ID, the name of a check type ("repository",
-    "archives", etc.), and a unique hash of the archives filter flags, return a the corresponding
-    check time or None if such a check time does not exist.
-
-    When the check type is "archives" or "data", this function probes two different paths to find
-    the check time, e.g.:
-
-      ~/.borgmatic/checks/1234567890/archives/9876543210
-      ~/.borgmatic/checks/1234567890/archives/all
-
-    ... and returns the maximum modification time of the files found (if any). The first path
-    represents a more specific archives check time (a check on a subset of archives), and the second
-    is a fallback to the last "all" archives check.
-
-    For other check types, this function reads from a single check time path, e.g.:
-
-      ~/.borgmatic/checks/1234567890/repository
-    '''
-    check_times = (
-        read_check_time(group[0])
-        for group in itertools.groupby(
-            (
-                make_check_time_path(config, borg_repository_id, check, archives_check_id),
-                make_check_time_path(config, borg_repository_id, check),
-            )
-        )
-    )
-
-    try:
-        return max(check_time for check_time in check_times if check_time)
-    except ValueError:
-        return None
-
-
-def upgrade_check_times(config, borg_repository_id):
-    '''
-    Given a configuration dict and a Borg repository ID, upgrade any corresponding check times on
-    disk from old-style paths to new-style paths.
-
-    Currently, the only upgrade performed is renaming an archive or data check path that looks like:
-
-      ~/.borgmatic/checks/1234567890/archives
-
-    to:
-
-      ~/.borgmatic/checks/1234567890/archives/all
-    '''
-    for check_type in ('archives', 'data'):
-        new_path = make_check_time_path(config, borg_repository_id, check_type, 'all')
-        old_path = os.path.dirname(new_path)
-        temporary_path = f'{old_path}.temp'
-
-        if not os.path.isfile(old_path) and not os.path.isfile(temporary_path):
-            continue
-
-        logger.debug(f'Upgrading archives check time from {old_path} to {new_path}')
-
-        try:
-            os.rename(old_path, temporary_path)
-        except FileNotFoundError:
-            pass
-
-        os.mkdir(old_path)
-        os.rename(temporary_path, new_path)
-
-
-def check_archives(
-    repository_path,
-    config,
-    local_borg_version,
-    check_arguments,
-    global_arguments,
-    local_path='borg',
-    remote_path=None,
+def get_repository_id(
+    repository_path, config, local_borg_version, global_arguments, local_path, remote_path
 ):
     '''
-    Given a local or remote repository path, a configuration dict, the local Borg version, check
-    arguments as an argparse.Namespace instance, global arguments, and local/remote commands to run,
-    check the contained Borg archives for consistency.
+    Given a local or remote repository path, a configuration dict, the local Borg version, global
+    arguments, and local/remote commands to run, return the corresponding Borg repository ID.
 
-    If there are no consistency checks to run, skip running them.
-
-    Raises ValueError if the Borg repository ID cannot be determined.
+    Raise ValueError if the Borg repository ID cannot be determined.
     '''
     try:
-        borg_repository_id = json.loads(
+        return json.loads(
             rinfo.display_repository_info(
                 repository_path,
                 config,
@@ -391,82 +107,80 @@ def check_archives(
     except (json.JSONDecodeError, KeyError):
         raise ValueError(f'Cannot determine Borg repository ID for {repository_path}')
 
-    upgrade_check_times(config, borg_repository_id)
 
-    check_last = config.get('check_last', None)
-    prefix = config.get('prefix')
-    configured_checks = parse_checks(config, check_arguments.only_checks)
-    lock_wait = None
+def check_archives(
+    repository_path,
+    config,
+    local_borg_version,
+    check_arguments,
+    global_arguments,
+    checks,
+    archive_filter_flags,
+    local_path='borg',
+    remote_path=None,
+):
+    '''
+    Given a local or remote repository path, a configuration dict, the local Borg version, check
+    arguments as an argparse.Namespace instance, global arguments, a set of named Borg checks to run
+    (some combination "repository", "archives", and/or "data"), archive filter flags, and
+    local/remote commands to run, check the contained Borg archives for consistency.
+    '''
+    lock_wait = config.get('lock_wait')
     extra_borg_options = config.get('extra_borg_options', {}).get('check', '')
-    archive_filter_flags = make_archive_filter_flags(
-        local_borg_version, config, configured_checks, check_arguments, check_last, prefix
-    )
-    archives_check_id = make_archives_check_id(archive_filter_flags)
 
-    checks = filter_checks_on_frequency(
-        config,
-        borg_repository_id,
-        configured_checks,
-        check_arguments.force,
-        archives_check_id,
-    )
+    verbosity_flags = ()
+    if logger.isEnabledFor(logging.INFO):
+        verbosity_flags = ('--info',)
+    if logger.isEnabledFor(logging.DEBUG):
+        verbosity_flags = ('--debug', '--show-rc')
 
-    if set(checks).intersection({'repository', 'archives', 'data'}):
-        lock_wait = config.get('lock_wait')
+    try:
+        repository_check_config = next(
+            check for check in config.get('checks', ()) if check.get('name') == 'repository'
+        )
+    except StopIteration:
+        repository_check_config = {}
 
-        verbosity_flags = ()
-        if logger.isEnabledFor(logging.INFO):
-            verbosity_flags = ('--info',)
-        if logger.isEnabledFor(logging.DEBUG):
-            verbosity_flags = ('--debug', '--show-rc')
-
-        full_command = (
-            (local_path, 'check')
-            + (('--repair',) if check_arguments.repair else ())
-            + make_check_flags(checks, archive_filter_flags)
-            + (('--remote-path', remote_path) if remote_path else ())
-            + (('--log-json',) if global_arguments.log_json else ())
-            + (('--lock-wait', str(lock_wait)) if lock_wait else ())
-            + verbosity_flags
-            + (('--progress',) if check_arguments.progress else ())
-            + (tuple(extra_borg_options.split(' ')) if extra_borg_options else ())
-            + flags.make_repository_flags(repository_path, local_borg_version)
+    if check_arguments.max_duration and 'archives' in checks:
+        raise ValueError('The archives check cannot run when the --max-duration flag is used')
+    if repository_check_config.get('max_duration') and 'archives' in checks:
+        raise ValueError(
+            'The archives check cannot run when the repository check has the max_duration option set'
         )
 
-        borg_environment = environment.make_environment(config)
-        borg_exit_codes = config.get('borg_exit_codes')
+    max_duration = check_arguments.max_duration or repository_check_config.get('max_duration')
 
-        # The Borg repair option triggers an interactive prompt, which won't work when output is
-        # captured. And progress messes with the terminal directly.
-        if check_arguments.repair or check_arguments.progress:
-            execute_command(
-                full_command,
-                output_file=DO_NOT_CAPTURE,
-                extra_environment=borg_environment,
-                borg_local_path=local_path,
-                borg_exit_codes=borg_exit_codes,
-            )
-        else:
-            execute_command(
-                full_command,
-                extra_environment=borg_environment,
-                borg_local_path=local_path,
-                borg_exit_codes=borg_exit_codes,
-            )
+    borg_environment = environment.make_environment(config)
+    borg_exit_codes = config.get('borg_exit_codes')
 
-        for check in checks:
-            write_check_time(
-                make_check_time_path(config, borg_repository_id, check, archives_check_id)
-            )
+    full_command = (
+        (local_path, 'check')
+        + (('--repair',) if check_arguments.repair else ())
+        + (('--max-duration', str(max_duration)) if max_duration else ())
+        + make_check_name_flags(checks, archive_filter_flags)
+        + (('--remote-path', remote_path) if remote_path else ())
+        + (('--log-json',) if global_arguments.log_json else ())
+        + (('--lock-wait', str(lock_wait)) if lock_wait else ())
+        + verbosity_flags
+        + (('--progress',) if check_arguments.progress else ())
+        + (tuple(extra_borg_options.split(' ')) if extra_borg_options else ())
+        + flags.make_repository_flags(repository_path, local_borg_version)
+    )
 
-    if 'extract' in checks:
-        extract.extract_last_archive_dry_run(
-            config,
-            local_borg_version,
-            global_arguments,
-            repository_path,
-            lock_wait,
-            local_path,
-            remote_path,
+    # The Borg repair option triggers an interactive prompt, which won't work when output is
+    # captured. And progress messes with the terminal directly.
+    if check_arguments.repair or check_arguments.progress:
+        execute_command(
+            full_command,
+            output_file=DO_NOT_CAPTURE,
+            extra_environment=borg_environment,
+            borg_local_path=local_path,
+            borg_exit_codes=borg_exit_codes,
+        )
+    else:
+        execute_command(
+            full_command,
+            extra_environment=borg_environment,
+            borg_local_path=local_path,
+            borg_exit_codes=borg_exit_codes,
         )
-        write_check_time(make_check_time_path(config, borg_repository_id, 'extract'))

borgmatic/borg/create.py

@@ -275,11 +275,11 @@ def collect_special_file_paths(
     create_command, config, local_path, working_directory, borg_environment, skip_directories
 ):
     '''
-    Given a Borg create command as a tuple, a local Borg path, a working directory, a dict of
-    environment variables to pass to Borg, and a sequence of parent directories to skip, collect the
-    paths for any special files (character devices, block devices, and named pipes / FIFOs) that
-    Borg would encounter during a create. These are all paths that could cause Borg to hang if its
-    --read-special flag is used.
+    Given a Borg create command as a tuple, a configuration dict, a local Borg path, a working
+    directory, a dict of environment variables to pass to Borg, and a sequence of parent directories
+    to skip, collect the paths for any special files (character devices, block devices, and named
+    pipes / FIFOs) that Borg would encounter during a create. These are all paths that could cause
+    Borg to hang if its --read-special flag is used.
     '''
     # Omit "--exclude-nodump" from the Borg dry run command, because that flag causes Borg to open
     # files including any named pipe we've created.
@@ -320,35 +320,31 @@ def check_all_source_directories_exist(source_directories):
         raise ValueError(f"Source directories do not exist: {', '.join(missing_directories)}")
 
 
-def create_archive(
+def make_base_create_command(
     dry_run,
     repository_path,
     config,
     config_paths,
     local_borg_version,
     global_arguments,
+    borgmatic_source_directories,
     local_path='borg',
     remote_path=None,
     progress=False,
-    stats=False,
     json=False,
     list_files=False,
     stream_processes=None,
 ):
     '''
     Given vebosity/dry-run flags, a local or remote repository path, a configuration dict, a
-    sequence of loaded configuration paths, the local Borg version, and global arguments as an
-    argparse.Namespace instance, create a Borg archive and return Borg's JSON output (if any).
-
-    If a sequence of stream processes is given (instances of subprocess.Popen), then execute the
-    create command while also triggering the given processes to produce output.
+    sequence of loaded configuration paths, the local Borg version, global arguments as an
+    argparse.Namespace instance, and a sequence of borgmatic source directories, return a tuple of
+    (base Borg create command flags, Borg create command positional arguments, open pattern file
+    handle, open exclude file handle).
     '''
-    borgmatic.logger.add_custom_log_levels()
-    borgmatic_source_directories = expand_directories(
-        collect_borgmatic_source_directories(config.get('borgmatic_source_directory'))
-    )
     if config.get('source_directories_must_exist', False):
         check_all_source_directories_exist(config.get('source_directories'))
+
     sources = deduplicate_directories(
         map_directories_to_devices(
             expand_directories(
@@ -364,11 +360,6 @@ def create_archive(
 
     ensure_files_readable(config.get('patterns_from'), config.get('exclude_from'))
 
-    try:
-        working_directory = os.path.expanduser(config.get('working_directory'))
-    except TypeError:
-        working_directory = None
-
     pattern_file = (
         write_pattern_file(config.get('patterns'), sources)
         if config.get('patterns') or config.get('patterns_from')
@@ -380,6 +371,7 @@ def create_archive(
     chunker_params = config.get('chunker_params', None)
     compression = config.get('compression', None)
     upload_rate_limit = config.get('upload_rate_limit', None)
+    upload_buffer_size = config.get('upload_buffer_size', None)
     umask = config.get('umask', None)
     lock_wait = config.get('lock_wait', None)
     list_filter_flags = make_list_filter_flags(local_borg_version, dry_run)
@@ -411,11 +403,6 @@ def create_archive(
             ('--remote-ratelimit', str(upload_rate_limit)) if upload_rate_limit else ()
         )
 
-    if stream_processes and config.get('read_special') is False:
-        logger.warning(
-            f'{repository_path}: Ignoring configured "read_special" value of false, as true is needed for database hooks.'
-        )
-
     create_flags = (
         tuple(local_path.split(' '))
         + ('create',)
@@ -426,6 +413,7 @@ def create_archive(
         + (('--chunker-params', chunker_params) if chunker_params else ())
         + (('--compression', compression) if compression else ())
         + upload_ratelimit_flags
+        + (('--upload-buffer', str(upload_buffer_size)) if upload_buffer_size else ())
         + (('--one-file-system',) if config.get('one_file_system') or stream_processes else ())
         + numeric_ids_flags
         + atime_flags
@@ -451,22 +439,19 @@ def create_archive(
         repository_path, archive_name_format, local_borg_version
     ) + (sources if not pattern_file else ())
 
-    if json:
-        output_log_level = None
-    elif list_files or (stats and not dry_run):
-        output_log_level = logging.ANSWER
-    else:
-        output_log_level = logging.INFO
-
-    # The progress output isn't compatible with captured and logged output, as progress messes with
-    # the terminal directly.
-    output_file = DO_NOT_CAPTURE if progress else None
-
-    borg_environment = environment.make_environment(config)
-
     # If database hooks are enabled (as indicated by streaming processes), exclude files that might
     # cause Borg to hang. But skip this if the user has explicitly set the "read_special" to True.
     if stream_processes and not config.get('read_special'):
+        logger.warning(
+            f'{repository_path}: Ignoring configured "read_special" value of false, as true is needed for database hooks.'
+        )
+        try:
+            working_directory = os.path.expanduser(config.get('working_directory'))
+        except TypeError:
+            working_directory = None
+
+        borg_environment = environment.make_environment(config)
+
         logger.debug(f'{repository_path}: Collecting special file paths')
         special_file_paths = collect_special_file_paths(
             create_flags + create_positional_arguments,
@@ -489,6 +474,73 @@ def create_archive(
             )
             create_flags += make_exclude_flags(config, exclude_file.name)
 
+    return (create_flags, create_positional_arguments, pattern_file, exclude_file)
+
+
+def create_archive(
+    dry_run,
+    repository_path,
+    config,
+    config_paths,
+    local_borg_version,
+    global_arguments,
+    local_path='borg',
+    remote_path=None,
+    progress=False,
+    stats=False,
+    json=False,
+    list_files=False,
+    stream_processes=None,
+):
+    '''
+    Given vebosity/dry-run flags, a local or remote repository path, a configuration dict, a
+    sequence of loaded configuration paths, the local Borg version, and global arguments as an
+    argparse.Namespace instance, create a Borg archive and return Borg's JSON output (if any).
+
+    If a sequence of stream processes is given (instances of subprocess.Popen), then execute the
+    create command while also triggering the given processes to produce output.
+    '''
+    borgmatic.logger.add_custom_log_levels()
+    borgmatic_source_directories = expand_directories(
+        collect_borgmatic_source_directories(config.get('borgmatic_source_directory'))
+    )
+
+    (create_flags, create_positional_arguments, pattern_file, exclude_file) = (
+        make_base_create_command(
+            dry_run,
+            repository_path,
+            config,
+            config_paths,
+            local_borg_version,
+            global_arguments,
+            borgmatic_source_directories,
+            local_path,
+            remote_path,
+            progress,
+            json,
+            list_files,
+            stream_processes,
+        )
+    )
+
+    if json:
+        output_log_level = None
+    elif list_files or (stats and not dry_run):
+        output_log_level = logging.ANSWER
+    else:
+        output_log_level = logging.INFO
+
+    # The progress output isn't compatible with captured and logged output, as progress messes with
+    # the terminal directly.
+    output_file = DO_NOT_CAPTURE if progress else None
+
+    try:
+        working_directory = os.path.expanduser(config.get('working_directory'))
+    except TypeError:
+        working_directory = None
+
+    borg_environment = environment.make_environment(config)
+
     create_flags += (
         (('--info',) if logger.getEffectiveLevel() == logging.INFO and not json else ())
         + (('--stats',) if stats and not json and not dry_run else ())

borgmatic/borg/delete.py

@@ -0,0 +1,132 @@
+import argparse
+import logging
+
+import borgmatic.borg.environment
+import borgmatic.borg.feature
+import borgmatic.borg.flags
+import borgmatic.borg.rdelete
+import borgmatic.execute
+
+logger = logging.getLogger(__name__)
+
+
+def make_delete_command(
+    repository,
+    config,
+    local_borg_version,
+    delete_arguments,
+    global_arguments,
+    local_path,
+    remote_path,
+):
+    '''
+    Given a local or remote repository dict, a configuration dict, the local Borg version, the
+    arguments to the delete action as an argparse.Namespace, and global arguments, return a command
+    as a tuple to delete archives from the repository.
+    '''
+    return (
+        (local_path, 'delete')
+        + (('--info',) if logger.getEffectiveLevel() == logging.INFO else ())
+        + (('--debug', '--show-rc') if logger.isEnabledFor(logging.DEBUG) else ())
+        + borgmatic.borg.flags.make_flags('dry-run', global_arguments.dry_run)
+        + borgmatic.borg.flags.make_flags('remote-path', remote_path)
+        + borgmatic.borg.flags.make_flags('log-json', global_arguments.log_json)
+        + borgmatic.borg.flags.make_flags('lock-wait', config.get('lock_wait'))
+        + borgmatic.borg.flags.make_flags('list', delete_arguments.list_archives)
+        + (
+            (('--force',) + (('--force',) if delete_arguments.force >= 2 else ()))
+            if delete_arguments.force
+            else ()
+        )
+        # Ignore match_archives and archive_name_format options from configuration, so the user has
+        # to be explicit on the command-line about the archives they want to delete.
+        + borgmatic.borg.flags.make_match_archives_flags(
+            delete_arguments.match_archives or delete_arguments.archive,
+            archive_name_format=None,
+            local_borg_version=local_borg_version,
+            default_archive_name_format='*',
+        )
+        + borgmatic.borg.flags.make_flags_from_arguments(
+            delete_arguments,
+            excludes=('list_archives', 'force', 'match_archives', 'archive', 'repository'),
+        )
+        + borgmatic.borg.flags.make_repository_flags(repository['path'], local_borg_version)
+    )
+
+
+ARCHIVE_RELATED_ARGUMENT_NAMES = (
+    'archive',
+    'match_archives',
+    'first',
+    'last',
+    'oldest',
+    'newest',
+    'older',
+    'newer',
+)
+
+
+def delete_archives(
+    repository,
+    config,
+    local_borg_version,
+    delete_arguments,
+    global_arguments,
+    local_path='borg',
+    remote_path=None,
+):
+    '''
+    Given a local or remote repository dict, a configuration dict, the local Borg version, the
+    arguments to the delete action as an argparse.Namespace, global arguments as an
+    argparse.Namespace, and local and remote Borg paths, delete the selected archives from the
+    repository. If no archives are selected, then delete the entire repository.
+    '''
+    borgmatic.logger.add_custom_log_levels()
+
+    if not any(
+        getattr(delete_arguments, argument_name, None)
+        for argument_name in ARCHIVE_RELATED_ARGUMENT_NAMES
+    ):
+        if borgmatic.borg.feature.available(
+            borgmatic.borg.feature.Feature.RDELETE, local_borg_version
+        ):
+            logger.warning(
+                'Deleting an entire repository with the delete action is deprecated when using Borg 2.x+. Use the rdelete action instead.'
+            )
+
+        rdelete_arguments = argparse.Namespace(
+            repository=repository['path'],
+            list_archives=delete_arguments.list_archives,
+            force=delete_arguments.force,
+            cache_only=delete_arguments.cache_only,
+            keep_security_info=delete_arguments.keep_security_info,
+        )
+        borgmatic.borg.rdelete.delete_repository(
+            repository,
+            config,
+            local_borg_version,
+            rdelete_arguments,
+            global_arguments,
+            local_path,
+            remote_path,
+        )
+
+        return
+
+    command = make_delete_command(
+        repository,
+        config,
+        local_borg_version,
+        delete_arguments,
+        global_arguments,
+        local_path,
+        remote_path,
+    )
+
+    borgmatic.execute.execute_command(
+        command,
+        output_log_level=logging.ANSWER,
+        extra_environment=borgmatic.borg.environment.make_environment(config),
+        borg_local_path=local_path,
+        borg_exit_codes=config.get('borg_exit_codes'),
+    )

borgmatic/borg/extract.py

@@ -104,8 +104,13 @@ def extract_archive(
         if not paths:
             raise ValueError('The --strip-components flag with "all" requires at least one --path')
 
-        # Calculate the maximum number of leading path components of the given paths.
-        strip_components = max(0, *(len(path.split(os.path.sep)) - 1 for path in paths))
+        # Calculate the maximum number of leading path components of the given paths. "if piece"
+        # ignores empty path components, e.g. those resulting from a leading slash. And the "- 1"
+        # is so this doesn't count the final path component, e.g. the filename itself.
+        strip_components = max(
+            0,
+            *(len(tuple(piece for piece in path.split(os.path.sep) if piece)) - 1 for path in paths)
+        )
 
     full_command = (
         (local_path, 'extract')

borgmatic/borg/feature.py

@@ -13,8 +13,9 @@ class Feature(Enum):
     RCREATE = 7
     RLIST = 8
     RINFO = 9
-    MATCH_ARCHIVES = 10
-    EXCLUDED_FILES_MINUS = 11
+    RDELETE = 10
+    MATCH_ARCHIVES = 11
+    EXCLUDED_FILES_MINUS = 12
 
 
 FEATURE_TO_MINIMUM_BORG_VERSION = {
@@ -27,6 +28,7 @@ FEATURE_TO_MINIMUM_BORG_VERSION = {
     Feature.RCREATE: parse('2.0.0a2'),  # borg rcreate
     Feature.RLIST: parse('2.0.0a2'),  # borg rlist
     Feature.RINFO: parse('2.0.0a2'),  # borg rinfo
+    Feature.RDELETE: parse('2.0.0a2'),  # borg rdelete
     Feature.MATCH_ARCHIVES: parse('2.0.0b3'),  # borg --match-archives
     Feature.EXCLUDED_FILES_MINUS: parse('2.0.0b5'),  # --list --filter uses "-" for excludes
 }

borgmatic/borg/flags.py

@@ -66,7 +66,12 @@ def make_repository_archive_flags(repository_path, archive, local_borg_version):
 DEFAULT_ARCHIVE_NAME_FORMAT = '{hostname}-{now:%Y-%m-%dT%H:%M:%S.%f}'  # noqa: FS003
 
 
-def make_match_archives_flags(match_archives, archive_name_format, local_borg_version):
+def make_match_archives_flags(
+    match_archives,
+    archive_name_format,
+    local_borg_version,
+    default_archive_name_format=DEFAULT_ARCHIVE_NAME_FORMAT,
+):
     '''
     Return match archives flags based on the given match archives value, if any. If it isn't set,
     return match archives flags to match archives created with the given (or default) archive name
@@ -74,13 +79,16 @@ def make_match_archives_flags(match_archives, archive_name_format, local_borg_ve
     (like "{now}") with globs.
     '''
     if match_archives:
+        if match_archives in {'*', 're:.*', 'sh:*'}:
+            return ()
+
         if feature.available(feature.Feature.MATCH_ARCHIVES, local_borg_version):
             return ('--match-archives', match_archives)
         else:
             return ('--glob-archives', re.sub(r'^sh:', '', match_archives))
 
     derived_match_archives = re.sub(
-        r'\{(now|utcnow|pid)([:%\w\.-]*)\}', '*', archive_name_format or DEFAULT_ARCHIVE_NAME_FORMAT
+        r'\{(now|utcnow|pid)([:%\w\.-]*)\}', '*', archive_name_format or default_archive_name_format
     )
 
     if derived_match_archives == '*':

borgmatic/borg/list.py

@@ -79,9 +79,11 @@ def make_find_paths(find_paths):
         return ()
 
     return tuple(
-        find_path
-        if re.compile(r'([-!+RrPp] )|(\w\w:)').match(find_path)
-        else f'sh:**/*{find_path}*/**'
+        (
+            find_path
+            if re.compile(r'([-!+RrPp] )|(\w\w:)').match(find_path)
+            else f'sh:**/*{find_path}*/**'
+        )
         for find_path in find_paths
     )
 
@@ -93,14 +95,15 @@ def capture_archive_listing(
     local_borg_version,
     global_arguments,
     list_paths=None,
+    path_format=None,
     local_path='borg',
     remote_path=None,
 ):
     '''
     Given a local or remote repository path, an archive name, a configuration dict, the local Borg
-    version, global arguments as an argparse.Namespace, the archive paths in which to list files, and
-    local and remote Borg paths, capture the output of listing that archive and return it as a list
-    of file paths.
+    version, global arguments as an argparse.Namespace, the archive paths in which to list files,
+    the Borg path format to use for the output, and local and remote Borg paths, capture the output
+    of listing that archive and return it as a list of file paths.
     '''
     borg_environment = environment.make_environment(config)
 
@@ -116,7 +119,7 @@ def capture_archive_listing(
                     paths=[f'sh:{path}' for path in list_paths] if list_paths else None,
                     find_paths=None,
                     json=None,
-                    format='{path}{NL}',  # noqa: FS003
+                    format=path_format or '{path}{NL}',  # noqa: FS003
                 ),
                 global_arguments,
                 local_path,
@@ -141,12 +144,12 @@ def list_archive(
     remote_path=None,
 ):
     '''
-    Given a local or remote repository path, a configuration dict, the local Borg version, global
-    arguments as an argparse.Namespace, the arguments to the list action as an argparse.Namespace,
-    and local and remote Borg paths, display the output of listing the files of a Borg archive (or
-    return JSON output). If list_arguments.find_paths are given, list the files by searching across
-    multiple archives. If neither find_paths nor archive name are given, instead list the archives
-    in the given repository.
+    Given a local or remote repository path, a configuration dict, the local Borg version, the
+    arguments to the list action as an argparse.Namespace, global arguments as an
+    argparse.Namespace, and local and remote Borg paths, display the output of listing the files of
+    a Borg archive (or return JSON output). If list_arguments.find_paths are given, list the files
+    by searching across multiple archives. If neither find_paths nor archive name are given, instead
+    list the archives in the given repository.
     '''
     borgmatic.logger.add_custom_log_levels()
 

borgmatic/borg/rdelete.py

@@ -0,0 +1,92 @@
+import logging
+
+import borgmatic.borg.environment
+import borgmatic.borg.feature
+import borgmatic.borg.flags
+import borgmatic.execute
+
+logger = logging.getLogger(__name__)
+
+
+def make_rdelete_command(
+    repository,
+    config,
+    local_borg_version,
+    rdelete_arguments,
+    global_arguments,
+    local_path,
+    remote_path,
+):
+    '''
+    Given a local or remote repository dict, a configuration dict, the local Borg version, the
+    arguments to the rdelete action as an argparse.Namespace, and global arguments, return a command
+    as a tuple to rdelete the entire repository.
+    '''
+    return (
+        (local_path,)
+        + (
+            ('rdelete',)
+            if borgmatic.borg.feature.available(
+                borgmatic.borg.feature.Feature.RDELETE, local_borg_version
+            )
+            else ('delete',)
+        )
+        + (('--info',) if logger.getEffectiveLevel() == logging.INFO else ())
+        + (('--debug', '--show-rc') if logger.isEnabledFor(logging.DEBUG) else ())
+        + borgmatic.borg.flags.make_flags('dry-run', global_arguments.dry_run)
+        + borgmatic.borg.flags.make_flags('remote-path', remote_path)
+        + borgmatic.borg.flags.make_flags('log-json', global_arguments.log_json)
+        + borgmatic.borg.flags.make_flags('lock-wait', config.get('lock_wait'))
+        + borgmatic.borg.flags.make_flags('list', rdelete_arguments.list_archives)
+        + (
+            (('--force',) + (('--force',) if rdelete_arguments.force >= 2 else ()))
+            if rdelete_arguments.force
+            else ()
+        )
+        + borgmatic.borg.flags.make_flags_from_arguments(
+            rdelete_arguments, excludes=('list_archives', 'force', 'repository')
+        )
+        + borgmatic.borg.flags.make_repository_flags(repository['path'], local_borg_version)
+    )
+
+
+def delete_repository(
+    repository,
+    config,
+    local_borg_version,
+    rdelete_arguments,
+    global_arguments,
+    local_path='borg',
+    remote_path=None,
+):
+    '''
+    Given a local or remote repository dict, a configuration dict, the local Borg version, the
+    arguments to the rdelete action as an argparse.Namespace, global arguments as an
+    argparse.Namespace, and local and remote Borg paths, rdelete the entire repository.
+    '''
+    borgmatic.logger.add_custom_log_levels()
+
+    command = make_rdelete_command(
+        repository,
+        config,
+        local_borg_version,
+        rdelete_arguments,
+        global_arguments,
+        local_path,
+        remote_path,
+    )
+
+    borgmatic.execute.execute_command(
+        command,
+        output_log_level=logging.ANSWER,
+        # Don't capture output when Borg is expected to prompt for interactive confirmation, or the
+        # prompt won't work.
+        output_file=(
+            None
+            if rdelete_arguments.force or rdelete_arguments.cache_only
+            else borgmatic.execute.DO_NOT_CAPTURE
+        ),
+        extra_environment=borgmatic.borg.environment.make_environment(config),
+        borg_local_path=local_path,
+        borg_exit_codes=config.get('borg_exit_codes'),
+    )

borgmatic/commands/arguments.py

@@ -12,11 +12,13 @@ ACTION_ALIASES = {
     'create': ['-C'],
     'check': ['-k'],
     'config': [],
+    'delete': [],
     'extract': ['-x'],
     'export-tar': [],
     'mount': ['-m'],
     'umount': ['-u'],
     'restore': ['-r'],
+    'rdelete': [],
     'rlist': [],
     'list': ['-l'],
     'rinfo': [],
@@ -113,6 +115,54 @@ def parse_and_record_action_arguments(
     return tuple(argument for argument in remaining if argument != action_name)
 
 
+def argument_is_flag(argument):
+    '''
+    Return True if the given argument looks like a flag, e.g. '--some-flag', as opposed to a
+    non-flag value.
+    '''
+    return isinstance(argument, str) and argument.startswith('--')
+
+
+def group_arguments_with_values(arguments):
+    '''
+    Given a sequence of arguments, return a sequence of tuples where each one contains either a
+    single argument (such as for a stand-alone flag) or a flag argument and its corresponding value.
+
+    For instance, given the following arguments sequence as input:
+
+      ('--foo', '--bar', '33', '--baz')
+
+    ... return the following output:
+
+      (('--foo',), ('--bar', '33'), ('--baz',))
+    '''
+    grouped_arguments = []
+    index = 0
+
+    while index < len(arguments):
+        this_argument = arguments[index]
+
+        try:
+            next_argument = arguments[index + 1]
+        except IndexError:
+            grouped_arguments.append((this_argument,))
+            break
+
+        if (
+            argument_is_flag(this_argument)
+            and not argument_is_flag(next_argument)
+            and next_argument not in ACTION_ALIASES
+        ):
+            grouped_arguments.append((this_argument, next_argument))
+            index += 2
+            continue
+
+        grouped_arguments.append((this_argument,))
+        index += 1
+
+    return tuple(grouped_arguments)
+
+
 def get_unparsable_arguments(remaining_action_arguments):
     '''
     Given a sequence of argument tuples (one per action parser that parsed arguments), determine the
@@ -121,12 +171,21 @@ def get_unparsable_arguments(remaining_action_arguments):
     if not remaining_action_arguments:
         return ()
 
+    grouped_action_arguments = tuple(
+        group_arguments_with_values(action_arguments)
+        for action_arguments in remaining_action_arguments
+    )
+
     return tuple(
-        argument
-        for argument in dict.fromkeys(
-            itertools.chain.from_iterable(remaining_action_arguments)
-        ).keys()
-        if all(argument in action_arguments for action_arguments in remaining_action_arguments)
+        itertools.chain.from_iterable(
+            argument_group
+            for argument_group in dict.fromkeys(
+                itertools.chain.from_iterable(grouped_action_arguments)
+            ).keys()
+            if all(
+                argument_group in action_arguments for action_arguments in grouped_action_arguments
+            )
+        )
     )
 
 
@@ -481,7 +540,7 @@ def make_parsers():
         dest='stats',
         default=False,
         action='store_true',
-        help='Display statistics of archive',
+        help='Display statistics of the pruned archive',
     )
     prune_group.add_argument(
         '--list', dest='list_archives', action='store_true', help='List archives kept/pruned'
@@ -604,6 +663,11 @@ def make_parsers():
         action='store_true',
         help='Attempt to repair any inconsistencies found (for interactive use)',
     )
+    check_group.add_argument(
+        '--max-duration',
+        metavar='SECONDS',
+        help='How long to check the repository before interrupting the check, defaults to no interruption',
+    )
     check_group.add_argument(
         '-a',
         '--match-archives',
@@ -614,10 +678,10 @@ def make_parsers():
     check_group.add_argument(
         '--only',
         metavar='CHECK',
-        choices=('repository', 'archives', 'data', 'extract'),
+        choices=('repository', 'archives', 'data', 'extract', 'spot'),
         dest='only_checks',
         action='append',
-        help='Run a particular consistency check (repository, archives, data, or extract) instead of configured checks (subject to configured frequency, can specify flag multiple times)',
+        help='Run a particular consistency check (repository, archives, data, extract, or spot) instead of configured checks (subject to configured frequency, can specify flag multiple times)',
     )
     check_group.add_argument(
         '--force',
@@ -627,6 +691,97 @@ def make_parsers():
     )
     check_group.add_argument('-h', '--help', action='help', help='Show this help message and exit')
 
+    delete_parser = action_parsers.add_parser(
+        'delete',
+        aliases=ACTION_ALIASES['delete'],
+        help='Delete an archive from a repository or delete an entire repository (with Borg 1.2+, you must run compact afterwards to actually free space)',
+        description='Delete an archive from a repository or delete an entire repository (with Borg 1.2+, you must run compact afterwards to actually free space)',
+        add_help=False,
+    )
+    delete_group = delete_parser.add_argument_group('delete arguments')
+    delete_group.add_argument(
+        '--repository',
+        help='Path of repository to delete or delete archives from, defaults to the configured repository if there is only one',
+    )
+    delete_group.add_argument(
+        '--archive',
+        help='Archive to delete',
+    )
+    delete_group.add_argument(
+        '--list',
+        dest='list_archives',
+        action='store_true',
+        help='Show details for the deleted archives',
+    )
+    delete_group.add_argument(
+        '--stats',
+        action='store_true',
+        help='Display statistics for the deleted archives',
+    )
+    delete_group.add_argument(
+        '--cache-only',
+        action='store_true',
+        help='Delete only the local cache for the given repository',
+    )
+    delete_group.add_argument(
+        '--force',
+        action='count',
+        help='Force deletion of corrupted archives, can be given twice if once does not work',
+    )
+    delete_group.add_argument(
+        '--keep-security-info',
+        action='store_true',
+        help='Do not delete the local security info when deleting a repository',
+    )
+    delete_group.add_argument(
+        '--save-space',
+        action='store_true',
+        help='Work slower, but using less space [Not supported in Borg 2.x+]',
+    )
+    delete_group.add_argument(
+        '--checkpoint-interval',
+        type=int,
+        metavar='SECONDS',
+        help='Write a checkpoint at the given interval, defaults to 1800 seconds (30 minutes)',
+    )
+    delete_group.add_argument(
+        '-a',
+        '--match-archives',
+        '--glob-archives',
+        metavar='PATTERN',
+        help='Only delete archives matching this pattern',
+    )
+    delete_group.add_argument(
+        '--sort-by', metavar='KEYS', help='Comma-separated list of sorting keys'
+    )
+    delete_group.add_argument(
+        '--first', metavar='N', help='Delete first N archives after other filters are applied'
+    )
+    delete_group.add_argument(
+        '--last', metavar='N', help='Delete last N archives after other filters are applied'
+    )
+    delete_group.add_argument(
+        '--oldest',
+        metavar='TIMESPAN',
+        help='Delete archives within a specified time range starting from the timestamp of the oldest archive (e.g. 7d or 12m) [Borg 2.x+ only]',
+    )
+    delete_group.add_argument(
+        '--newest',
+        metavar='TIMESPAN',
+        help='Delete archives within a time range that ends at timestamp of the newest archive and starts a specified time range ago (e.g. 7d or 12m) [Borg 2.x+ only]',
+    )
+    delete_group.add_argument(
+        '--older',
+        metavar='TIMESPAN',
+        help='Delete archives that are older than the specified time range (e.g. 7d or 12m) from the current time [Borg 2.x+ only]',
+    )
+    delete_group.add_argument(
+        '--newer',
+        metavar='TIMESPAN',
+        help='Delete archives that are newer than the specified time range (e.g. 7d or 12m) from the current time [Borg 2.x+ only]',
+    )
+    delete_group.add_argument('-h', '--help', action='help', help='Show this help message and exit')
+
     extract_parser = action_parsers.add_parser(
         'extract',
         aliases=ACTION_ALIASES['extract'],
@@ -915,6 +1070,43 @@ def make_parsers():
     )
     umount_group.add_argument('-h', '--help', action='help', help='Show this help message and exit')
 
+    rdelete_parser = action_parsers.add_parser(
+        'rdelete',
+        aliases=ACTION_ALIASES['rdelete'],
+        help='Delete an entire repository (with Borg 1.2+, you must run compact afterwards to actually free space)',
+        description='Delete an entire repository (with Borg 1.2+, you must run compact afterwards to actually free space)',
+        add_help=False,
+    )
+    rdelete_group = rdelete_parser.add_argument_group('delete arguments')
+    rdelete_group.add_argument(
+        '--repository',
+        help='Path of repository to delete, defaults to the configured repository if there is only one',
+    )
+    rdelete_group.add_argument(
+        '--list',
+        dest='list_archives',
+        action='store_true',
+        help='Show details for the archives in the given repository',
+    )
+    rdelete_group.add_argument(
+        '--force',
+        action='count',
+        help='Force deletion of corrupted archives, can be given twice if once does not work',
+    )
+    rdelete_group.add_argument(
+        '--cache-only',
+        action='store_true',
+        help='Delete only the local cache for the given repository',
+    )
+    rdelete_group.add_argument(
+        '--keep-security-info',
+        action='store_true',
+        help='Do not delete the local security info when deleting a repository',
+    )
+    rdelete_group.add_argument(
+        '-h', '--help', action='help', help='Show this help message and exit'
+    )
+
     restore_parser = action_parsers.add_parser(
         'restore',
         aliases=ACTION_ALIASES['restore'],

borgmatic/commands/borgmatic.py

@@ -18,6 +18,7 @@ import borgmatic.actions.config.bootstrap
 import borgmatic.actions.config.generate
 import borgmatic.actions.config.validate
 import borgmatic.actions.create
+import borgmatic.actions.delete
 import borgmatic.actions.export_key
 import borgmatic.actions.export_tar
 import borgmatic.actions.extract
@@ -26,6 +27,7 @@ import borgmatic.actions.list
 import borgmatic.actions.mount
 import borgmatic.actions.prune
 import borgmatic.actions.rcreate
+import borgmatic.actions.rdelete
 import borgmatic.actions.restore
 import borgmatic.actions.rinfo
 import borgmatic.actions.rlist
@@ -169,7 +171,7 @@ def run_configuration(config_filename, config, config_paths, arguments):
                     continue
 
                 if command.considered_soft_failure(config_filename, error):
-                    return
+                    break
 
                 yield from log_error_records(
                     f'{repository.get("label", repository["path"])}: Error running actions for repository',
@@ -191,11 +193,9 @@ def run_configuration(config_filename, config, config_paths, arguments):
                 global_arguments.dry_run,
             )
     except (OSError, CalledProcessError) as error:
-        if command.considered_soft_failure(config_filename, error):
-            return
-
-        encountered_error = error
-        yield from log_error_records(f'{repository["path"]}: Error pinging monitor', error)
+        if not command.considered_soft_failure(config_filename, error):
+            encountered_error = error
+            yield from log_error_records(f'{repository["path"]}: Error pinging monitor', error)
 
     if not encountered_error:
         try:
@@ -288,10 +288,11 @@ def run_actions(
     global_arguments = arguments['global']
     dry_run_label = ' (dry run; not making any changes)' if global_arguments.dry_run else ''
     hook_context = {
-        'repository': repository_path,
+        'repository_label': repository.get('label', ''),
+        'log_file': global_arguments.log_file if global_arguments.log_file else '',
         # Deprecated: For backwards compatibility with borgmatic < 1.6.0.
         'repositories': ','.join([repo['path'] for repo in config['repositories']]),
-        'log_file': global_arguments.log_file if global_arguments.log_file else '',
+        'repository': repository_path,
     }
     skip_actions = set(get_skip_actions(config, arguments))
 
@@ -480,6 +481,26 @@ def run_actions(
                 local_path,
                 remote_path,
             )
+        elif action_name == 'delete' and action_name not in skip_actions:
+            borgmatic.actions.delete.run_delete(
+                repository,
+                config,
+                local_borg_version,
+                action_arguments,
+                global_arguments,
+                local_path,
+                remote_path,
+            )
+        elif action_name == 'rdelete' and action_name not in skip_actions:
+            borgmatic.actions.rdelete.run_rdelete(
+                repository,
+                config,
+                local_borg_version,
+                action_arguments,
+                global_arguments,
+                local_path,
+                remote_path,
+            )
         elif action_name == 'borg' and action_name not in skip_actions:
             borgmatic.actions.borg.run_borg(
                 repository,

borgmatic/config/constants.py

@@ -50,12 +50,15 @@ def apply_constants(value, constants, shell_escape=False):
             value[index] = apply_constants(list_value, constants, shell_escape)
     elif isinstance(value, dict):
         for option_name, option_value in value.items():
-            shell_escape = (
-                shell_escape
-                or option_name.startswith('before_')
-                or option_name.startswith('after_')
-                or option_name == 'on_error'
+            value[option_name] = apply_constants(
+                option_value,
+                constants,
+                shell_escape=(
+                    shell_escape
+                    or option_name.startswith('before_')
+                    or option_name.startswith('after_')
+                    or option_name == 'on_error'
+                ),
             )
-            value[option_name] = apply_constants(option_value, constants, shell_escape)
 
     return value

borgmatic/config/generate.py

@@ -21,6 +21,19 @@ def insert_newline_before_comment(config, field_name):
     )
 
 
+def get_properties(schema):
+    '''
+    Given a schema dict, return its properties. But if it's got sub-schemas with multiple different
+    potential properties, returned their merged properties instead.
+    '''
+    if 'oneOf' in schema:
+        return dict(
+            collections.ChainMap(*[sub_schema['properties'] for sub_schema in schema['oneOf']])
+        )
+
+    return schema['properties']
+
+
 def schema_to_sample_configuration(schema, level=0, parent_is_sequence=False):
     '''
     Given a loaded configuration schema, generate and return sample config for it. Include comments
@@ -40,7 +53,7 @@ def schema_to_sample_configuration(schema, level=0, parent_is_sequence=False):
         config = ruamel.yaml.comments.CommentedMap(
             [
                 (field_name, schema_to_sample_configuration(sub_schema, level + 1))
-                for field_name, sub_schema in schema['properties'].items()
+                for field_name, sub_schema in get_properties(schema).items()
             ]
         )
         indent = (level * INDENT) + (SEQUENCE_INDENT if parent_is_sequence else 0)
@@ -151,7 +164,7 @@ def add_comments_to_configuration_sequence(config, schema, indent=0):
         return
 
     for field_name in config[0].keys():
-        field_schema = schema['items']['properties'].get(field_name, {})
+        field_schema = get_properties(schema['items']).get(field_name, {})
         description = field_schema.get('description')
 
         # No description to use? Skip it.
@@ -178,7 +191,7 @@ def add_comments_to_configuration_object(config, schema, indent=0, skip_first=Fa
         if skip_first and index == 0:
             continue
 
-        field_schema = schema['properties'].get(field_name, {})
+        field_schema = get_properties(schema).get(field_name, {})
         description = field_schema.get('description', '').strip()
 
         # If this is an optional key, add an indicator to the comment flagging it to be commented

borgmatic/config/schema.yaml

@@ -269,7 +269,8 @@ properties:
     compression:
         type: string
         description: |
-            Type of compression to use when creating archives. See
+            Type of compression to use when creating archives. (Compression
+            level can be added separated with a comma, like "zstd,7".) See
             http://borgbackup.readthedocs.io/en/stable/usage/create.html for
             details. Defaults to "lz4".
         example: lz4
@@ -279,6 +280,11 @@ properties:
             Remote network upload rate limit in kiBytes/second. Defaults to
             unlimited.
         example: 100
+    upload_buffer_size:
+        type: integer
+        description: |
+            Size of network upload buffer in MiB. Defaults to no buffer.
+        example: 160
     retries:
         type: integer
         description: |
@@ -503,37 +509,205 @@ properties:
         type: array
         items:
             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". "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". See "skip_actions"
-                        for disabling checks altogether.
-                    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
+            oneOf:
+                - required: [name]
+                  additionalProperties: false
+                  properties:
+                      name:
+                          type: string
+                          enum:
+                              - archives
+                              - data
+                              - extract
+                              - disabled
+                          description: |
+                              Name of consistency check to run: "repository",
+                              "archives", "data", "spot", and/or "extract".
+                              "repository" checks the consistency of the
+                              repository, "archives" checks all of the
+                              archives, "data" verifies the integrity of the
+                              data within the archives, "spot" checks that
+                              some percentage of source files are found in the
+                              most recent archive (with identical contents),
+                              and "extract" does an extraction dry-run of the
+                              most recent archive. Note that "data" implies
+                              "archives". See "skip_actions" for disabling
+                              checks altogether.
+                          example: spot
+                      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
+                      only_run_on:
+                          type: array
+                          items:
+                              type: string
+                          description: |
+                              After the "frequency" duration has elapsed, only
+                              run this check if the current day of the week
+                              matches one of these values (the name of a day of
+                              the week in the current locale). "weekday" and
+                              "weekend" are also accepted. Defaults to running
+                              the check on any day of the week.
+                          example:
+                              - Saturday
+                              - Sunday
+                - required: [name]
+                  additionalProperties: false
+                  properties:
+                      name:
+                          type: string
+                          enum:
+                              - repository
+                          description: |
+                              Name of consistency check to run: "repository",
+                              "archives", "data", "spot", and/or "extract".
+                              "repository" checks the consistency of the
+                              repository, "archives" checks all of the
+                              archives, "data" verifies the integrity of the
+                              data within the archives, "spot" checks that
+                              some percentage of source files are found in the
+                              most recent archive (with identical contents),
+                              and "extract" does an extraction dry-run of the
+                              most recent archive. Note that "data" implies
+                              "archives". See "skip_actions" for disabling
+                              checks altogether.
+                          example: spot
+                      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
+                      only_run_on:
+                          type: array
+                          items:
+                              type: string
+                          description: |
+                              After the "frequency" duration has elapsed, only
+                              run this check if the current day of the week
+                              matches one of these values (the name of a day of
+                              the week in the current locale). "weekday" and
+                              "weekend" are also accepted. Defaults to running
+                              the check on any day of the week.
+                          example:
+                              - Saturday
+                              - Sunday
+                      max_duration:
+                          type: integer
+                          description: |
+                              How many seconds to check the repository before
+                              interrupting the check. Useful for splitting a
+                              long-running repository check into multiple
+                              partial checks. Defaults to no interruption. Only
+                              applies to the "repository" check, does not check
+                              the repository index, and is not compatible with a
+                              simultaneous "archives" check or "--repair" flag.
+                          example: 3600
+                - required:
+                    - name
+                    - count_tolerance_percentage
+                    - data_sample_percentage
+                    - data_tolerance_percentage
+                  additionalProperties: false
+                  properties:
+                      name:
+                          type: string
+                          enum:
+                              - spot
+                          description: |
+                              Name of consistency check to run: "repository",
+                              "archives", "data", "spot", and/or "extract".
+                              "repository" checks the consistency of the
+                              repository, "archives" checks all of the
+                              archives, "data" verifies the integrity of the
+                              data within the archives, "spot" checks that
+                              some percentage of source files are found in the
+                              most recent archive (with identical contents),
+                              and "extract" does an extraction dry-run of the
+                              most recent archive. Note that "data" implies
+                              "archives". See "skip_actions" for disabling
+                              checks altogether.
+                          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
+                      only_run_on:
+                          type: array
+                          items:
+                              type: string
+                          description: |
+                              After the "frequency" duration has elapsed, only
+                              run this check if the current day of the week
+                              matches one of these values (the name of a day of
+                              the week in the current locale). "weekday" and
+                              "weekend" are also accepted. Defaults to running
+                              the check on any day of the week.
+                          example:
+                              - Saturday
+                              - Sunday
+                      count_tolerance_percentage:
+                          type: number
+                          description: |
+                              The percentage delta between the source
+                              directories file count and the most recent backup
+                              archive file count that is allowed before the
+                              entire consistency check fails. This can catch
+                              problems like incorrect excludes, inadvertent
+                              deletes, etc. Only applies to the "spot" check.
+                          example: 10
+                      data_sample_percentage:
+                          type: number
+                          description: |
+                              The percentage of total files in the source
+                              directories to randomly sample and compare to
+                              their corresponding files in the most recent
+                              backup archive. Only applies to the "spot" check.
+                          example: 1
+                      data_tolerance_percentage:
+                          type: number
+                          description: |
+                              The percentage of total files in the source
+                              directories that can fail a spot check comparison
+                              without failing the entire consistency check. This
+                              can catch problems like source files that have
+                              been bulk-changed by malware, backups that have
+                              been tampered with, etc. The value must be lower
+                              than or equal to the "contents_sample_percentage".
+                              Only applies to the "spot" check.
+                          example: 0.5
+                      xxh64sum_command:
+                          type: string
+                          description: |
+                              Command to use instead of "xxh64sum" to hash
+                              source files, usually found in an OS package named
+                              "xxhash". Do not substitute with a different hash
+                              type (SHA, MD5, etc.) or the check will never
+                              succeed. Only applies to the "spot" check.
+                          example: /usr/local/bin/xxh64sum
         description: |
             List of one or more consistency checks to run on a periodic basis
             (if "frequency" is set) or every time borgmatic runs checks (if
@@ -573,11 +747,13 @@ properties:
                 - compact
                 - create
                 - check
+                - delete
                 - extract
                 - config
                 - export-tar
                 - mount
                 - umount
+                - rdelete
                 - restore
                 - rlist
                 - list
@@ -1579,11 +1755,51 @@ properties:
                     states.
                 example:
                     - finish
+            create_slug:
+                type: boolean
+                description: |
+                    Create the check if it does not exist. Only works with
+                    the slug URL scheme (https://hc-ping.com/<ping-key>/<slug>
+                    as opposed to https://hc-ping.com/<uuid>).
+                    Defaults to false.
+                example: true
         description: |
             Configuration for a monitoring integration with Healthchecks. Create
             an account at https://healthchecks.io (or self-host Healthchecks) if
             you'd like to use this service. See borgmatic monitoring
             documentation for details.
+    uptime_kuma:
+        type: object
+        required: ['push_url']
+        additionalProperties: false
+        properties:
+            push_url:
+                type: string
+                description: |
+                  Uptime Kuma push URL without query string (do not include the
+                  question mark or anything after it).
+                example: https://example.uptime.kuma/api/push/abcd1234
+            states:
+                type: array
+                items:
+                    type: string
+                    enum:
+                        - start
+                        - finish
+                        - fail
+                    uniqueItems: true
+                description: |
+                    List of one or more monitoring states to push for: "start",
+                    "finish", and/or "fail". Defaults to pushing for all
+                    states.
+                example:
+                    - start
+                    - finish
+                    - fail
+        description: |
+            Configuration for a monitoring integration with Uptime Kuma using
+            the Push monitor type.
+            See more information here: https://uptime.kuma.pet
     cronitor:
         type: object
         required: ['ping_url']

borgmatic/execute.py

@@ -4,6 +4,7 @@ import logging
 import os
 import select
 import subprocess
+import textwrap
 
 logger = logging.getLogger(__name__)
 
@@ -219,13 +220,41 @@ def log_outputs(processes, exclude_stdouts, output_log_level, borg_local_path, b
         }
 
 
+SECRET_COMMAND_FLAG_NAMES = {'--password'}
+
+
+def mask_command_secrets(full_command):
+    '''
+    Given a command as a sequence, mask secret values for flags like "--password" in preparation for
+    logging.
+    '''
+    masked_command = []
+    previous_piece = None
+
+    for piece in full_command:
+        masked_command.append('***' if previous_piece in SECRET_COMMAND_FLAG_NAMES else piece)
+        previous_piece = piece
+
+    return tuple(masked_command)
+
+
+MAX_LOGGED_COMMAND_LENGTH = 1000
+
+
 def log_command(full_command, input_file=None, output_file=None, environment=None):
     '''
     Log the given command (a sequence of command/argument strings), along with its input/output file
     paths and extra environment variables (with omitted values in case they contain passwords).
     '''
     logger.debug(
-        ' '.join(tuple(f'{key}=***' for key in (environment or {}).keys()) + tuple(full_command))
+        textwrap.shorten(
+            ' '.join(
+                tuple(f'{key}=***' for key in (environment or {}).keys())
+                + mask_command_secrets(full_command)
+            ),
+            width=MAX_LOGGED_COMMAND_LENGTH,
+            placeholder=' ...',
+        )
         + (f" < {getattr(input_file, 'name', '')}" if input_file else '')
         + (f" > {getattr(output_file, 'name', '')}" if output_file else '')
     )
@@ -376,9 +405,9 @@ def execute_command_with_processes(
             command,
             stdin=input_file,
             stdout=None if do_not_capture else (output_file or subprocess.PIPE),
-            stderr=None
-            if do_not_capture
-            else (subprocess.PIPE if output_file else subprocess.STDOUT),
+            stderr=(
+                None if do_not_capture else (subprocess.PIPE if output_file else subprocess.STDOUT)
+            ),
             shell=shell,
             env=environment,
             cwd=working_directory,

borgmatic/hooks/command.py

@@ -68,9 +68,9 @@ def execute_hook(commands, umask, config_filename, description, dry_run, **conte
             if not dry_run:
                 execute.execute_command(
                     [command],
-                    output_log_level=logging.ERROR
-                    if description == 'on-error'
-                    else logging.WARNING,
+                    output_log_level=(
+                        logging.ERROR if description == 'on-error' else logging.WARNING
+                    ),
                     shell=True,
                 )
     finally:

borgmatic/hooks/dispatch.py

@@ -13,6 +13,7 @@ from borgmatic.hooks import (
     pagerduty,
     postgresql,
     sqlite,
+    uptimekuma,
 )
 
 logger = logging.getLogger(__name__)
@@ -22,6 +23,7 @@ HOOK_NAME_TO_MODULE = {
     'cronhub': cronhub,
     'cronitor': cronitor,
     'healthchecks': healthchecks,
+    'loki': loki,
     'mariadb_databases': mariadb,
     'mongodb_databases': mongodb,
     'mysql_databases': mysql,
@@ -29,7 +31,7 @@ HOOK_NAME_TO_MODULE = {
     'pagerduty': pagerduty,
     'postgresql_databases': postgresql,
     'sqlite_databases': sqlite,
-    'loki': loki,
+    'uptime_kuma': uptimekuma,
 }
 
 

borgmatic/hooks/healthchecks.py

@@ -1,4 +1,5 @@
 import logging
+import re
 
 import requests
 
@@ -14,7 +15,7 @@ MONITOR_STATE_TO_HEALTHCHECKS = {
     monitor.State.LOG: 'log',
 }
 
-DEFAULT_PING_BODY_LIMIT_BYTES = 1500
+DEFAULT_PING_BODY_LIMIT_BYTES = 100000
 HANDLER_IDENTIFIER = 'healthchecks'
 
 
@@ -59,10 +60,20 @@ def ping_monitor(hook_config, config, config_filename, state, monitoring_log_lev
         )
         return
 
+    ping_url_is_uuid = re.search(r'\w{8}-\w{4}-\w{4}-\w{4}-\w{12}$', ping_url)
+
     healthchecks_state = MONITOR_STATE_TO_HEALTHCHECKS.get(state)
     if healthchecks_state:
         ping_url = f'{ping_url}/{healthchecks_state}'
 
+    if hook_config.get('create_slug'):
+        if ping_url_is_uuid:
+            logger.warning(
+                f'{config_filename}: Healthchecks UUIDs do not support auto provisionning; ignoring'
+            )
+        else:
+            ping_url = f'{ping_url}?create=1'
+
     logger.info(f'{config_filename}: Pinging Healthchecks {state.name.lower()}{dry_run_label}')
     logger.debug(f'{config_filename}: Using Healthchecks ping URL {ping_url}')
 

borgmatic/hooks/mariadb.py

@@ -115,6 +115,14 @@ def execute_dump_command(
     )
 
 
+def use_streaming(databases, config, log_prefix):
+    '''
+    Given a sequence of MariaDB database configuration dicts, a configuration dict (ignored), and a
+    log prefix (ignored), return whether streaming will be using during dumps.
+    '''
+    return any(databases)
+
+
 def dump_data_sources(databases, config, log_prefix, dry_run):
     '''
     Dump the given MariaDB databases to a named pipe. The databases are supplied as a sequence of

borgmatic/hooks/mongodb.py

@@ -16,6 +16,14 @@ def make_dump_path(config):  # pragma: no cover
     )
 
 
+def use_streaming(databases, config, log_prefix):
+    '''
+    Given a sequence of MongoDB database configuration dicts, a configuration dict (ignored), and a
+    log prefix (ignored), return whether streaming will be using during dumps.
+    '''
+    return any(database.get('format') != 'directory' for database in databases)
+
+
 def dump_data_sources(databases, config, log_prefix, dry_run):
     '''
     Dump the given MongoDB databases to a named pipe. The databases are supplied as a sequence of

borgmatic/hooks/monitor.py

@@ -1,6 +1,15 @@
 from enum import Enum
 
-MONITOR_HOOK_NAMES = ('apprise', 'healthchecks', 'cronitor', 'cronhub', 'pagerduty', 'ntfy', 'loki')
+MONITOR_HOOK_NAMES = (
+    'apprise',
+    'cronhub',
+    'cronitor',
+    'healthchecks',
+    'loki',
+    'ntfy',
+    'pagerduty',
+    'uptime_kuma',
+)
 
 
 class State(Enum):

borgmatic/hooks/mysql.py

@@ -114,6 +114,14 @@ def execute_dump_command(
     )
 
 
+def use_streaming(databases, config, log_prefix):
+    '''
+    Given a sequence of MySQL database configuration dicts, a configuration dict (ignored), and a
+    log prefix (ignored), return whether streaming will be using during dumps.
+    '''
+    return any(databases)
+
+
 def dump_data_sources(databases, config, log_prefix, dry_run):
     '''
     Dump the given MySQL/MariaDB databases to a named pipe. The databases are supplied as a sequence

borgmatic/hooks/pagerduty.py

@@ -40,9 +40,7 @@ def ping_monitor(hook_config, config, config_filename, state, monitoring_log_lev
         return
 
     hostname = platform.node()
-    local_timestamp = (
-        datetime.datetime.utcnow().replace(tzinfo=datetime.timezone.utc).astimezone().isoformat()
-    )
+    local_timestamp = datetime.datetime.now(datetime.timezone.utc).astimezone().isoformat()
     payload = json.dumps(
         {
             'routing_key': hook_config['integration_key'],

borgmatic/hooks/postgresql.py

@@ -96,6 +96,14 @@ def database_names_to_dump(database, extra_environment, log_prefix, dry_run):
     )
 
 
+def use_streaming(databases, config, log_prefix):
+    '''
+    Given a sequence of PostgreSQL database configuration dicts, a configuration dict (ignored), and
+    a log prefix (ignored), return whether streaming will be using during dumps.
+    '''
+    return any(database.get('format') != 'directory' for database in databases)
+
+
 def dump_data_sources(databases, config, log_prefix, dry_run):
     '''
     Dump the given PostgreSQL databases to a named pipe. The databases are supplied as a sequence of

borgmatic/hooks/sqlite.py

@@ -17,9 +17,17 @@ def make_dump_path(config):  # pragma: no cover
     )
 
 
+def use_streaming(databases, config, log_prefix):
+    '''
+    Given a sequence of SQLite database configuration dicts, a configuration dict (ignored), and a
+    log prefix (ignored), return whether streaming will be using during dumps.
+    '''
+    return any(databases)
+
+
 def dump_data_sources(databases, config, log_prefix, dry_run):
     '''
-    Dump the given SQLite3 databases to a named pipe. The databases are supplied as a sequence of
+    Dump the given SQLite databases to a named pipe. The databases are supplied as a sequence of
     configuration dicts, as per the configuration schema. Use the given configuration dict to
     construct the destination path and the given log prefix in any log entries.
 
@@ -71,7 +79,7 @@ def dump_data_sources(databases, config, log_prefix, dry_run):
 
 def remove_data_source_dumps(databases, config, log_prefix, dry_run):  # pragma: no cover
     '''
-    Remove the given SQLite3 database dumps from the filesystem. The databases are supplied as a
+    Remove the given SQLite database dumps from the filesystem. The databases are supplied as a
     sequence of configuration dicts, as per the configuration schema. Use the given configuration
     dict to construct the destination path and the given log prefix in any log entries. If this is a
     dry run, then don't actually remove anything.
@@ -81,8 +89,8 @@ def remove_data_source_dumps(databases, config, log_prefix, dry_run):  # pragma:
 
 def make_data_source_dump_pattern(databases, config, log_prefix, name=None):  # pragma: no cover
     '''
-    Make a pattern that matches the given SQLite3 databases. The databases are supplied as a
-    sequence of configuration dicts, as per the configuration schema.
+    Make a pattern that matches the given SQLite databases. The databases are supplied as a sequence
+    of configuration dicts, as per the configuration schema.
     '''
     return dump.make_data_source_dump_filename(make_dump_path(config), name)
 

borgmatic/hooks/uptimekuma.py

@@ -0,0 +1,55 @@
+import logging
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+
+def initialize_monitor(
+    push_url, config, config_filename, monitoring_log_level, dry_run
+):  # pragma: no cover
+    '''
+    No initialization is necessary for this monitor.
+    '''
+    pass
+
+
+def ping_monitor(hook_config, config, config_filename, state, monitoring_log_level, dry_run):
+    '''
+    Make a get request to the configured Uptime Kuma push_url. Use the given configuration filename
+    in any log entries. If this is a dry run, then don't actually push anything.
+    '''
+    run_states = hook_config.get('states', ['start', 'finish', 'fail'])
+
+    if state.name.lower() not in run_states:
+        return
+
+    dry_run_label = ' (dry run; not actually pushing)' if dry_run else ''
+    status = 'down' if state.name.lower() == 'fail' else 'up'
+    push_url = hook_config.get('push_url', 'https://example.uptime.kuma/api/push/abcd1234')
+    query = f'status={status}&msg={state.name.lower()}'
+    logger.info(
+        f'{config_filename}: Pushing Uptime Kuma push_url {push_url}?{query} {dry_run_label}'
+    )
+    logger.debug(f'{config_filename}: Full Uptime Kuma state URL {push_url}?{query}')
+
+    if dry_run:
+        return
+
+    logging.getLogger('urllib3').setLevel(logging.ERROR)
+
+    try:
+        response = requests.get(f'{push_url}?{query}')
+        if not response.ok:
+            response.raise_for_status()
+    except requests.exceptions.RequestException as error:
+        logger.warning(f'{config_filename}: Uptime Kuma error: {error}')
+
+
+def destroy_monitor(
+    push_url_or_uuid, config, config_filename, monitoring_log_level, dry_run
+):  # pragma: no cover
+    '''
+    No destruction is necessary for this monitor.
+    '''
+    pass

borgmatic/logger.py

@@ -41,8 +41,7 @@ def should_do_markup(no_color, configs):
     if any(config.get('output', {}).get('color') is False for config in configs.values()):
         return False
 
-    no_color_env = os.environ.get('NO_COLOR', None)
-    if no_color_env is not None:
+    if os.environ.get('NO_COLOR', None):
         return False
 
     py_colors = os.environ.get('PY_COLORS', None)
@@ -89,6 +88,11 @@ class Multi_stream_handler(logging.Handler):
             handler.setLevel(level)
 
 
+class Console_no_color_formatter(logging.Formatter):
+    def format(self, record):  # pragma: no cover
+        return record.msg
+
+
 class Console_color_formatter(logging.Formatter):
     def format(self, record):
         add_custom_log_levels()
@@ -199,6 +203,8 @@ def configure_logging(
 
     if color_enabled:
         console_handler.setFormatter(Console_color_formatter())
+    else:
+        console_handler.setFormatter(Console_no_color_formatter())
 
     console_handler.setLevel(console_log_level)
 

docs/Dockerfile

@@ -4,7 +4,7 @@ COPY . /app
 RUN apk add --no-cache py3-pip py3-ruamel.yaml py3-ruamel.yaml.clib
 RUN pip install --no-cache /app && generate-borgmatic-config && chmod +r /etc/borgmatic/config.yaml
 RUN borgmatic --help > /command-line.txt \
-    && for action in rcreate transfer create prune compact check extract config "config bootstrap" "config generate" "config validate" export-tar mount umount restore rlist list rinfo info break-lock borg; do \
+    && for action in rcreate transfer create prune compact check delete extract config "config bootstrap" "config generate" "config validate" export-tar mount umount rdelete restore rlist list rinfo info break-lock borg; do \
            echo -e "\n--------------------------------------------------------------------------------\n" >> /command-line.txt \
            && borgmatic $action --help >> /command-line.txt; done
 

docs/_includes/index.css

@@ -167,12 +167,11 @@ li {
 	padding: .25em 0;
 }
 li ul {
-	margin: .5em 0;
-	padding-left: 1em;
+        list-style-type: disc;
+        padding-left: 2em;
 }
-li li {
-	padding-top: .1em;
-	padding-bottom: .1em;
+li li:last-child {
+	padding-bottom: 0em;
 }
 
 /* Syntax highlighting and Code blocks */

docs/docker-compose.yaml

@@ -1,4 +1,3 @@
-version: '3'
 services:
   docs:
     image: borgmatic-docs

docs/how-to/add-preparation-and-cleanup-steps-to-backups.md

@@ -84,6 +84,9 @@ variables you can use here:
    path of the borgmatic log file, only set when the `--log-file` flag is used
  * `repository`: path of the current repository as configured in the current
    borgmatic configuration file
+ * `repository_label` <span class="minilink minilink-addedin">New in version
+   1.8.12</span>: label of the current repository as configured in the current
+   borgmatic configuration file
 
 Note that you can also interpolate in [arbitrary environment
 variables](https://torsion.org/borgmatic/docs/how-to/provide-your-passwords/).

docs/how-to/backup-your-databases.md

@@ -206,6 +206,36 @@ hooks:
 
 Alter the ports in these examples to suit your particular database system.
 
+Normally, borgmatic dumps a database by running a database dump command (e.g.
+`pg_dump`) on the host or wherever borgmatic is running, and this command
+connects to your containerized database via the given `hostname` and `port`.
+But if you don't have any database dump commands installed on your host and
+you'd rather use the commands inside your database container itself, borgmatic
+supports that too. Just configure borgmatic to `exec` into your container to
+run the dump command.
+
+For instance, if using Docker and PostgreSQL, something like this might work:
+
+```yaml
+hooks:
+    postgresql_databases:
+        - name: users
+          hostname: 127.0.0.1
+          port: 5433
+          username: postgres
+          password: trustsome1
+          pg_dump_command: docker exec my_pg_container pg_dump
+```
+
+... where `my_pg_container` is the name of your database container. In this
+example, you'd also need to set the `pg_restore_command` and `psql_command`
+options.
+
+Similar command override options are available for (some of) the other
+supported database types as well. See the [configuration
+reference](https://torsion.org/borgmatic/docs/reference/configuration/) for
+details.
+
 
 ### No source directories
 
@@ -407,19 +437,28 @@ borgmatic's own configuration file. So include your configuration file in
 backups to avoid getting caught without a way to restore a database.
 3. borgmatic does not currently support backing up or restoring multiple
 databases that share the exact same name on different hosts.
-4. Because database hooks implicitly enable the `read_special` configuration,
-any special files are excluded from backups (named pipes, block devices,
-character devices, and sockets) to prevent hanging. Try a command like `find
-/your/source/path -type b -or -type c -or -type p -or -type s` to find such
-files. Common directories to exclude are `/dev` and `/run`, but that may not
-be exhaustive. <span class="minilink minilink-addedin">New in version
-1.7.3</span> When database hooks are enabled, borgmatic automatically excludes
-special files (and symlinks to special files) that may cause Borg to hang, so
-generally you no longer need to manually exclude them. There are potential
-edge cases though in which applications on your system create new special files
-*after* borgmatic constructs its exclude list, resulting in Borg hangs. If that
-occurs, you can resort to the manual excludes described above. And to opt out
-of the auto-exclude feature entirely, explicitly set `read_special` to true.
+4. When database hooks are enabled, borgmatic instructs Borg to consume
+special files (via `--read-special`) to support database dump
+streaming—regardless of the value of your `read_special` configuration option.
+And because this can cause Borg to hang, borgmatic also automatically excludes
+special files (and symlinks to them) that Borg may get stuck on. Even so,
+there are still potential edge cases in which applications on your system
+create new special files *after* borgmatic constructs its exclude list,
+resulting in Borg hangs. If that occurs, you can resort to manually excluding
+those files. And if you explicitly set the `read-special` option to `true`,
+borgmatic will opt you out of the auto-exclude feature entirely, but will
+still instruct Borg to consume special files—you will just be on your own to
+exclude them. <span class="minilink minilink-addedin">Prior to version
+1.7.3</span>Special files were not auto-excluded, and you were responsible for
+excluding them yourself. Common directories to exclude are `/dev` and `/run`,
+but that may not be exhaustive.
+5. Database hooks also implicitly enable the `one_file_system` option, which
+means Borg won't cross filesystem boundaries when looking for files to backup.
+This is especially important when running borgmatic in a container, as
+container volumes are mounted as separate filesystems. One work-around is to
+explicitly add each mounted volume you'd like to backup to
+`source_directories` instead of relying on Borg to include them implicitly via
+a parent directory.
 
 
 ### Manual restoration

docs/how-to/customize-warnings-and-errors.md

@@ -48,7 +48,7 @@ support for [more granular exit
 codes](https://borgbackup.readthedocs.io/en/1.4-maint/usage/general.html#return-codes)
 means that you can configure borgmatic to respond to specific Borg conditions.
 See the full list of [Borg 1.4 error and warning exit
-codes](https://borgbackup.readthedocs.io/en/1.4.0b1/internals/frontends.html#message-ids).
+codes](https://borgbackup.readthedocs.io/en/1.4.0b2/internals/frontends.html#message-ids).
 The `rc:` numeric value there tells you the exit code for each.
 
 For instance, this borgmatic configuration elevates all Borg backup file

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

@@ -20,7 +20,7 @@ default action ordering was `prune`, `compact`, `create`, and `check`.
 ### A la carte actions
 
 If you find yourself wanting to customize the actions, you have some options.
-First, you can run borgmatic's `prune`, `compact`, `create`, or `check`
+First, you can run borgmatic's `create`, `prune`, `compact`, or `check`
 actions separately. For instance, the following optional actions are
 available (among others):
 
@@ -91,8 +91,9 @@ Here are the available checks from fastest to slowest:
 
  * `repository`: Checks the consistency of the repository itself.
  * `archives`: Checks all of the archives in the repository.
- * `extract`: Performs an extraction dry-run of the most recent archive.
+ * `extract`: Performs an extraction dry-run of the latest archive.
  * `data`: Verifies the data integrity of all archives contents, decrypting and decompressing all data.
+ * `spot`: Compares file counts and contents between your source files and the latest archive.
 
 Note that the `data` check is a more thorough version of the `archives` check,
 so enabling the `data` check implicitly enables the `archives` check as well.
@@ -102,6 +103,89 @@ documentation](https://borgbackup.readthedocs.io/en/stable/usage/check.html)
 for more information.
 
 
+### Spot check
+
+The various consistency checks all have trade-offs around speed and
+thoroughness, but most of them don't even look at your original source
+files—arguably one important way to ensure your backups contain the files
+you'll want to restore in the case of catastrophe (or just an accidentally
+deleted file). Because if something goes wrong with your source files, most
+consistency checks will still pass with flying colors and you won't discover
+there's a problem until you go to restore.
+
+<span class="minilink minilink-addedin">New in version 1.8.10</span> <span
+class="minilink minilink-addedin">Beta feature</span> That's where the spot
+check comes in. This check actually compares your source file counts and data
+against those in the latest archive, potentially catching problems like
+incorrect excludes, inadvertent deletes, files changed by malware, etc.
+
+However, because an exhaustive comparison of all source files against the
+latest archive might be too slow, the spot check supports *sampling* a
+percentage of your source files for the comparison, ensuring they fall within
+configured tolerances.
+
+Here's how it works. Start by installing the `xxhash` OS package if you don't
+already have it, so the spot check can run the `xxh64sum` command and
+efficiently hash files for comparison. Then add something like the following
+to your borgmatic configuration:
+
+```yaml
+checks:
+    - name: spot
+      count_tolerance_percentage: 10
+      data_sample_percentage: 1
+      data_tolerance_percentage: 0.5
+```
+
+The `count_tolerance_percentage` is the percentage delta between the source
+directories file count and the latest backup archive file count that is
+allowed before the entire consistency check fails. For instance, if the spot
+check runs and finds 100 source files on disk and 105 files in the latest
+archive, that would be within the configured 10% count tolerance and the check
+would succeed. But if there were 100 source files and 200 archive files, the
+check would fail. (100 source files and only 50 archive files would also
+fail.)
+
+The `data_sample_percentage` is the percentage of total files in the source
+directories to randomly sample and compare to their corresponding files in the
+latest backup archive. A higher value allows a more accurate check—and a
+slower one. The comparison is performed by hashing the selected source files
+and counting hashes that don't match the latest archive. For instance, if you
+have 1,000 source files and your sample percentage is 1%, then only 10 source
+files will be compared against the latest archive. These sampled files are
+selected randomly each time, so in effect the spot check is probabilistic.
+
+The `data_tolerance_percentage` is the percentage of total files in the source
+directories that can fail a spot check data comparison without failing the
+entire consistency check. The value must be lower than or equal to the
+`data_sample_percentage`, because `data_tolerance_percentage` only looks at
+at the sampled files as determined by `data_sample_percentage`.
+
+All three options are required when using the spot check. And because the
+check relies on these configured tolerances, it may not be a
+set-it-and-forget-it type of consistency check, at least until you get the
+tolerances dialed in so there are minimal false positives or negatives. It is
+recommended you run `borgmatic check` several times after configuring the spot
+check, tweaking your tolerances as needed. For certain workloads where your
+source files experience wild swings of file contents or counts, the spot check
+may not suitable at all.
+
+What if you add, delete, or change a bunch of your source files and you don't
+want the spot check to fail the next time it's run? Run `borgmatic create` to
+create a new backup, thereby allowing the next spot check to run against an
+archive that contains your recent changes.
+
+Because the spot check only looks at the most recent archive, you may not want
+to run it immediately after a `create` action (borgmatic's default behavior).
+Instead, it may make more sense to run the spot check on a separate schedule
+from `create`.
+
+As long as the spot check feature is in beta, it may be subject to breaking
+changes. But feel free to use it in production if you're okay with that
+caveat, and please [provide any
+feedback](https://torsion.org/borgmatic/#issues) you have on this feature.
+
+
 ### Check frequency
 
 <span class="minilink minilink-addedin">New in version 1.6.2</span> You can
@@ -158,6 +242,57 @@ check --force` runs `check` even if it's specified in the `skip_actions`
 option.
 
 
+### Check days
+
+<span class="minilink minilink-addedin">New in version 1.8.13</span> You can
+optionally configure checks to only run on particular days of the week. For
+instance:
+
+```yaml
+checks:
+    - name: repository
+      only_run_on:
+         - Saturday
+         - Sunday
+    - name: archives
+      only_run_on:
+         - weekday
+    - name: spot
+      only_run_on:
+         - Friday
+         - weekend
+```
+
+Each day of the week is specified in the current locale (system
+language/country settings). `weekend` and `weekday` are also accepted.
+
+Just like with `frequency`, borgmatic only makes a best effort to run checks
+on the given day of the week. For instance, if you run `borgmatic check`
+daily, then every day borgmatic will have an opportunity to determine whether
+your checks are configured to run on that day. If they are, then the checks
+run. If not, they are skipped.
+
+For instance, with the above configuration, if borgmatic is run on a Saturday,
+the `repository` check will run. But on a Monday? The repository check will
+get skipped. And if borgmatic is never run on a Saturday or a Sunday, that
+check will never get a chance to run.
+
+Also, the day of the week configuration applies *after* any configured
+`frequency` for a check. So for instance, imagine the following configuration:
+
+```yaml
+checks:
+    - name: repository
+      frequency: 2 weeks
+      only_run_on:
+         - Monday
+```
+
+If you run borgmatic daily with that configuration, then borgmatic will first
+wait two weeks after the previous check before running the check again—on the
+first Monday after the `frequency` duration elapses.
+
+
 ### Running only checks
 
 <span class="minilink minilink-addedin">New in version 1.7.1</span> If you

docs/how-to/develop-on-borgmatic.md

@@ -102,9 +102,9 @@ and depend on containers for runtime dependencies. These tests do run on the
 continuous integration (CI) server, and running them on your developer machine
 is the closest thing to dev-CI parity.
 
-If you would like to run the full test suite, first install Docker (or Podman;
-see below) and [Docker Compose](https://docs.docker.com/compose/install/).
-Then run:
+If you would like to run the end-to-end tests, first install Docker (or
+Podman; see below) and [Docker
+Compose](https://docs.docker.com/compose/install/). Then run:
 
 ```bash
 scripts/run-end-to-end-tests
@@ -152,12 +152,17 @@ the following deviations from it:
  * In general, spell out words in variable names instead of shortening them.
    So, think `index` instead of `idx`. There are some notable exceptions to
    this though (like `config`).
+ * Favor blank lines around logical code groupings, `if` statements,
+   `return`s, etc. Readability is more important than packing code tightly.
+ * Import fully qualified Python modules instead of importing individual
+   functions, classes, or constants. E.g., do `import os.path` instead of
+   `from os import path`. (Some exceptions to this are made in tests.)
 
 borgmatic code uses the [Black](https://black.readthedocs.io/en/stable/) code
 formatter, the [Flake8](http://flake8.pycqa.org/en/latest/) code checker, and
 the [isort](https://github.com/timothycrosley/isort) import orderer, so
-certain code style requirements will be enforced when running automated tests.
-See the Black, Flake8, and isort documentation for more information.
+certain code style requirements are enforced when running automated tests. See
+the Black, Flake8, and isort documentation for more information.
 
 
 ## Continuous integration

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

@@ -133,7 +133,7 @@ For Borg 1.x, use a shell pattern for the `match_archives` value and see the
 [Borg patterns
 documentation](https://borgbackup.readthedocs.io/en/stable/usage/help.html#borg-help-patterns)
 for more information. For Borg 2.x, see the [match archives
-documentation](https://borgbackup.readthedocs.io/en/2.0.0b5/usage/help.html#borg-help-match-archives).
+documentation](https://borgbackup.readthedocs.io/en/2.0.0b8/usage/help.html#borg-help-match-archives).
 
 Some borgmatic command-line actions also have a `--match-archives` flag that
 overrides both the auto-matching behavior and the `match_archives`

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

@@ -39,13 +39,14 @@ below for how to configure this.
 borgmatic integrates with these monitoring services and libraries, pinging
 them as backups happen:
 
- * [Healthchecks](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#healthchecks-hook)
- * [Cronitor](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#cronitor-hook)
- * [Cronhub](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#cronhub-hook)
- * [PagerDuty](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#pagerduty-hook)
- * [ntfy](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#ntfy-hook)
- * [Grafana Loki](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#loki-hook)
  * [Apprise](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#apprise-hook)
+ * [Cronhub](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#cronhub-hook)
+ * [Cronitor](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#cronitor-hook)
+ * [Grafana Loki](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#loki-hook)
+ * [Healthchecks](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#healthchecks-hook)
+ * [ntfy](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#ntfy-hook)
+ * [PagerDuty](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#pagerduty-hook)
+ * [Uptime Kuma](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#uptime-kuma-hook)
 
 The idea is that you'll receive an alert when something goes wrong or when the
 service doesn't hear from borgmatic for a configured interval (if supported).
@@ -208,8 +209,8 @@ cronitor:
 this option in the `hooks:` section of your configuration.
 
 With this configuration, borgmatic pings your Cronitor monitor when a backup
-begins, ends, or errors, but only when any of the `prune`, `compact`,
-`create`, or `check` actions are run. Then, if the actions complete
+begins, ends, or errors, but only when any of the `create`, `prune`,
+`compact`, or `check` actions are run. Then, if the actions complete
 successfully or errors, borgmatic notifies Cronitor accordingly.
 
 You can configure Cronitor to notify you by a [variety of
@@ -235,8 +236,8 @@ cronhub:
 this option in the `hooks:` section of your configuration.
 
 With this configuration, borgmatic pings your Cronhub monitor when a backup
-begins, ends, or errors, but only when any of the `prune`, `compact`,
-`create`, or `check` actions are run. Then, if the actions complete
+begins, ends, or errors, but only when any of the `create`, `prune`,
+`compact`, or `check` actions are run. Then, if the actions complete
 successfully or errors, borgmatic notifies Cronhub accordingly.
 
 Note that even though you configure borgmatic with the "start" variant of the
@@ -368,7 +369,7 @@ loki:
 ```
 
 With this configuration, borgmatic sends its logs to your Loki instance as any
-of the `prune`, `compact`, `create`, or `check` actions are run. Then, after
+of the `create`, `prune`, `compact`, or `check` actions are run. Then, after
 the actions complete, borgmatic notifies Loki of success or failure.
 
 This hook supports sending arbitrary labels to Loki. For instance:
@@ -401,6 +402,10 @@ loki:
         hostname: __hostname
 ```
 
+Also check out this [Loki dashboard for
+borgmatic](https://grafana.com/grafana/dashboards/20736-borgmatic-logs/) if
+you'd like to see your backup logs and statistics in one place.
+
 
 ## Apprise hook
 
@@ -416,7 +421,8 @@ pipx](https://torsion.org/borgmatic/docs/how-to/set-up-backups/#installation),
 run the following to install Apprise so borgmatic can use it:
 
 ```bash
-sudo pipx install --force borgmatic[Apprise]
+sudo pipx uninstall borgmatic
+sudo pipx install borgmatic[Apprise]
 ```
 
 Omit `sudo` if borgmatic is installed as a non-root user.
@@ -431,11 +437,16 @@ apprise:
           label: gotify
         - url: mastodons://access_key@hostname/@user
           label: mastodon
+    states:
+        - start
+        - finish
+        - fail
 ```
 
 With this configuration, borgmatic pings each of the configured Apprise
 services when a backup begins, ends, or errors, but only when any of the
-`prune`, `compact`, `create`, or `check` actions are run.
+`create`, `prune`, `compact`, or `check` actions are run. (By default, if
+`states` is not specified, Apprise services are only pinged on error.)
 
 You can optionally customize the contents of the default messages sent to
 these services:
@@ -495,6 +506,62 @@ See the [configuration
 reference](https://torsion.org/borgmatic/docs/reference/configuration/) for
 details.
 
+## Uptime Kuma hook
+
+<span class="minilink minilink-addedin">New in version 1.8.13</span> [Uptime
+Kuma](https://uptime.kuma.pet) is an easy-to-use, self-hosted monitoring tool
+and can provide a Push monitor type to accept HTTP `GET` requests from a
+service instead of contacting it directly.
+
+Uptime Kuma allows you to see a history of monitor states and can in turn
+alert via ntfy, Gotify, Matrix, Apprise, Email, and many more.
+
+An example configuration is shown here with all the available options:
+
+```yaml
+uptime_kuma:
+    push_url: https://kuma.my-domain.com/api/push/abcd1234
+    states:
+        - start
+        - finish
+        - fail
+```
+
+The `push_url` is provided to your from your Uptime Kuma service and
+originally includes a query string—the text including and after the question
+mark (`?`). But please do not include the query string in the `push_url`
+configuration; borgmatic will add this automatically depending on the state of
+your backup. 
+
+Using `start`, `finish` and `fail` states means you will get two "up beats" in
+Uptime Kuma for successful backups and the ability to see failures if and when
+the backup started (was there a `start` beat?).
+
+A reasonable base-level configuration for an Uptime Kuma Monitor for a backup
+is below:
+
+```ini
+# These are to be entered into Uptime Kuma and not into your borgmatic
+# configuration.
+
+# Push monitors wait for the client to contact Uptime Kuma instead of Uptime
+# Kuma contacting the client. This is perfect for backup monitoring.
+Monitor Type = Push
+
+Heartbeat Interval = 90000     # = 25 hours = 1 day + 1 hour
+
+# Wait 6 times the Heartbeat Retry (below) before logging a heartbeat missed.
+Retries = 6
+
+# Multiplied by Retries this gives a grace period within which the monitor
+# goes into the "Pending" state.
+Heartbeat Retry = 360          # = 10 minutes
+
+# For each Heartbeat Interval if the backup fails repeatedly, a notification
+# is sent each time.
+Resend Notification every X times = 1
+```
+
 
 ## Scripting borgmatic
 

docs/how-to/run-arbitrary-borg-commands.md

@@ -133,6 +133,8 @@ borgmatic's `borg` action is not without limitations:
    borgmatic action. In this case, only the Borg command is run.
  * Unlike normal borgmatic actions that support JSON, the `borg` action will
    not disable certain borgmatic logs to avoid interfering with JSON output.
+ * The `borg` action bypasses most of borgmatic's machinery, so for instance
+   monitoring hooks will not get triggered when running `borgmatic borg create`.
  * <span class="minilink minilink-addedin">Prior to version 1.8.0</span>
    borgmatic implicitly injected the repository/archive arguments on the Borg
    command-line for you (based on your borgmatic configuration or the

docs/how-to/upgrade.md

@@ -151,7 +151,7 @@ borgmatic rcreate --verbosity 1 --encryption repokey-aes-ocb \
 ```
 
 Read about [Borg encryption
-modes](https://borgbackup.readthedocs.io/en/2.0.0b5/usage/rcreate.html#encryption-mode-tldr)
+modes](https://borgbackup.readthedocs.io/en/2.0.0b8/usage/rcreate.html#encryption-mode-tldr)
 for more details.
 
 To transfer data from your original Borg 1 repository to your newly created
@@ -174,7 +174,7 @@ confirmation of success—or tells you if something hasn't been transferred yet.
 Note that by omitting the `--upgrader` flag, you can also do archive transfers
 between related Borg 2 repositories without upgrading, even down to individual
 archives. For more on that functionality, see the [Borg transfer
-documentation](https://borgbackup.readthedocs.io/en/2.0.0b5/usage/transfer.html).
+documentation](https://borgbackup.readthedocs.io/en/2.0.0b8/usage/transfer.html).
 
 That's it! Now you can use your new Borg 2 repository as normal with
 borgmatic. If you've got multiple repositories, repeat the above process for

docs/reference/source-code.md

@@ -10,20 +10,17 @@ eleventyNavigation:
 If case you're interested in [developing on
 borgmatic](https://torsion.org/borgmatic/docs/how-to/develop-on-borgmatic/),
 here's an abridged primer on how its Python source code is organized to help
-you get started. At the top level we have:
+you get started. Starting at the top level, we have:
 
- * [borgmatic](https://projects.torsion.org/borgmatic-collective/borgmatic/src/branch/main/borgmatic): The main borgmatic source module. Most of the code is here.
+ * [borgmatic](https://projects.torsion.org/borgmatic-collective/borgmatic/src/branch/main/borgmatic): The main borgmatic source module. Most of the code is here. Within that:
+   * [actions](https://projects.torsion.org/borgmatic-collective/borgmatic/src/branch/main/borgmatic/actions): borgmatic-specific logic for running each action (create, list, check, etc.).
+   * [borg](https://projects.torsion.org/borgmatic-collective/borgmatic/src/branch/main/borgmatic/borg): Lower-level code that's responsible for interacting with Borg to run each action.
+   * [commands](https://projects.torsion.org/borgmatic-collective/borgmatic/src/branch/main/borgmatic/commands): Looking to add a new flag or action? Start here. This contains borgmatic's entry point, argument parsing, and shell completion. 
+   * [config](https://projects.torsion.org/borgmatic-collective/borgmatic/src/branch/main/borgmatic/config): Code responsible for loading, normalizing, and validating borgmatic's configuration.
+   * [hooks](https://projects.torsion.org/borgmatic-collective/borgmatic/src/branch/main/borgmatic/hooks): Looking to add a new database or monitoring integration? Start here.
  * [docs](https://projects.torsion.org/borgmatic-collective/borgmatic/src/branch/main/docs): How-to and reference documentation, including the document you're reading now.
  * [sample](https://projects.torsion.org/borgmatic-collective/borgmatic/src/branch/main/sample): Example configurations for cron and systemd.
  * [scripts](https://projects.torsion.org/borgmatic-collective/borgmatic/src/branch/main/scripts): Dev-facing scripts for things like building documentation and running end-to-end tests.
  * [tests](https://projects.torsion.org/borgmatic-collective/borgmatic/src/branch/main/tests): Automated tests organized by: end-to-end, integration, and unit.
 
-Within the `borgmatic` directory you'll find:
-
- * [actions](https://projects.torsion.org/borgmatic-collective/borgmatic/src/branch/main/borgmatic/actions): Mid-level code for running each borgmatic action (create, list, check, etc.).
- * [borg](https://projects.torsion.org/borgmatic-collective/borgmatic/src/branch/main/borgmatic/borg): Lower-level code that actually shells out to Borg for each action.
- * [commands](https://projects.torsion.org/borgmatic-collective/borgmatic/src/branch/main/borgmatic/commands): Looking to add a new flag or action? Start here. This contains borgmatic's entry point, argument parsing, and shell completion. 
- * [config](https://projects.torsion.org/borgmatic-collective/borgmatic/src/branch/main/borgmatic/config): Code responsible for loading, normalizing, and validating borgmatic's configuration.
- * [hooks](https://projects.torsion.org/borgmatic-collective/borgmatic/src/branch/main/borgmatic/hooks): Looking to add a new database or monitoring integration? Start here.
-
 So, broadly speaking, the control flow goes: `commands` → `config` followed by `commands` → `actions` → `borg` and `hooks`.

setup.py

@@ -1,6 +1,6 @@
 from setuptools import find_packages, setup
 
-VERSION = '1.8.9'
+VERSION = '1.8.13'
 
 
 setup(

test_requirements.txt

@@ -1,34 +1,34 @@
 appdirs==1.4.4
-apprise==1.3.0
-attrs==22.2.0
-black==23.3.0
-certifi==2023.7.22
-chardet==5.1.0
-click==8.1.3
-codespell==2.2.4
+apprise==1.8.0
+attrs==23.2.0
+black==24.4.2
+certifi==2024.2.2
+chardet==5.2.0
+click==8.1.7
+codespell==2.2.6
 colorama==0.4.6
-coverage==7.2.3
-flake8==6.0.0
-flake8-quotes==3.3.2
+coverage==7.5.1
+flake8==7.0.0
+flake8-quotes==3.4.0
 flake8-use-fstring==1.4
-flake8-variables-names==0.0.5
-flexmock==0.11.3
-idna==3.4
-isort==5.12.0
-jsonschema==4.17.3
-Markdown==3.4.1
+flake8-variables-names==0.0.6
+flexmock==0.12.1
+idna==3.7
+isort==5.13.2
+jsonschema==4.22.0
+Markdown==3.6
 mccabe==0.7.0
-packaging==23.1
-pathspec==0.11.1
-pluggy==1.0.0
+packaging==24.0
+pathspec==0.12.1
+pluggy==1.5.0
 py==1.11.0
-pycodestyle==2.10.0
-pyflakes==3.0.1
-pytest==7.3.0
-pytest-cov==4.0.0
+pycodestyle==2.11.1
+pyflakes==3.2.0
+pytest==8.2.1
+pytest-cov==5.0.0
 PyYAML>5.0.0
 regex
-requests==2.31.0
+requests==2.32.2
 ruamel.yaml>0.15.0
 toml==0.10.2
 typed-ast

tests/end-to-end/docker-compose.yaml

@@ -1,4 +1,3 @@
-version: '3'
 services:
   postgresql:
     image: docker.io/postgres:13.1-alpine

tests/unit/actions/test_delete.py

@@ -0,0 +1,43 @@
+from flexmock import flexmock
+
+from borgmatic.actions import delete as module
+
+
+def test_run_delete_does_not_raise():
+    flexmock(module.logger).answer = lambda message: None
+    flexmock(module.borgmatic.config.validate).should_receive('repositories_match').and_return(True)
+    flexmock(module.borgmatic.borg.rlist).should_receive('resolve_archive_name')
+    flexmock(module.borgmatic.actions.arguments).should_receive('update_arguments').and_return(
+        flexmock()
+    )
+    flexmock(module.borgmatic.borg.delete).should_receive('delete_archives')
+
+    module.run_delete(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version=None,
+        delete_arguments=flexmock(repository=flexmock(), archive=flexmock()),
+        global_arguments=flexmock(),
+        local_path=None,
+        remote_path=None,
+    )
+
+
+def test_run_delete_without_archive_does_not_raise():
+    flexmock(module.logger).answer = lambda message: None
+    flexmock(module.borgmatic.config.validate).should_receive('repositories_match').and_return(True)
+    flexmock(module.borgmatic.borg.rlist).should_receive('resolve_archive_name')
+    flexmock(module.borgmatic.actions.arguments).should_receive('update_arguments').and_return(
+        flexmock()
+    )
+    flexmock(module.borgmatic.borg.delete).should_receive('delete_archives')
+
+    module.run_delete(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version=None,
+        delete_arguments=flexmock(repository=flexmock(), archive=None),
+        global_arguments=flexmock(),
+        local_path=None,
+        remote_path=None,
+    )

tests/unit/actions/test_json.py

@@ -1,25 +1,31 @@
-from flexmock import flexmock
+import pytest
 
 from borgmatic.actions import json as module
 
 
 def test_parse_json_loads_json_from_string():
-    flexmock(module.json).should_receive('loads').and_return({'repository': {'id': 'foo'}})
-
     assert module.parse_json('{"repository": {"id": "foo"}}', label=None) == {
         'repository': {'id': 'foo', 'label': ''}
     }
 
 
-def test_parse_json_injects_label_into_parsed_data():
-    flexmock(module.json).should_receive('loads').and_return({'repository': {'id': 'foo'}})
+def test_parse_json_skips_non_json_warnings_and_loads_subsequent_json():
+    assert module.parse_json(
+        '/non/existent/path: stat: [Errno 2] No such file or directory: /non/existent/path\n{"repository":\n{"id": "foo"}}',
+        label=None,
+    ) == {'repository': {'id': 'foo', 'label': ''}}
 
+
+def test_parse_json_skips_with_invalid_json_raises():
+    with pytest.raises(module.json.JSONDecodeError):
+        module.parse_json('this is not valid JSON }', label=None)
+
+
+def test_parse_json_injects_label_into_parsed_data():
     assert module.parse_json('{"repository": {"id": "foo"}}', label='bar') == {
         'repository': {'id': 'foo', 'label': 'bar'}
     }
 
 
 def test_parse_json_injects_nothing_when_repository_missing():
-    flexmock(module.json).should_receive('loads').and_return({'stuff': {'id': 'foo'}})
-
     assert module.parse_json('{"stuff": {"id": "foo"}}', label='bar') == {'stuff': {'id': 'foo'}}

tests/unit/actions/test_rdelete.py

@@ -0,0 +1,41 @@
+from flexmock import flexmock
+
+from borgmatic.actions import rdelete as module
+
+
+def test_run_rdelete_does_not_raise():
+    flexmock(module.logger).answer = lambda message: None
+    flexmock(module.borgmatic.config.validate).should_receive('repositories_match').and_return(True)
+    flexmock(module.borgmatic.actions.arguments).should_receive('update_arguments').and_return(
+        flexmock()
+    )
+    flexmock(module.borgmatic.borg.rdelete).should_receive('delete_repository')
+
+    module.run_rdelete(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version=None,
+        rdelete_arguments=flexmock(repository=flexmock(), cache_only=False),
+        global_arguments=flexmock(),
+        local_path=None,
+        remote_path=None,
+    )
+
+
+def test_run_rdelete_with_cache_only_does_not_raise():
+    flexmock(module.logger).answer = lambda message: None
+    flexmock(module.borgmatic.config.validate).should_receive('repositories_match').and_return(True)
+    flexmock(module.borgmatic.actions.arguments).should_receive('update_arguments').and_return(
+        flexmock()
+    )
+    flexmock(module.borgmatic.borg.rdelete).should_receive('delete_repository')
+
+    module.run_rdelete(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version=None,
+        rdelete_arguments=flexmock(repository=flexmock(), cache_only=True),
+        global_arguments=flexmock(),
+        local_path=None,
+        remote_path=None,
+    )

tests/unit/borg/test_delete.py

@@ -0,0 +1,338 @@
+import logging
+
+import pytest
+from flexmock import flexmock
+
+from borgmatic.borg import delete as module
+
+from ..test_verbosity import insert_logging_mock
+
+
+def test_make_delete_command_includes_log_info():
+    insert_logging_mock(logging.INFO)
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_match_archives_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags_from_arguments').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_repository_flags').and_return(
+        ('repo',)
+    )
+
+    command = module.make_delete_command(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version='1.2.3',
+        delete_arguments=flexmock(list_archives=False, force=0, match_archives=None, archive=None),
+        global_arguments=flexmock(dry_run=False, log_json=False),
+        local_path='borg',
+        remote_path=None,
+    )
+
+    assert command == ('borg', 'delete', '--info', 'repo')
+
+
+def test_make_delete_command_includes_log_debug():
+    insert_logging_mock(logging.DEBUG)
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_match_archives_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags_from_arguments').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_repository_flags').and_return(
+        ('repo',)
+    )
+
+    command = module.make_delete_command(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version='1.2.3',
+        delete_arguments=flexmock(list_archives=False, force=0, match_archives=None, archive=None),
+        global_arguments=flexmock(dry_run=False, log_json=False),
+        local_path='borg',
+        remote_path=None,
+    )
+
+    assert command == ('borg', 'delete', '--debug', '--show-rc', 'repo')
+
+
+def test_make_delete_command_includes_dry_run():
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').with_args(
+        'dry-run', True
+    ).and_return(('--dry-run',))
+    flexmock(module.borgmatic.borg.flags).should_receive('make_match_archives_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags_from_arguments').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_repository_flags').and_return(
+        ('repo',)
+    )
+
+    command = module.make_delete_command(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version='1.2.3',
+        delete_arguments=flexmock(list_archives=False, force=0, match_archives=None, archive=None),
+        global_arguments=flexmock(dry_run=True, log_json=False),
+        local_path='borg',
+        remote_path=None,
+    )
+
+    assert command == ('borg', 'delete', '--dry-run', 'repo')
+
+
+def test_make_delete_command_includes_remote_path():
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').with_args(
+        'remote-path', 'borg1'
+    ).and_return(('--remote-path', 'borg1'))
+    flexmock(module.borgmatic.borg.flags).should_receive('make_match_archives_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags_from_arguments').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_repository_flags').and_return(
+        ('repo',)
+    )
+
+    command = module.make_delete_command(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version='1.2.3',
+        delete_arguments=flexmock(list_archives=False, force=0, match_archives=None, archive=None),
+        global_arguments=flexmock(dry_run=False, log_json=False),
+        local_path='borg',
+        remote_path='borg1',
+    )
+
+    assert command == ('borg', 'delete', '--remote-path', 'borg1', 'repo')
+
+
+def test_make_delete_command_includes_log_json():
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').with_args(
+        'log-json', True
+    ).and_return(('--log-json',))
+    flexmock(module.borgmatic.borg.flags).should_receive('make_match_archives_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags_from_arguments').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_repository_flags').and_return(
+        ('repo',)
+    )
+
+    command = module.make_delete_command(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version='1.2.3',
+        delete_arguments=flexmock(list_archives=False, force=0, match_archives=None, archive=None),
+        global_arguments=flexmock(dry_run=False, log_json=True),
+        local_path='borg',
+        remote_path=None,
+    )
+
+    assert command == ('borg', 'delete', '--log-json', 'repo')
+
+
+def test_make_delete_command_includes_lock_wait():
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').with_args(
+        'lock-wait', 5
+    ).and_return(('--lock-wait', '5'))
+    flexmock(module.borgmatic.borg.flags).should_receive('make_match_archives_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags_from_arguments').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_repository_flags').and_return(
+        ('repo',)
+    )
+
+    command = module.make_delete_command(
+        repository={'path': 'repo'},
+        config={'lock_wait': 5},
+        local_borg_version='1.2.3',
+        delete_arguments=flexmock(list_archives=False, force=0, match_archives=None, archive=None),
+        global_arguments=flexmock(dry_run=False, log_json=False),
+        local_path='borg',
+        remote_path=None,
+    )
+
+    assert command == ('borg', 'delete', '--lock-wait', '5', 'repo')
+
+
+def test_make_delete_command_includes_list():
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').with_args(
+        'list', True
+    ).and_return(('--list',))
+    flexmock(module.borgmatic.borg.flags).should_receive('make_match_archives_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags_from_arguments').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_repository_flags').and_return(
+        ('repo',)
+    )
+
+    command = module.make_delete_command(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version='1.2.3',
+        delete_arguments=flexmock(list_archives=True, force=0, match_archives=None, archive=None),
+        global_arguments=flexmock(dry_run=False, log_json=False),
+        local_path='borg',
+        remote_path=None,
+    )
+
+    assert command == ('borg', 'delete', '--list', 'repo')
+
+
+def test_make_delete_command_includes_force():
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_match_archives_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags_from_arguments').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_repository_flags').and_return(
+        ('repo',)
+    )
+
+    command = module.make_delete_command(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version='1.2.3',
+        delete_arguments=flexmock(list_archives=False, force=1, match_archives=None, archive=None),
+        global_arguments=flexmock(dry_run=False, log_json=False),
+        local_path='borg',
+        remote_path=None,
+    )
+
+    assert command == ('borg', 'delete', '--force', 'repo')
+
+
+def test_make_delete_command_includes_force_twice():
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_match_archives_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags_from_arguments').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_repository_flags').and_return(
+        ('repo',)
+    )
+
+    command = module.make_delete_command(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version='1.2.3',
+        delete_arguments=flexmock(list_archives=False, force=2, match_archives=None, archive=None),
+        global_arguments=flexmock(dry_run=False, log_json=False),
+        local_path='borg',
+        remote_path=None,
+    )
+
+    assert command == ('borg', 'delete', '--force', '--force', 'repo')
+
+
+def test_make_delete_command_includes_archive():
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_match_archives_flags').and_return(
+        ('--match-archives', 'archive')
+    )
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags_from_arguments').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_repository_flags').and_return(
+        ('repo',)
+    )
+
+    command = module.make_delete_command(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version='1.2.3',
+        delete_arguments=flexmock(
+            list_archives=False, force=0, match_archives=None, archive='archive'
+        ),
+        global_arguments=flexmock(dry_run=False, log_json=False),
+        local_path='borg',
+        remote_path=None,
+    )
+
+    assert command == ('borg', 'delete', '--match-archives', 'archive', 'repo')
+
+
+def test_make_delete_command_includes_match_archives():
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_match_archives_flags').and_return(
+        ('--match-archives', 'sh:foo*')
+    )
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags_from_arguments').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_repository_flags').and_return(
+        ('repo',)
+    )
+
+    command = module.make_delete_command(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version='1.2.3',
+        delete_arguments=flexmock(
+            list_archives=False, force=0, match_archives='sh:foo*', archive='archive'
+        ),
+        global_arguments=flexmock(dry_run=False, log_json=False),
+        local_path='borg',
+        remote_path=None,
+    )
+
+    assert command == ('borg', 'delete', '--match-archives', 'sh:foo*', 'repo')
+
+
+def test_delete_archives_with_archive_calls_borg_delete():
+    flexmock(module.borgmatic.logger).should_receive('add_custom_log_levels')
+    flexmock(module.borgmatic.borg.rdelete).should_receive('delete_repository').never()
+    flexmock(module).should_receive('make_delete_command').and_return(flexmock())
+    flexmock(module.borgmatic.borg.environment).should_receive('make_environment').and_return(
+        flexmock()
+    )
+    flexmock(module.borgmatic.execute).should_receive('execute_command').once()
+
+    module.delete_archives(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version=flexmock(),
+        delete_arguments=flexmock(archive='archive'),
+        global_arguments=flexmock(),
+    )
+
+
+def test_delete_archives_with_match_archives_calls_borg_delete():
+    flexmock(module.borgmatic.logger).should_receive('add_custom_log_levels')
+    flexmock(module.borgmatic.borg.rdelete).should_receive('delete_repository').never()
+    flexmock(module).should_receive('make_delete_command').and_return(flexmock())
+    flexmock(module.borgmatic.borg.environment).should_receive('make_environment').and_return(
+        flexmock()
+    )
+    flexmock(module.borgmatic.execute).should_receive('execute_command').once()
+
+    module.delete_archives(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version=flexmock(),
+        delete_arguments=flexmock(match_archives='sh:foo*'),
+        global_arguments=flexmock(),
+    )
+
+
+@pytest.mark.parametrize('argument_name', module.ARCHIVE_RELATED_ARGUMENT_NAMES[2:])
+def test_delete_archives_with_archive_related_argument_calls_borg_delete(argument_name):
+    flexmock(module.borgmatic.logger).should_receive('add_custom_log_levels')
+    flexmock(module.borgmatic.borg.rdelete).should_receive('delete_repository').never()
+    flexmock(module).should_receive('make_delete_command').and_return(flexmock())
+    flexmock(module.borgmatic.borg.environment).should_receive('make_environment').and_return(
+        flexmock()
+    )
+    flexmock(module.borgmatic.execute).should_receive('execute_command').once()
+
+    module.delete_archives(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version=flexmock(),
+        delete_arguments=flexmock(archive='archive', **{argument_name: 'value'}),
+        global_arguments=flexmock(),
+    )
+
+
+def test_delete_archives_without_archive_related_argument_calls_borg_rdelete():
+    flexmock(module.borgmatic.logger).should_receive('add_custom_log_levels')
+    flexmock(module.borgmatic.borg.feature).should_receive('available').and_return(True)
+    flexmock(module.borgmatic.borg.rdelete).should_receive('delete_repository').once()
+    flexmock(module).should_receive('make_delete_command').never()
+    flexmock(module.borgmatic.borg.environment).should_receive('make_environment').never()
+    flexmock(module.borgmatic.execute).should_receive('execute_command').never()
+
+    module.delete_archives(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version=flexmock(),
+        delete_arguments=flexmock(
+            list_archives=True, force=False, cache_only=False, keep_security_info=False
+        ),
+        global_arguments=flexmock(),
+    )

tests/unit/borg/test_extract.py

@@ -507,6 +507,39 @@ def test_extract_archive_calls_borg_with_strip_components_calculated_from_all():
     )
 
 
+def test_extract_archive_calls_borg_with_strip_components_calculated_from_all_with_leading_slash():
+    flexmock(module.os.path).should_receive('abspath').and_return('repo')
+    insert_execute_command_mock(
+        (
+            'borg',
+            'extract',
+            '--strip-components',
+            '2',
+            'repo::archive',
+            '/foo/bar/baz.txt',
+            '/foo/bar.txt',
+        )
+    )
+    flexmock(module.feature).should_receive('available').and_return(True)
+    flexmock(module.flags).should_receive('make_repository_archive_flags').and_return(
+        ('repo::archive',)
+    )
+    flexmock(module.borgmatic.config.validate).should_receive(
+        'normalize_repository_path'
+    ).and_return('repo')
+
+    module.extract_archive(
+        dry_run=False,
+        repository='repo',
+        archive='archive',
+        paths=['/foo/bar/baz.txt', '/foo/bar.txt'],
+        config={},
+        local_borg_version='1.2.3',
+        global_arguments=flexmock(log_json=False),
+        strip_components='all',
+    )
+
+
 def test_extract_archive_with_strip_components_all_and_no_paths_raises():
     flexmock(module.os.path).should_receive('abspath').and_return('repo')
     flexmock(module.feature).should_receive('available').and_return(True)

tests/unit/borg/test_flags.py

@@ -151,6 +151,30 @@ def test_make_repository_archive_flags_with_borg_features_joins_repository_and_a
             False,
             ('--glob-archives', '*-docs-{user}'),  # noqa: FS003
         ),
+        (
+            '*',
+            '{now}',  # noqa: FS003
+            True,
+            (),
+        ),
+        (
+            '*',
+            '{now}',  # noqa: FS003
+            False,
+            (),
+        ),
+        (
+            're:.*',
+            '{now}',  # noqa: FS003
+            True,
+            (),
+        ),
+        (
+            'sh:*',
+            '{now}',  # noqa: FS003
+            True,
+            (),
+        ),
     ),
 )
 def test_make_match_archives_flags_makes_flags_with_globs(
@@ -166,6 +190,20 @@ def test_make_match_archives_flags_makes_flags_with_globs(
     )
 
 
+def test_make_match_archives_flags_accepts_default_archive_name_format():
+    flexmock(module.feature).should_receive('available').and_return(True)
+
+    assert (
+        module.make_match_archives_flags(
+            match_archives=None,
+            archive_name_format=None,
+            local_borg_version=flexmock(),
+            default_archive_name_format='*',
+        )
+        == ()
+    )
+
+
 def test_warn_for_aggressive_archive_flags_without_archive_flags_bails():
     flexmock(module.logger).should_receive('warning').never()
 

tests/unit/borg/test_rdelete.py

@@ -0,0 +1,336 @@
+import logging
+
+from flexmock import flexmock
+
+from borgmatic.borg import rdelete as module
+
+from ..test_verbosity import insert_logging_mock
+
+
+def test_make_rdelete_command_with_feature_available_runs_borg_rdelete():
+    flexmock(module.borgmatic.borg.feature).should_receive('available').and_return(True)
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags_from_arguments').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_repository_flags').and_return(
+        ('repo',)
+    )
+
+    command = module.make_rdelete_command(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version='1.2.3',
+        rdelete_arguments=flexmock(list_archives=False, force=0),
+        global_arguments=flexmock(dry_run=False, log_json=False),
+        local_path='borg',
+        remote_path=None,
+    )
+
+    assert command == ('borg', 'rdelete', 'repo')
+
+
+def test_make_rdelete_command_without_feature_available_runs_borg_delete():
+    flexmock(module.borgmatic.borg.feature).should_receive('available').and_return(False)
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags_from_arguments').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_repository_flags').and_return(
+        ('repo',)
+    )
+
+    command = module.make_rdelete_command(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version='1.2.3',
+        rdelete_arguments=flexmock(list_archives=False, force=0),
+        global_arguments=flexmock(dry_run=False, log_json=False),
+        local_path='borg',
+        remote_path=None,
+    )
+
+    assert command == ('borg', 'delete', 'repo')
+
+
+def test_make_rdelete_command_includes_log_info():
+    insert_logging_mock(logging.INFO)
+    flexmock(module.borgmatic.borg.feature).should_receive('available').and_return(True)
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags_from_arguments').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_repository_flags').and_return(
+        ('repo',)
+    )
+
+    command = module.make_rdelete_command(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version='1.2.3',
+        rdelete_arguments=flexmock(list_archives=False, force=0),
+        global_arguments=flexmock(dry_run=False, log_json=False),
+        local_path='borg',
+        remote_path=None,
+    )
+
+    assert command == ('borg', 'rdelete', '--info', 'repo')
+
+
+def test_make_rdelete_command_includes_log_debug():
+    insert_logging_mock(logging.DEBUG)
+    flexmock(module.borgmatic.borg.feature).should_receive('available').and_return(True)
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags_from_arguments').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_repository_flags').and_return(
+        ('repo',)
+    )
+
+    command = module.make_rdelete_command(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version='1.2.3',
+        rdelete_arguments=flexmock(list_archives=False, force=0),
+        global_arguments=flexmock(dry_run=False, log_json=False),
+        local_path='borg',
+        remote_path=None,
+    )
+
+    assert command == ('borg', 'rdelete', '--debug', '--show-rc', 'repo')
+
+
+def test_make_rdelete_command_includes_dry_run():
+    flexmock(module.borgmatic.borg.feature).should_receive('available').and_return(True)
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').with_args(
+        'dry-run', True
+    ).and_return(('--dry-run',))
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags_from_arguments').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_repository_flags').and_return(
+        ('repo',)
+    )
+
+    command = module.make_rdelete_command(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version='1.2.3',
+        rdelete_arguments=flexmock(list_archives=False, force=0),
+        global_arguments=flexmock(dry_run=True, log_json=False),
+        local_path='borg',
+        remote_path=None,
+    )
+
+    assert command == ('borg', 'rdelete', '--dry-run', 'repo')
+
+
+def test_make_rdelete_command_includes_remote_path():
+    flexmock(module.borgmatic.borg.feature).should_receive('available').and_return(True)
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').with_args(
+        'remote-path', 'borg1'
+    ).and_return(('--remote-path', 'borg1'))
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags_from_arguments').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_repository_flags').and_return(
+        ('repo',)
+    )
+
+    command = module.make_rdelete_command(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version='1.2.3',
+        rdelete_arguments=flexmock(list_archives=False, force=0),
+        global_arguments=flexmock(dry_run=False, log_json=False),
+        local_path='borg',
+        remote_path='borg1',
+    )
+
+    assert command == ('borg', 'rdelete', '--remote-path', 'borg1', 'repo')
+
+
+def test_make_rdelete_command_includes_log_json():
+    flexmock(module.borgmatic.borg.feature).should_receive('available').and_return(True)
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').with_args(
+        'log-json', True
+    ).and_return(('--log-json',))
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags_from_arguments').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_repository_flags').and_return(
+        ('repo',)
+    )
+
+    command = module.make_rdelete_command(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version='1.2.3',
+        rdelete_arguments=flexmock(list_archives=False, force=0),
+        global_arguments=flexmock(dry_run=False, log_json=True),
+        local_path='borg',
+        remote_path=None,
+    )
+
+    assert command == ('borg', 'rdelete', '--log-json', 'repo')
+
+
+def test_make_rdelete_command_includes_lock_wait():
+    flexmock(module.borgmatic.borg.feature).should_receive('available').and_return(True)
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').with_args(
+        'lock-wait', 5
+    ).and_return(('--lock-wait', '5'))
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags_from_arguments').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_repository_flags').and_return(
+        ('repo',)
+    )
+
+    command = module.make_rdelete_command(
+        repository={'path': 'repo'},
+        config={'lock_wait': 5},
+        local_borg_version='1.2.3',
+        rdelete_arguments=flexmock(list_archives=False, force=0),
+        global_arguments=flexmock(dry_run=False, log_json=False),
+        local_path='borg',
+        remote_path=None,
+    )
+
+    assert command == ('borg', 'rdelete', '--lock-wait', '5', 'repo')
+
+
+def test_make_rdelete_command_includes_list():
+    flexmock(module.borgmatic.borg.feature).should_receive('available').and_return(True)
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').with_args(
+        'list', True
+    ).and_return(('--list',))
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags_from_arguments').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_repository_flags').and_return(
+        ('repo',)
+    )
+
+    command = module.make_rdelete_command(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version='1.2.3',
+        rdelete_arguments=flexmock(list_archives=True, force=0),
+        global_arguments=flexmock(dry_run=False, log_json=False),
+        local_path='borg',
+        remote_path=None,
+    )
+
+    assert command == ('borg', 'rdelete', '--list', 'repo')
+
+
+def test_make_rdelete_command_includes_force():
+    flexmock(module.borgmatic.borg.feature).should_receive('available').and_return(True)
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags_from_arguments').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_repository_flags').and_return(
+        ('repo',)
+    )
+
+    command = module.make_rdelete_command(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version='1.2.3',
+        rdelete_arguments=flexmock(list_archives=False, force=1),
+        global_arguments=flexmock(dry_run=False, log_json=False),
+        local_path='borg',
+        remote_path=None,
+    )
+
+    assert command == ('borg', 'rdelete', '--force', 'repo')
+
+
+def test_make_rdelete_command_includes_force_twice():
+    flexmock(module.borgmatic.borg.feature).should_receive('available').and_return(True)
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_flags_from_arguments').and_return(())
+    flexmock(module.borgmatic.borg.flags).should_receive('make_repository_flags').and_return(
+        ('repo',)
+    )
+
+    command = module.make_rdelete_command(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version='1.2.3',
+        rdelete_arguments=flexmock(list_archives=False, force=2),
+        global_arguments=flexmock(dry_run=False, log_json=False),
+        local_path='borg',
+        remote_path=None,
+    )
+
+    assert command == ('borg', 'rdelete', '--force', '--force', 'repo')
+
+
+def test_delete_repository_with_defaults_does_not_capture_output():
+    flexmock(module.borgmatic.logger).should_receive('add_custom_log_levels')
+    command = flexmock()
+    flexmock(module).should_receive('make_rdelete_command').and_return(command)
+    flexmock(module.borgmatic.borg.environment).should_receive('make_environment').and_return(
+        flexmock()
+    )
+    flexmock(module.borgmatic.execute).should_receive('execute_command').with_args(
+        command,
+        output_log_level=module.logging.ANSWER,
+        output_file=module.borgmatic.execute.DO_NOT_CAPTURE,
+        extra_environment=object,
+        borg_local_path='borg',
+        borg_exit_codes=None,
+    ).once()
+
+    module.delete_repository(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version=flexmock(),
+        rdelete_arguments=flexmock(force=False, cache_only=False),
+        global_arguments=flexmock(),
+        local_path='borg',
+        remote_path=None,
+    )
+
+
+def test_delete_repository_with_force_captures_output():
+    flexmock(module.borgmatic.logger).should_receive('add_custom_log_levels')
+    command = flexmock()
+    flexmock(module).should_receive('make_rdelete_command').and_return(command)
+    flexmock(module.borgmatic.borg.environment).should_receive('make_environment').and_return(
+        flexmock()
+    )
+    flexmock(module.borgmatic.execute).should_receive('execute_command').with_args(
+        command,
+        output_log_level=module.logging.ANSWER,
+        output_file=None,
+        extra_environment=object,
+        borg_local_path='borg',
+        borg_exit_codes=None,
+    ).once()
+
+    module.delete_repository(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version=flexmock(),
+        rdelete_arguments=flexmock(force=True, cache_only=False),
+        global_arguments=flexmock(),
+        local_path='borg',
+        remote_path=None,
+    )
+
+
+def test_delete_repository_with_cache_only_captures_output():
+    flexmock(module.borgmatic.logger).should_receive('add_custom_log_levels')
+    command = flexmock()
+    flexmock(module).should_receive('make_rdelete_command').and_return(command)
+    flexmock(module.borgmatic.borg.environment).should_receive('make_environment').and_return(
+        flexmock()
+    )
+    flexmock(module.borgmatic.execute).should_receive('execute_command').with_args(
+        command,
+        output_log_level=module.logging.ANSWER,
+        output_file=None,
+        extra_environment=object,
+        borg_local_path='borg',
+        borg_exit_codes=None,
+    ).once()
+
+    module.delete_repository(
+        repository={'path': 'repo'},
+        config={},
+        local_borg_version=flexmock(),
+        rdelete_arguments=flexmock(force=False, cache_only=True),
+        global_arguments=flexmock(),
+        local_path='borg',
+        remote_path=None,
+    )

tests/unit/commands/test_arguments.py

@@ -130,36 +130,175 @@ def test_parse_and_record_action_arguments_with_borg_action_consumes_arguments_a
     assert borg_parsed_arguments.options == ('list',)
 
 
+@pytest.mark.parametrize(
+    'argument, expected',
+    [
+        ('--foo', True),
+        ('foo', False),
+        (33, False),
+    ],
+)
+def test_argument_is_flag_only_for_string_starting_with_double_dash(argument, expected):
+    assert module.argument_is_flag(argument) == expected
+
+
 @pytest.mark.parametrize(
     'arguments, expected',
     [
-        # A global flag remaining from each parsed action.
+        # Ending with a valueless flag.
         (
+            ('--foo', '--bar', 33, '--baz'),
             (
-                ('--latest', 'archive', 'prune', 'extract', 'list', '--test-flag'),
-                ('--latest', 'archive', 'check', 'extract', 'list', '--test-flag'),
-                ('prune', 'check', 'list', '--test-flag'),
-                ('prune', 'check', 'extract', '--test-flag'),
+                ('--foo',),
+                ('--bar', 33),
+                ('--baz',),
             ),
-            ('--test-flag',),
         ),
-        # No global flags remaining.
+        # Ending with a flag and its corresponding value.
+        (
+            ('--foo', '--bar', 33, '--baz', '--quux', 'thing'),
+            (('--foo',), ('--bar', 33), ('--baz',), ('--quux', 'thing')),
+        ),
+        # Starting with an action name.
+        (
+            ('check', '--foo', '--bar', 33, '--baz'),
+            (
+                ('check',),
+                ('--foo',),
+                ('--bar', 33),
+                ('--baz',),
+            ),
+        ),
+        # Action name that one could mistake for a flag value.
+        (('--progress', 'list'), (('--progress',), ('list',))),
+        # No arguments.
+        ((), ()),
+    ],
+)
+def test_group_arguments_with_values_returns_flags_with_corresponding_values(arguments, expected):
+    flexmock(module).should_receive('argument_is_flag').with_args('--foo').and_return(True)
+    flexmock(module).should_receive('argument_is_flag').with_args('--bar').and_return(True)
+    flexmock(module).should_receive('argument_is_flag').with_args('--baz').and_return(True)
+    flexmock(module).should_receive('argument_is_flag').with_args('--quux').and_return(True)
+    flexmock(module).should_receive('argument_is_flag').with_args('--progress').and_return(True)
+    flexmock(module).should_receive('argument_is_flag').with_args(33).and_return(False)
+    flexmock(module).should_receive('argument_is_flag').with_args('thing').and_return(False)
+    flexmock(module).should_receive('argument_is_flag').with_args('check').and_return(False)
+    flexmock(module).should_receive('argument_is_flag').with_args('list').and_return(False)
+
+    assert module.group_arguments_with_values(arguments) == expected
+
+
+@pytest.mark.parametrize(
+    'arguments, grouped_arguments, expected',
+    [
+        # An unparsable flag remaining from each parsed action.
         (
             (
-                ('--latest', 'archive', 'prune', 'extract', 'list'),
-                ('--latest', 'archive', 'check', 'extract', 'list'),
+                ('--latest', 'archive', 'prune', 'extract', 'list', '--flag'),
+                ('--latest', 'archive', 'check', 'extract', 'list', '--flag'),
+                ('prune', 'check', 'list', '--flag'),
+                ('prune', 'check', 'extract', '--flag'),
+            ),
+            (
+                (
+                    ('--latest',),
+                    ('archive',),
+                    ('prune',),
+                    ('extract',),
+                    ('list',),
+                    ('--flag',),
+                ),
+                (
+                    ('--latest',),
+                    ('archive',),
+                    ('check',),
+                    ('extract',),
+                    ('list',),
+                    ('--flag',),
+                ),
+                (('prune',), ('check',), ('list',), ('--flag',)),
+                (('prune',), ('check',), ('extract',), ('--flag',)),
+            ),
+            ('--flag',),
+        ),
+        # No unparsable flags remaining.
+        (
+            (
+                ('--archive', 'archive', 'prune', 'extract', 'list'),
+                ('--archive', 'archive', 'check', 'extract', 'list'),
                 ('prune', 'check', 'list'),
                 ('prune', 'check', 'extract'),
             ),
+            (
+                (
+                    (
+                        '--archive',
+                        'archive',
+                    ),
+                    ('prune',),
+                    ('extract',),
+                    ('list',),
+                ),
+                (
+                    (
+                        '--archive',
+                        'archive',
+                    ),
+                    ('check',),
+                    ('extract',),
+                    ('list',),
+                ),
+                (('prune',), ('check',), ('list',)),
+                (('prune',), ('check',), ('extract',)),
+            ),
+            (),
+        ),
+        # No unparsable flags remaining, but some values in common.
+        (
+            (
+                ('--verbosity', '5', 'archive', 'prune', 'extract', 'list'),
+                ('--last', '5', 'archive', 'check', 'extract', 'list'),
+                ('prune', 'check', 'list', '--last', '5'),
+                ('prune', 'check', '--verbosity', '5', 'extract'),
+            ),
+            (
+                (('--verbosity', '5'), ('archive',), ('prune',), ('extract',), ('list',)),
+                (
+                    (
+                        '--last',
+                        '5',
+                    ),
+                    ('archive',),
+                    ('check',),
+                    ('extract',),
+                    ('list',),
+                ),
+                (('prune',), ('check',), ('list',), ('--last', '5')),
+                (
+                    ('prune',),
+                    ('check',),
+                    (
+                        '--verbosity',
+                        '5',
+                    ),
+                    ('extract',),
+                ),
+            ),
             (),
         ),
         # No flags.
-        ((), ()),
+        ((), (), ()),
     ],
 )
 def test_get_unparsable_arguments_returns_remaining_arguments_that_no_action_can_parse(
-    arguments, expected
+    arguments, grouped_arguments, expected
 ):
+    for action_arguments, grouped_action_arguments in zip(arguments, grouped_arguments):
+        flexmock(module).should_receive('group_arguments_with_values').with_args(
+            action_arguments
+        ).and_return(grouped_action_arguments)
+
     assert module.get_unparsable_arguments(arguments) == expected
 
 

tests/unit/commands/test_borgmatic.py

@@ -61,7 +61,7 @@ def test_run_configuration_with_invalid_borg_version_errors():
     flexmock(module.command).should_receive('execute_hook').never()
     flexmock(module.dispatch).should_receive('call_hooks').never()
     flexmock(module).should_receive('run_actions').never()
-    config = {'repositories': ['foo']}
+    config = {'repositories': [{'path': 'foo'}]}
     arguments = {'global': flexmock(monitoring_verbosity=1, dry_run=False), 'prune': flexmock()}
 
     list(module.run_configuration('test.yaml', config, ['/tmp/test.yaml'], arguments))
@@ -77,7 +77,7 @@ def test_run_configuration_logs_monitor_start_error():
     expected_results = [flexmock()]
     flexmock(module).should_receive('log_error_records').and_return(expected_results)
     flexmock(module).should_receive('run_actions').never()
-    config = {'repositories': ['foo']}
+    config = {'repositories': [{'path': 'foo'}]}
     arguments = {'global': flexmock(monitoring_verbosity=1, dry_run=False), 'create': flexmock()}
 
     results = list(module.run_configuration('test.yaml', config, ['/tmp/test.yaml'], arguments))
@@ -93,7 +93,7 @@ def test_run_configuration_bails_for_monitor_start_soft_failure():
     flexmock(module.dispatch).should_receive('call_hooks').and_raise(error)
     flexmock(module).should_receive('log_error_records').never()
     flexmock(module).should_receive('run_actions').never()
-    config = {'repositories': ['foo']}
+    config = {'repositories': [{'path': 'foo'}]}
     arguments = {'global': flexmock(monitoring_verbosity=1, dry_run=False), 'create': flexmock()}
 
     results = list(module.run_configuration('test.yaml', config, ['/tmp/test.yaml'], arguments))
@@ -118,11 +118,11 @@ def test_run_configuration_logs_actions_error():
     assert results == expected_results
 
 
-def test_run_configuration_bails_for_actions_soft_failure():
+def test_run_configuration_skips_remaining_actions_for_actions_soft_failure_but_still_pings_monitor():
     flexmock(module).should_receive('verbosity_to_log_level').and_return(logging.INFO)
     flexmock(module).should_receive('get_skip_actions').and_return([])
     flexmock(module.borg_version).should_receive('local_borg_version').and_return(flexmock())
-    flexmock(module.dispatch).should_receive('call_hooks')
+    flexmock(module.dispatch).should_receive('call_hooks').times(5)
     error = subprocess.CalledProcessError(borgmatic.hooks.command.SOFT_FAIL_EXIT_CODE, 'try again')
     flexmock(module).should_receive('run_actions').and_raise(error)
     flexmock(module).should_receive('log_error_records').never()
@@ -153,14 +153,14 @@ def test_run_configuration_logs_monitor_log_error():
     assert results == expected_results
 
 
-def test_run_configuration_bails_for_monitor_log_soft_failure():
+def test_run_configuration_still_pings_monitor_for_monitor_log_soft_failure():
     flexmock(module).should_receive('verbosity_to_log_level').and_return(logging.INFO)
     flexmock(module).should_receive('get_skip_actions').and_return([])
     flexmock(module.borg_version).should_receive('local_borg_version').and_return(flexmock())
     error = subprocess.CalledProcessError(borgmatic.hooks.command.SOFT_FAIL_EXIT_CODE, 'try again')
     flexmock(module.dispatch).should_receive('call_hooks').and_return(None).and_return(
         None
-    ).and_raise(error)
+    ).and_raise(error).and_return(None).and_return(None).times(5)
     flexmock(module).should_receive('log_error_records').never()
     flexmock(module).should_receive('run_actions').and_return([])
     flexmock(module.command).should_receive('considered_soft_failure').and_return(True)
@@ -259,7 +259,7 @@ def test_run_configuration_bails_for_on_error_hook_soft_failure():
 
 
 def test_run_configuration_retries_soft_error():
-    # Run action first fails, second passes
+    # Run action first fails, second passes.
     flexmock(module).should_receive('verbosity_to_log_level').and_return(logging.INFO)
     flexmock(module).should_receive('get_skip_actions').and_return([])
     flexmock(module.borg_version).should_receive('local_borg_version').and_return(flexmock())
@@ -273,7 +273,7 @@ def test_run_configuration_retries_soft_error():
 
 
 def test_run_configuration_retries_hard_error():
-    # Run action fails twice
+    # Run action fails twice.
     flexmock(module).should_receive('verbosity_to_log_level').and_return(logging.INFO)
     flexmock(module).should_receive('get_skip_actions').and_return([])
     flexmock(module.borg_version).should_receive('local_borg_version').and_return(flexmock())
@@ -487,6 +487,45 @@ def test_run_actions_runs_rcreate():
     )
 
 
+def test_run_actions_adds_label_file_to_hook_context():
+    flexmock(module).should_receive('add_custom_log_levels')
+    flexmock(module).should_receive('get_skip_actions').and_return([])
+    flexmock(module.command).should_receive('execute_hook')
+    expected = flexmock()
+    flexmock(borgmatic.actions.create).should_receive('run_create').with_args(
+        config_filename=object,
+        repository={'path': 'repo', 'label': 'my repo'},
+        config={'repositories': []},
+        config_paths=[],
+        hook_context={
+            'repository_label': 'my repo',
+            'log_file': '',
+            'repositories': '',
+            'repository': 'repo',
+        },
+        local_borg_version=object,
+        create_arguments=object,
+        global_arguments=object,
+        dry_run_label='',
+        local_path=object,
+        remote_path=object,
+    ).once().and_return(expected)
+
+    result = tuple(
+        module.run_actions(
+            arguments={'global': flexmock(dry_run=False, log_file=None), 'create': flexmock()},
+            config_filename=flexmock(),
+            config={'repositories': []},
+            config_paths=[],
+            local_path=flexmock(),
+            remote_path=flexmock(),
+            local_borg_version=flexmock(),
+            repository={'path': 'repo', 'label': 'my repo'},
+        )
+    )
+    assert result == (expected,)
+
+
 def test_run_actions_adds_log_file_to_hook_context():
     flexmock(module).should_receive('add_custom_log_levels')
     flexmock(module).should_receive('get_skip_actions').and_return([])
@@ -497,7 +536,12 @@ def test_run_actions_adds_log_file_to_hook_context():
         repository={'path': 'repo'},
         config={'repositories': []},
         config_paths=[],
-        hook_context={'repository': 'repo', 'repositories': '', 'log_file': 'foo'},
+        hook_context={
+            'repository_label': '',
+            'log_file': 'foo',
+            'repositories': '',
+            'repository': 'repo',
+        },
         local_borg_version=object,
         create_arguments=object,
         global_arguments=object,
@@ -934,6 +978,46 @@ def test_run_actions_runs_export_key():
     )
 
 
+def test_run_actions_runs_delete():
+    flexmock(module).should_receive('add_custom_log_levels')
+    flexmock(module).should_receive('get_skip_actions').and_return([])
+    flexmock(module.command).should_receive('execute_hook')
+    flexmock(borgmatic.actions.delete).should_receive('run_delete').once()
+
+    tuple(
+        module.run_actions(
+            arguments={'global': flexmock(dry_run=False, log_file='foo'), 'delete': flexmock()},
+            config_filename=flexmock(),
+            config={'repositories': []},
+            config_paths=[],
+            local_path=flexmock(),
+            remote_path=flexmock(),
+            local_borg_version=flexmock(),
+            repository={'path': 'repo'},
+        )
+    )
+
+
+def test_run_actions_runs_rdelete():
+    flexmock(module).should_receive('add_custom_log_levels')
+    flexmock(module).should_receive('get_skip_actions').and_return([])
+    flexmock(module.command).should_receive('execute_hook')
+    flexmock(borgmatic.actions.rdelete).should_receive('run_rdelete').once()
+
+    tuple(
+        module.run_actions(
+            arguments={'global': flexmock(dry_run=False, log_file='foo'), 'rdelete': flexmock()},
+            config_filename=flexmock(),
+            config={'repositories': []},
+            config_paths=[],
+            local_path=flexmock(),
+            remote_path=flexmock(),
+            local_borg_version=flexmock(),
+            repository={'path': 'repo'},
+        )
+    )
+
+
 def test_run_actions_runs_borg():
     flexmock(module).should_receive('add_custom_log_levels')
     flexmock(module).should_receive('get_skip_actions').and_return([])

tests/unit/config/test_constants.py

@@ -50,6 +50,16 @@ def test_apply_constants_with_empty_constants_passes_through_value():
         ({'before_backup': '{inject}'}, {'before_backup': "'echo hi; naughty-command'"}),
         ({'after_backup': '{inject}'}, {'after_backup': "'echo hi; naughty-command'"}),
         ({'on_error': '{inject}'}, {'on_error': "'echo hi; naughty-command'"}),
+        (
+            {
+                'before_backup': '{env_pass}',
+                'postgresql_databases': [{'name': 'users', 'password': '{env_pass}'}],
+            },
+            {
+                'before_backup': "'${PASS}'",
+                'postgresql_databases': [{'name': 'users', 'password': '${PASS}'}],
+            },
+        ),
         (3, 3),
         (True, True),
         (False, False),
@@ -63,6 +73,7 @@ def test_apply_constants_makes_string_substitutions(value, expected_value):
         'int': 3,
         'bool': True,
         'inject': 'echo hi; naughty-command',
+        'env_pass': '${PASS}',
     }
 
     assert module.apply_constants(value, constants) == expected_value

tests/unit/config/test_generate.py

@@ -6,9 +6,48 @@ from flexmock import flexmock
 from borgmatic.config import generate as module
 
 
+def test_get_properties_with_simple_object():
+    schema = {
+        'type': 'object',
+        'properties': OrderedDict(
+            [
+                ('field1', {'example': 'Example'}),
+            ]
+        ),
+    }
+
+    assert module.get_properties(schema) == schema['properties']
+
+
+def test_get_properties_merges_one_of_list_properties():
+    schema = {
+        'type': 'object',
+        'oneOf': [
+            {
+                'properties': OrderedDict(
+                    [
+                        ('field1', {'example': 'Example 1'}),
+                        ('field2', {'example': 'Example 2'}),
+                    ]
+                ),
+            },
+            {
+                'properties': OrderedDict(
+                    [
+                        ('field2', {'example': 'Example 2'}),
+                        ('field3', {'example': 'Example 3'}),
+                    ]
+                ),
+            },
+        ],
+    }
+
+    assert module.get_properties(schema) == dict(
+        schema['oneOf'][0]['properties'], **schema['oneOf'][1]['properties']
+    )
+
+
 def test_schema_to_sample_configuration_generates_config_map_with_examples():
-    flexmock(module.ruamel.yaml.comments).should_receive('CommentedMap').replace_with(OrderedDict)
-    flexmock(module).should_receive('add_comments_to_configuration_object')
     schema = {
         'type': 'object',
         'properties': OrderedDict(
@@ -19,6 +58,9 @@ def test_schema_to_sample_configuration_generates_config_map_with_examples():
             ]
         ),
     }
+    flexmock(module).should_receive('get_properties').and_return(schema['properties'])
+    flexmock(module.ruamel.yaml.comments).should_receive('CommentedMap').replace_with(OrderedDict)
+    flexmock(module).should_receive('add_comments_to_configuration_object')
 
     config = module.schema_to_sample_configuration(schema)
 
@@ -42,9 +84,6 @@ def test_schema_to_sample_configuration_generates_config_sequence_of_strings_wit
 
 
 def test_schema_to_sample_configuration_generates_config_sequence_of_maps_with_examples():
-    flexmock(module.ruamel.yaml.comments).should_receive('CommentedSeq').replace_with(list)
-    flexmock(module).should_receive('add_comments_to_configuration_sequence')
-    flexmock(module).should_receive('add_comments_to_configuration_object')
     schema = {
         'type': 'array',
         'items': {
@@ -54,6 +93,10 @@ def test_schema_to_sample_configuration_generates_config_sequence_of_maps_with_e
             ),
         },
     }
+    flexmock(module).should_receive('get_properties').and_return(schema['items']['properties'])
+    flexmock(module.ruamel.yaml.comments).should_receive('CommentedSeq').replace_with(list)
+    flexmock(module).should_receive('add_comments_to_configuration_sequence')
+    flexmock(module).should_receive('add_comments_to_configuration_object')
 
     config = module.schema_to_sample_configuration(schema)
 

tests/unit/hooks/test_healthchecks.py

@@ -264,6 +264,75 @@ def test_ping_monitor_hits_ping_url_when_states_matching():
     )
 
 
+def test_ping_monitor_adds_create_query_parameter_when_create_slug_true():
+    flexmock(module.borgmatic.hooks.logs).should_receive('Forgetful_buffering_handler').never()
+    hook_config = {'ping_url': 'https://example.com', 'create_slug': True}
+    flexmock(module.requests).should_receive('post').with_args(
+        'https://example.com/start?create=1', data=''.encode('utf-8'), verify=True
+    ).and_return(flexmock(ok=True))
+
+    module.ping_monitor(
+        hook_config,
+        {},
+        'config.yaml',
+        state=module.monitor.State.START,
+        monitoring_log_level=1,
+        dry_run=False,
+    )
+
+
+def test_ping_monitor_does_not_add_create_query_parameter_when_create_slug_false():
+    flexmock(module.borgmatic.hooks.logs).should_receive('Forgetful_buffering_handler').never()
+    hook_config = {'ping_url': 'https://example.com', 'create_slug': False}
+    flexmock(module.requests).should_receive('post').with_args(
+        'https://example.com/start', data=''.encode('utf-8'), verify=True
+    ).and_return(flexmock(ok=True))
+
+    module.ping_monitor(
+        hook_config,
+        {},
+        'config.yaml',
+        state=module.monitor.State.START,
+        monitoring_log_level=1,
+        dry_run=False,
+    )
+
+
+def test_ping_monitor_does_not_add_create_query_parameter_when_ping_url_is_uuid():
+    hook_config = {'ping_url': 'b3611b24-df9c-4d36-9203-fa292820bf2a', 'create_slug': True}
+    flexmock(module.requests).should_receive('post').with_args(
+        f"https://hc-ping.com/{hook_config['ping_url']}",
+        data=''.encode('utf-8'),
+        verify=True,
+    ).and_return(flexmock(ok=True))
+
+    module.ping_monitor(
+        hook_config,
+        {},
+        'config.yaml',
+        state=module.monitor.State.FINISH,
+        monitoring_log_level=1,
+        dry_run=False,
+    )
+
+
+def test_ping_monitor_issues_warning_when_ping_url_is_uuid_and_create_slug_true():
+    hook_config = {'ping_url': 'b3611b24-df9c-4d36-9203-fa292820bf2a', 'create_slug': True}
+
+    flexmock(module.requests).should_receive('post').and_return(flexmock(ok=True))
+
+    flexmock(module.logger).should_receive('warning').once()
+
+    module.ping_monitor(
+        hook_config,
+        {},
+        'config.yaml',
+        state=module.monitor.State.FINISH,
+        monitoring_log_level=1,
+        dry_run=False,
+    )
+
+
 def test_ping_monitor_with_connection_error_logs_warning():
     flexmock(module.borgmatic.hooks.logs).should_receive('Forgetful_buffering_handler').never()
     hook_config = {'ping_url': 'https://example.com'}

tests/unit/hooks/test_mariadb.py

@@ -44,6 +44,16 @@ def test_database_names_to_dump_queries_mariadb_for_database_names():
     assert names == ('foo', 'bar')
 
 
+def test_use_streaming_true_for_any_databases():
+    assert module.use_streaming(
+        databases=[flexmock(), flexmock()], config=flexmock(), log_prefix=flexmock()
+    )
+
+
+def test_use_streaming_false_for_no_databases():
+    assert not module.use_streaming(databases=[], config=flexmock(), log_prefix=flexmock())
+
+
 def test_dump_data_sources_dumps_each_database():
     databases = [{'name': 'foo'}, {'name': 'bar'}]
     processes = [flexmock(), flexmock()]

tests/unit/hooks/test_mongodb.py

@@ -5,6 +5,26 @@ from flexmock import flexmock
 from borgmatic.hooks import mongodb as module
 
 
+def test_use_streaming_true_for_any_non_directory_format_databases():
+    assert module.use_streaming(
+        databases=[{'format': 'stuff'}, {'format': 'directory'}, {}],
+        config=flexmock(),
+        log_prefix=flexmock(),
+    )
+
+
+def test_use_streaming_false_for_all_directory_format_databases():
+    assert not module.use_streaming(
+        databases=[{'format': 'directory'}, {'format': 'directory'}],
+        config=flexmock(),
+        log_prefix=flexmock(),
+    )
+
+
+def test_use_streaming_false_for_no_databases():
+    assert not module.use_streaming(databases=[], config=flexmock(), log_prefix=flexmock())
+
+
 def test_dump_data_sources_runs_mongodump_for_each_database():
     databases = [{'name': 'foo'}, {'name': 'bar'}]
     processes = [flexmock(), flexmock()]

tests/unit/hooks/test_mysql.py

@@ -44,6 +44,16 @@ def test_database_names_to_dump_queries_mysql_for_database_names():
     assert names == ('foo', 'bar')
 
 
+def test_use_streaming_true_for_any_databases():
+    assert module.use_streaming(
+        databases=[flexmock(), flexmock()], config=flexmock(), log_prefix=flexmock()
+    )
+
+
+def test_use_streaming_false_for_no_databases():
+    assert not module.use_streaming(databases=[], config=flexmock(), log_prefix=flexmock())
+
+
 def test_dump_data_sources_dumps_each_database():
     databases = [{'name': 'foo'}, {'name': 'bar'}]
     processes = [flexmock(), flexmock()]

tests/unit/hooks/test_postgresql.py

@@ -199,6 +199,26 @@ def test_database_names_to_dump_with_all_and_psql_command_uses_custom_command():
     )
 
 
+def test_use_streaming_true_for_any_non_directory_format_databases():
+    assert module.use_streaming(
+        databases=[{'format': 'stuff'}, {'format': 'directory'}, {}],
+        config=flexmock(),
+        log_prefix=flexmock(),
+    )
+
+
+def test_use_streaming_false_for_all_directory_format_databases():
+    assert not module.use_streaming(
+        databases=[{'format': 'directory'}, {'format': 'directory'}],
+        config=flexmock(),
+        log_prefix=flexmock(),
+    )
+
+
+def test_use_streaming_false_for_no_databases():
+    assert not module.use_streaming(databases=[], config=flexmock(), log_prefix=flexmock())
+
+
 def test_dump_data_sources_runs_pg_dump_for_each_database():
     databases = [{'name': 'foo'}, {'name': 'bar'}]
     processes = [flexmock(), flexmock()]

tests/unit/hooks/test_sqlite.py

@@ -5,6 +5,16 @@ from flexmock import flexmock
 from borgmatic.hooks import sqlite as module
 
 
+def test_use_streaming_true_for_any_databases():
+    assert module.use_streaming(
+        databases=[flexmock(), flexmock()], config=flexmock(), log_prefix=flexmock()
+    )
+
+
+def test_use_streaming_false_for_no_databases():
+    assert not module.use_streaming(databases=[], config=flexmock(), log_prefix=flexmock())
+
+
 def test_dump_data_sources_logs_and_skips_if_dump_already_exists():
     databases = [{'path': '/path/to/database', 'name': 'database'}]
 

tests/unit/hooks/test_uptimekuma.py

@@ -0,0 +1,165 @@
+from flexmock import flexmock
+
+import borgmatic.hooks.monitor
+from borgmatic.hooks import uptimekuma as module
+
+DEFAULT_PUSH_URL = 'https://example.uptime.kuma/api/push/abcd1234'
+CUSTOM_PUSH_URL = 'https://uptime.example.com/api/push/efgh5678'
+
+
+def test_ping_monitor_hits_default_uptimekuma_on_fail():
+    hook_config = {}
+    flexmock(module.requests).should_receive('get').with_args(
+        f'{DEFAULT_PUSH_URL}?status=down&msg=fail'
+    ).and_return(flexmock(ok=True)).once()
+
+    module.ping_monitor(
+        hook_config,
+        {},
+        'config.yaml',
+        borgmatic.hooks.monitor.State.FAIL,
+        monitoring_log_level=1,
+        dry_run=False,
+    )
+
+
+def test_ping_monitor_hits_custom_uptimekuma_on_fail():
+    hook_config = {'push_url': CUSTOM_PUSH_URL}
+    flexmock(module.requests).should_receive('get').with_args(
+        f'{CUSTOM_PUSH_URL}?status=down&msg=fail'
+    ).and_return(flexmock(ok=True)).once()
+
+    module.ping_monitor(
+        hook_config,
+        {},
+        'config.yaml',
+        borgmatic.hooks.monitor.State.FAIL,
+        monitoring_log_level=1,
+        dry_run=False,
+    )
+
+
+def test_ping_monitor_custom_uptimekuma_on_start():
+    hook_config = {'push_url': CUSTOM_PUSH_URL}
+    flexmock(module.requests).should_receive('get').with_args(
+        f'{CUSTOM_PUSH_URL}?status=up&msg=start'
+    ).and_return(flexmock(ok=True)).once()
+
+    module.ping_monitor(
+        hook_config,
+        {},
+        'config.yaml',
+        borgmatic.hooks.monitor.State.START,
+        monitoring_log_level=1,
+        dry_run=False,
+    )
+
+
+def test_ping_monitor_custom_uptimekuma_on_finish():
+    hook_config = {'push_url': CUSTOM_PUSH_URL}
+    flexmock(module.requests).should_receive('get').with_args(
+        f'{CUSTOM_PUSH_URL}?status=up&msg=finish'
+    ).and_return(flexmock(ok=True)).once()
+
+    module.ping_monitor(
+        hook_config,
+        {},
+        'config.yaml',
+        borgmatic.hooks.monitor.State.FINISH,
+        monitoring_log_level=1,
+        dry_run=False,
+    )
+
+
+def test_ping_monitor_does_not_hit_custom_uptimekuma_on_fail_dry_run():
+    hook_config = {'push_url': CUSTOM_PUSH_URL}
+    flexmock(module.requests).should_receive('get').never()
+
+    module.ping_monitor(
+        hook_config,
+        {},
+        'config.yaml',
+        borgmatic.hooks.monitor.State.FAIL,
+        monitoring_log_level=1,
+        dry_run=True,
+    )
+
+
+def test_ping_monitor_does_not_hit_custom_uptimekuma_on_start_dry_run():
+    hook_config = {'push_url': CUSTOM_PUSH_URL}
+    flexmock(module.requests).should_receive('get').never()
+
+    module.ping_monitor(
+        hook_config,
+        {},
+        'config.yaml',
+        borgmatic.hooks.monitor.State.START,
+        monitoring_log_level=1,
+        dry_run=True,
+    )
+
+
+def test_ping_monitor_does_not_hit_custom_uptimekuma_on_finish_dry_run():
+    hook_config = {'push_url': CUSTOM_PUSH_URL}
+    flexmock(module.requests).should_receive('get').never()
+
+    module.ping_monitor(
+        hook_config,
+        {},
+        'config.yaml',
+        borgmatic.hooks.monitor.State.FINISH,
+        monitoring_log_level=1,
+        dry_run=True,
+    )
+
+
+def test_ping_monitor_with_connection_error_logs_warning():
+    hook_config = {'push_url': CUSTOM_PUSH_URL}
+    flexmock(module.requests).should_receive('get').with_args(
+        f'{CUSTOM_PUSH_URL}?status=down&msg=fail'
+    ).and_raise(module.requests.exceptions.ConnectionError)
+    flexmock(module.logger).should_receive('warning').once()
+
+    module.ping_monitor(
+        hook_config,
+        {},
+        'config.yaml',
+        borgmatic.hooks.monitor.State.FAIL,
+        monitoring_log_level=1,
+        dry_run=False,
+    )
+
+
+def test_ping_monitor_with_other_error_logs_warning():
+    hook_config = {'push_url': CUSTOM_PUSH_URL}
+    response = flexmock(ok=False)
+    response.should_receive('raise_for_status').and_raise(
+        module.requests.exceptions.RequestException
+    )
+    flexmock(module.requests).should_receive('get').with_args(
+        f'{CUSTOM_PUSH_URL}?status=down&msg=fail'
+    ).and_return(response)
+    flexmock(module.logger).should_receive('warning').once()
+
+    module.ping_monitor(
+        hook_config,
+        {},
+        'config.yaml',
+        borgmatic.hooks.monitor.State.FAIL,
+        monitoring_log_level=1,
+        dry_run=False,
+    )
+
+
+def test_ping_monitor_with_invalid_run_state():
+    hook_config = {'push_url': CUSTOM_PUSH_URL}
+    flexmock(module.requests).should_receive('get').never()
+
+    module.ping_monitor(
+        hook_config,
+        {},
+        'config.yaml',
+        borgmatic.hooks.monitor.State.LOG,
+        monitoring_log_level=1,
+        dry_run=True,
+    )

tests/unit/test_execute.py

@@ -117,12 +117,37 @@ def test_append_last_lines_with_output_log_level_none_appends_captured_output():
     assert captured_output == ['captured', 'line']
 
 
+def test_mask_command_secrets_masks_password_flag_value():
+    assert module.mask_command_secrets(('cooldb', '--username', 'bob', '--password', 'pass')) == (
+        'cooldb',
+        '--username',
+        'bob',
+        '--password',
+        '***',
+    )
+
+
+def test_mask_command_secrets_passes_through_other_commands():
+    assert module.mask_command_secrets(('cooldb', '--username', 'bob')) == (
+        'cooldb',
+        '--username',
+        'bob',
+    )
+
+
 @pytest.mark.parametrize(
     'full_command,input_file,output_file,environment,expected_result',
     (
         (('foo', 'bar'), None, None, None, 'foo bar'),
         (('foo', 'bar'), flexmock(name='input'), None, None, 'foo bar < input'),
         (('foo', 'bar'), None, flexmock(name='output'), None, 'foo bar > output'),
+        (
+            ('A',) * module.MAX_LOGGED_COMMAND_LENGTH,
+            None,
+            None,
+            None,
+            'A ' * (module.MAX_LOGGED_COMMAND_LENGTH // 2 - 2) + '...',
+        ),
         (
             ('foo', 'bar'),
             flexmock(name='input'),
@@ -142,6 +167,7 @@ def test_append_last_lines_with_output_log_level_none_appends_captured_output():
 def test_log_command_logs_command_constructed_from_arguments(
     full_command, input_file, output_file, environment, expected_result
 ):
+    flexmock(module).should_receive('mask_command_secrets').replace_with(lambda command: command)
     flexmock(module.logger).should_receive('debug').with_args(expected_result).once()
 
     module.log_command(full_command, input_file, output_file, environment)

tests/unit/test_logger.py

@@ -116,7 +116,7 @@ def test_should_do_markup_prefers_PY_COLORS_to_interactive_console_value():
     )
     flexmock(module.os.environ).should_receive('get').with_args('NO_COLOR', None).and_return(None)
     flexmock(module).should_receive('to_bool').and_return(True)
-    flexmock(module).should_receive('interactive_console').and_return(False)
+    flexmock(module).should_receive('interactive_console').never()
 
     assert module.should_do_markup(no_color=False, configs={}) is True
 
@@ -124,7 +124,6 @@ def test_should_do_markup_prefers_PY_COLORS_to_interactive_console_value():
 def test_should_do_markup_prefers_NO_COLOR_to_interactive_console_value():
     flexmock(module.os.environ).should_receive('get').with_args('PY_COLORS', None).and_return(None)
     flexmock(module.os.environ).should_receive('get').with_args('NO_COLOR', None).and_return('True')
-    flexmock(module).should_receive('interactive_console').and_return(False)
 
     assert module.should_do_markup(no_color=False, configs={}) is False
 
@@ -136,6 +135,14 @@ def test_should_do_markup_respects_NO_COLOR_environment_variable():
     assert module.should_do_markup(no_color=False, configs={}) is False
 
 
+def test_should_do_markup_ignores_empty_NO_COLOR_environment_variable():
+    flexmock(module.os.environ).should_receive('get').with_args('NO_COLOR', None).and_return('')
+    flexmock(module.os.environ).should_receive('get').with_args('PY_COLORS', None).and_return(None)
+    flexmock(module).should_receive('interactive_console').and_return(True)
+
+    assert module.should_do_markup(no_color=False, configs={}) is True
+
+
 def test_should_do_markup_prefers_NO_COLOR_to_PY_COLORS():
     flexmock(module.os.environ).should_receive('get').with_args('PY_COLORS', None).and_return(
         'True'
@@ -210,10 +217,11 @@ def test_add_logging_level_skips_global_setting_if_already_set():
 def test_configure_logging_with_syslog_log_level_probes_for_log_socket_on_linux():
     flexmock(module).should_receive('add_custom_log_levels')
     flexmock(module.logging).ANSWER = module.ANSWER
+    fake_formatter = flexmock()
+    flexmock(module).should_receive('Console_color_formatter').and_return(fake_formatter)
     multi_stream_handler = flexmock(setLevel=lambda level: None, level=logging.INFO)
-    multi_stream_handler.should_receive('setFormatter').once()
+    multi_stream_handler.should_receive('setFormatter').with_args(fake_formatter).once()
     flexmock(module).should_receive('Multi_stream_handler').and_return(multi_stream_handler)
-    flexmock(module).should_receive('Console_color_formatter')
     flexmock(module).should_receive('interactive_console').and_return(False)
     flexmock(module.logging).should_receive('basicConfig').with_args(
         level=logging.DEBUG, handlers=list
@@ -230,10 +238,11 @@ def test_configure_logging_with_syslog_log_level_probes_for_log_socket_on_linux(
 def test_configure_logging_with_syslog_log_level_probes_for_log_socket_on_macos():
     flexmock(module).should_receive('add_custom_log_levels')
     flexmock(module.logging).ANSWER = module.ANSWER
+    fake_formatter = flexmock()
+    flexmock(module).should_receive('Console_color_formatter').and_return(fake_formatter)
     multi_stream_handler = flexmock(setLevel=lambda level: None, level=logging.INFO)
-    multi_stream_handler.should_receive('setFormatter').once()
+    multi_stream_handler.should_receive('setFormatter').with_args(fake_formatter).once()
     flexmock(module).should_receive('Multi_stream_handler').and_return(multi_stream_handler)
-    flexmock(module).should_receive('Console_color_formatter')
     flexmock(module).should_receive('interactive_console').and_return(False)
     flexmock(module.logging).should_receive('basicConfig').with_args(
         level=logging.DEBUG, handlers=list
@@ -251,10 +260,11 @@ def test_configure_logging_with_syslog_log_level_probes_for_log_socket_on_macos(
 def test_configure_logging_with_syslog_log_level_probes_for_log_socket_on_freebsd():
     flexmock(module).should_receive('add_custom_log_levels')
     flexmock(module.logging).ANSWER = module.ANSWER
+    fake_formatter = flexmock()
+    flexmock(module).should_receive('Console_color_formatter').and_return(fake_formatter)
     multi_stream_handler = flexmock(setLevel=lambda level: None, level=logging.INFO)
-    multi_stream_handler.should_receive('setFormatter').once()
+    multi_stream_handler.should_receive('setFormatter').with_args(fake_formatter).once()
     flexmock(module).should_receive('Multi_stream_handler').and_return(multi_stream_handler)
-    flexmock(module).should_receive('Console_color_formatter')
     flexmock(module).should_receive('interactive_console').and_return(False)
     flexmock(module.logging).should_receive('basicConfig').with_args(
         level=logging.DEBUG, handlers=list
@@ -273,10 +283,11 @@ def test_configure_logging_with_syslog_log_level_probes_for_log_socket_on_freebs
 def test_configure_logging_without_syslog_log_level_skips_syslog():
     flexmock(module).should_receive('add_custom_log_levels')
     flexmock(module.logging).ANSWER = module.ANSWER
+    fake_formatter = flexmock()
+    flexmock(module).should_receive('Console_color_formatter').and_return(fake_formatter)
     multi_stream_handler = flexmock(setLevel=lambda level: None, level=logging.INFO)
-    multi_stream_handler.should_receive('setFormatter').once()
+    multi_stream_handler.should_receive('setFormatter').with_args(fake_formatter).once()
     flexmock(module).should_receive('Multi_stream_handler').and_return(multi_stream_handler)
-    flexmock(module).should_receive('Console_color_formatter')
     flexmock(module.logging).should_receive('basicConfig').with_args(
         level=logging.INFO, handlers=list
     )
@@ -289,10 +300,11 @@ def test_configure_logging_without_syslog_log_level_skips_syslog():
 def test_configure_logging_skips_syslog_if_not_found():
     flexmock(module).should_receive('add_custom_log_levels')
     flexmock(module.logging).ANSWER = module.ANSWER
+    fake_formatter = flexmock()
+    flexmock(module).should_receive('Console_color_formatter').and_return(fake_formatter)
     multi_stream_handler = flexmock(setLevel=lambda level: None, level=logging.INFO)
-    multi_stream_handler.should_receive('setFormatter').once()
+    multi_stream_handler.should_receive('setFormatter').with_args(fake_formatter).once()
     flexmock(module).should_receive('Multi_stream_handler').and_return(multi_stream_handler)
-    flexmock(module).should_receive('Console_color_formatter')
     flexmock(module.logging).should_receive('basicConfig').with_args(
         level=logging.INFO, handlers=list
     )
@@ -305,8 +317,10 @@ def test_configure_logging_skips_syslog_if_not_found():
 def test_configure_logging_skips_log_file_if_log_file_logging_is_disabled():
     flexmock(module).should_receive('add_custom_log_levels')
     flexmock(module.logging).DISABLED = module.DISABLED
+    fake_formatter = flexmock()
+    flexmock(module).should_receive('Console_color_formatter').and_return(fake_formatter)
     multi_stream_handler = flexmock(setLevel=lambda level: None, level=logging.INFO)
-    multi_stream_handler.should_receive('setFormatter').once()
+    multi_stream_handler.should_receive('setFormatter').with_args(fake_formatter).once()
     flexmock(module).should_receive('Multi_stream_handler').and_return(multi_stream_handler)
 
     flexmock(module.logging).should_receive('basicConfig').with_args(
@@ -324,8 +338,10 @@ def test_configure_logging_skips_log_file_if_log_file_logging_is_disabled():
 def test_configure_logging_to_log_file_instead_of_syslog():
     flexmock(module).should_receive('add_custom_log_levels')
     flexmock(module.logging).ANSWER = module.ANSWER
+    fake_formatter = flexmock()
+    flexmock(module).should_receive('Console_color_formatter').and_return(fake_formatter)
     multi_stream_handler = flexmock(setLevel=lambda level: None, level=logging.INFO)
-    multi_stream_handler.should_receive('setFormatter').once()
+    multi_stream_handler.should_receive('setFormatter').with_args(fake_formatter).once()
     flexmock(module).should_receive('Multi_stream_handler').and_return(multi_stream_handler)
 
     flexmock(module.logging).should_receive('basicConfig').with_args(
@@ -349,8 +365,10 @@ def test_configure_logging_to_log_file_instead_of_syslog():
 def test_configure_logging_to_both_log_file_and_syslog():
     flexmock(module).should_receive('add_custom_log_levels')
     flexmock(module.logging).ANSWER = module.ANSWER
+    fake_formatter = flexmock()
+    flexmock(module).should_receive('Console_color_formatter').and_return(fake_formatter)
     multi_stream_handler = flexmock(setLevel=lambda level: None, level=logging.INFO)
-    multi_stream_handler.should_receive('setFormatter').once()
+    multi_stream_handler.should_receive('setFormatter').with_args(fake_formatter).once()
     flexmock(module).should_receive('Multi_stream_handler').and_return(multi_stream_handler)
 
     flexmock(module.logging).should_receive('basicConfig').with_args(
@@ -380,8 +398,10 @@ def test_configure_logging_to_log_file_formats_with_custom_log_format():
     flexmock(module.logging).should_receive('Formatter').with_args(
         '{message}', style='{'  # noqa: FS003
     ).once()
+    fake_formatter = flexmock()
+    flexmock(module).should_receive('Console_color_formatter').and_return(fake_formatter)
     multi_stream_handler = flexmock(setLevel=lambda level: None, level=logging.INFO)
-    multi_stream_handler.should_receive('setFormatter').once()
+    multi_stream_handler.should_receive('setFormatter').with_args(fake_formatter).once()
     flexmock(module).should_receive('Multi_stream_handler').and_return(multi_stream_handler)
 
     flexmock(module).should_receive('interactive_console').and_return(False)
@@ -406,8 +426,10 @@ def test_configure_logging_to_log_file_formats_with_custom_log_format():
 def test_configure_logging_skips_log_file_if_argument_is_none():
     flexmock(module).should_receive('add_custom_log_levels')
     flexmock(module.logging).ANSWER = module.ANSWER
+    fake_formatter = flexmock()
+    flexmock(module).should_receive('Console_color_formatter').and_return(fake_formatter)
     multi_stream_handler = flexmock(setLevel=lambda level: None, level=logging.INFO)
-    multi_stream_handler.should_receive('setFormatter').once()
+    multi_stream_handler.should_receive('setFormatter').with_args(fake_formatter).once()
     flexmock(module).should_receive('Multi_stream_handler').and_return(multi_stream_handler)
 
     flexmock(module.logging).should_receive('basicConfig').with_args(
@@ -419,11 +441,14 @@ def test_configure_logging_skips_log_file_if_argument_is_none():
     module.configure_logging(console_log_level=logging.INFO, log_file=None)
 
 
-def test_configure_logging_skips_console_color_formatter_if_color_disabled():
+def test_configure_logging_uses_console_no_color_formatter_if_color_disabled():
     flexmock(module).should_receive('add_custom_log_levels')
     flexmock(module.logging).ANSWER = module.ANSWER
+    fake_formatter = flexmock()
+    flexmock(module).should_receive('Console_color_formatter').never()
+    flexmock(module).should_receive('Console_no_color_formatter').and_return(fake_formatter)
     multi_stream_handler = flexmock(setLevel=lambda level: None, level=logging.INFO)
-    multi_stream_handler.should_receive('setFormatter').never()
+    multi_stream_handler.should_receive('setFormatter').with_args(fake_formatter).once()
     flexmock(module).should_receive('Multi_stream_handler').and_return(multi_stream_handler)
 
     flexmock(module.logging).should_receive('basicConfig').with_args(