Rephrase documentation and link to docs on exit codes feature (#798).

Reviewed-on: https://projects.torsion.org/borgmatic-collective/borgmatic/pulls/805
Reviewed-by: Dan Helfman <witten@torsion.org>

.drone.yml

@@ -93,5 +93,3 @@ trigger:
     - borgmatic-collective/borgmatic
   branch:
     - main
-  event:
-    - push

.gitea/issue_template/config.yaml

@@ -1 +1 @@
-blank_issues_enabled: false
+blank_issues_enabled: true

NEWS

@@ -1,3 +1,76 @@
+1.8.7
+ * #736: Store included configuration files within each backup archive in support of the "config
+   bootstrap" action. Previously, only top-level configuration files were stored.
+ * #798: Elevate specific Borg warnings to errors or squash errors to
+ * warnings. See the documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/customize-warnings-and-errors/
+ * #810: SECURITY: Prevent shell injection attacks within the PostgreSQL hook, the MongoDB hook, the
+   SQLite hook, the "borgmatic borg" action, and command hook variable/constant interpolation.
+ * #814: Fix a traceback when providing an invalid "--override" value for a list option.
+
+1.8.6
+ * #767: Add an "--ssh-command" flag to the "config bootstrap" action for setting a custom SSH
+   command, as no configuration is available (including the "ssh_command" option) until
+   bootstrapping completes.
+ * #794: Fix a traceback when the "repositories" option contains both strings and key/value pairs.
+ * #800: Add configured repository labels to the JSON output for all actions.
+ * #802: The "check --force" flag now runs checks even if "check" is in "skip_actions".
+ * #804: Validate the configured action names in the "skip_actions" option.
+ * #807: Stream SQLite databases directly to Borg instead of dumping to an intermediate file.
+ * When logging commands that borgmatic executes, log the environment variables that
+   borgmatic sets for those commands. (But don't log their values, since they often contain
+   passwords.)
+
+1.8.5
+ * #701: Add a "skip_actions" option to skip running particular actions, handy for append-only or
+   checkless configurations. See the documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/set-up-backups/#skipping-actions
+ * #701: Deprecate the "disabled" value for the "checks" option in favor of the new "skip_actions"
+   option.
+ * #745: Constants now apply to included configuration, not just the file doing the includes. As a
+   side effect of this change, constants no longer apply to option names and only substitute into
+   configuration values.
+ * #779: Add a "--match-archives" flag to the "check" action for selecting the archives to check,
+   overriding the existing "archive_name_format" and "match_archives" options in configuration.
+ * #779: Only parse "--override" values as complex data types when they're for options of those
+   types.
+ * #782: Fix environment variable interpolation within configured repository paths.
+ * #782: Add configuration constant overriding via the existing "--override" flag.
+ * #783: Upgrade ruamel.yaml dependency to support version 0.18.x.
+ * #784: Drop support for Python 3.7, which has been end-of-lifed.
+
+1.8.4
+ * #715: Add a monitoring hook for sending backup status to a variety of monitoring services via the
+   Apprise library. See the documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#apprise-hook
+ * #748: When an archive filter causes no matching archives for the "rlist" or "info"
+   actions, warn the user and suggest how to remove the filter.
+ * #768: Fix a traceback when an invalid command-line flag or action is used.
+ * #771: Fix normalization of deprecated sections ("location:", "storage:", "hooks:", etc.) to
+   support empty sections without erroring.
+ * #774: Disallow the "--dry-run" flag with the "borg" action, as borgmatic can't guarantee the Borg
+   command won't have side effects.
+
+1.8.3
+ * #665: BREAKING: Simplify logging logic as follows: Syslog verbosity is now disabled by
+   default, but setting the "--syslog-verbosity" flag enables it regardless of whether you're at an
+   interactive console. Additionally, "--log-file-verbosity" and "--monitoring-verbosity" now
+   default to 1 (info about steps borgmatic is taking) instead of 0. And both syslog logging and
+   file logging can be enabled simultaneously.
+ * #743: Add a monitoring hook for sending backup status and logs to Grafana Loki. See the
+   documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#loki-hook
+ * #753: When "archive_name_format" is not set, filter archives using the default archive name
+   format.
+ * #754: Fix error handling to log command output as one record per line instead of truncating
+   too-long output and swallowing the end of some Borg error messages.
+ * #757: Update documentation so "sudo borgmatic" works for pipx borgmatic installations.
+ * #761: Fix for borgmatic not stopping Borg immediately when the user presses ctrl-C.
+ * Update documentation to recommend installing/upgrading borgmatic with pipx instead of pip. See the
+   documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/set-up-backups/#installation
+   https://torsion.org/borgmatic/docs/how-to/upgrade/#upgrading-borgmatic
+
 1.8.2
  * #345: Add "key export" action to export a copy of the repository key for safekeeping in case
    the original goes missing or gets damaged.
@@ -38,10 +111,10 @@
    "check --repair".
  * When merging two configuration files, error gracefully if the two files do not adhere to the same
    format.
- * #721: Remove configuration sections ("location:", "storage:", "hooks:" etc.), while still keeping
-   deprecated support for them. Now, all options are at the same level, and you don't need to worry
-   about commenting/uncommenting section headers when you change an option (if you remove your
-   sections first).
+ * #721: Remove configuration sections ("location:", "storage:", "hooks:", etc.), while still
+   keeping deprecated support for them. Now, all options are at the same level, and you don't need
+   to worry about commenting/uncommenting section headers when you change an option (if you remove
+   your sections first).
  * #721: BREAKING: The retention prefix and the consistency prefix can no longer have different
    values (unless one is not set).
  * #721: BREAKING: The storage umask and the hooks umask can no longer have different values (unless

README.md

@@ -48,24 +48,27 @@ postgresql_databases:
     - name: users
 
 # Third-party services to notify you if backups aren't happening.
-healthchecks: https://hc-ping.com/be067061-cf96-4412-8eae-62b0c50d6a8c
+healthchecks:
+    ping_url: https://hc-ping.com/be067061-cf96-4412-8eae-62b0c50d6a8c
 ```
 
 borgmatic is powered by [Borg Backup](https://www.borgbackup.org/).
 
 ## Integrations
 
-<a href="https://www.postgresql.org/"><img src="docs/static/postgresql.png" alt="PostgreSQL" height="60px" style="margin-bottom:20px;"></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-<a href="https://www.mysql.com/"><img src="docs/static/mysql.png" alt="MySQL" height="60px" style="margin-bottom:20px;"></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-<a href="https://mariadb.com/"><img src="docs/static/mariadb.png" alt="MariaDB" height="60px" style="margin-bottom:20px;"></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-<a href="https://www.mongodb.com/"><img src="docs/static/mongodb.png" alt="MongoDB" height="60px" style="margin-bottom:20px;"></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-<a href="https://sqlite.org/"><img src="docs/static/sqlite.png" alt="SQLite" height="60px" style="margin-bottom:20px;"></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-<a href="https://healthchecks.io/"><img src="docs/static/healthchecks.png" alt="Healthchecks" height="60px" style="margin-bottom:20px;"></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-<a href="https://cronitor.io/"><img src="docs/static/cronitor.png" alt="Cronitor" height="60px" style="margin-bottom:20px;"></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-<a href="https://cronhub.io/"><img src="docs/static/cronhub.png" alt="Cronhub" height="60px" style="margin-bottom:20px;"></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-<a href="https://www.pagerduty.com/"><img src="docs/static/pagerduty.png" alt="PagerDuty" height="60px" style="margin-bottom:20px;"></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-<a href="https://ntfy.sh/"><img src="docs/static/ntfy.png" alt="ntfy" height="60px" style="margin-bottom:20px;"></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-<a href="https://www.borgbase.com/?utm_source=borgmatic"><img src="docs/static/borgbase.png" alt="BorgBase" height="60px" style="margin-bottom:20px;"></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+<a href="https://www.postgresql.org/"><img src="docs/static/postgresql.png" alt="PostgreSQL" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
+<a href="https://www.mysql.com/"><img src="docs/static/mysql.png" alt="MySQL" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
+<a href="https://mariadb.com/"><img src="docs/static/mariadb.png" alt="MariaDB" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
+<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://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>
+<a href="https://ntfy.sh/"><img src="docs/static/ntfy.png" alt="ntfy" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
+<a href="https://grafana.com/oss/loki/"><img src="docs/static/loki.png" alt="Loki" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
+<a href="https://github.com/caronc/apprise/wiki"><img src="docs/static/apprise.png" alt="Apprise" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
+<a href="https://www.borgbase.com/?utm_source=borgmatic"><img src="docs/static/borgbase.png" alt="BorgBase" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
 
 
 ## Getting started

borgmatic/actions/check.py

@@ -39,13 +39,10 @@ def run_check(
         repository['path'],
         config,
         local_borg_version,
+        check_arguments,
         global_arguments,
         local_path=local_path,
         remote_path=remote_path,
-        progress=check_arguments.progress,
-        repair=check_arguments.repair,
-        only_checks=check_arguments.only,
-        force=check_arguments.force,
     )
     borgmatic.hooks.command.execute_hook(
         config.get('after_check'),

borgmatic/actions/config/bootstrap.py

@@ -13,14 +13,11 @@ logger = logging.getLogger(__name__)
 
 def get_config_paths(bootstrap_arguments, global_arguments, local_borg_version):
     '''
-    Given:
-    The bootstrap arguments, which include the repository and archive name, borgmatic source directory,
-    destination directory, and whether to strip components.
-    The global arguments, which include the dry run flag
-    and the local borg version,
-    Return:
-    The config paths from the manifest.json file in the borgmatic source directory after extracting it from the
-    repository.
+    Given the bootstrap arguments as an argparse.Namespace (containing the repository and archive
+    name, borgmatic source directory, destination directory, and whether to strip components), the
+    global arguments as an argparse.Namespace (containing the dry run flag and the local borg
+    version), return the config paths from the manifest.json file in the borgmatic source directory
+    after extracting it from the repository.
 
     Raise ValueError if the manifest JSON is missing, can't be decoded, or doesn't contain the
     expected configuration path data.
@@ -31,24 +28,26 @@ def get_config_paths(bootstrap_arguments, global_arguments, local_borg_version):
     borgmatic_manifest_path = os.path.expanduser(
         os.path.join(borgmatic_source_directory, 'bootstrap', 'manifest.json')
     )
+    config = {'ssh_command': bootstrap_arguments.ssh_command}
+
     extract_process = borgmatic.borg.extract.extract_archive(
         global_arguments.dry_run,
         bootstrap_arguments.repository,
         borgmatic.borg.rlist.resolve_archive_name(
             bootstrap_arguments.repository,
             bootstrap_arguments.archive,
-            {},
+            config,
             local_borg_version,
             global_arguments,
         ),
         [borgmatic_manifest_path],
-        {},
+        config,
         local_borg_version,
         global_arguments,
         extract_to_stdout=True,
     )
-
     manifest_json = extract_process.stdout.read()
+
     if not manifest_json:
         raise ValueError(
             'Cannot read configuration paths from archive due to missing bootstrap manifest'
@@ -79,6 +78,7 @@ def run_bootstrap(bootstrap_arguments, global_arguments, local_borg_version):
     manifest_config_paths = get_config_paths(
         bootstrap_arguments, global_arguments, local_borg_version
     )
+    config = {'ssh_command': bootstrap_arguments.ssh_command}
 
     logger.info(f"Bootstrapping config paths: {', '.join(manifest_config_paths)}")
 
@@ -88,12 +88,12 @@ def run_bootstrap(bootstrap_arguments, global_arguments, local_borg_version):
         borgmatic.borg.rlist.resolve_archive_name(
             bootstrap_arguments.repository,
             bootstrap_arguments.archive,
-            {},
+            config,
             local_borg_version,
             global_arguments,
         ),
         [config_path.lstrip(os.path.sep) for config_path in manifest_config_paths],
-        {},
+        config,
         local_borg_version,
         global_arguments,
         extract_to_stdout=False,

borgmatic/actions/create.py

@@ -1,12 +1,9 @@
+import importlib.metadata
 import json
 import logging
 import os
 
-try:
-    import importlib_metadata
-except ModuleNotFoundError:  # pragma: nocover
-    import importlib.metadata as importlib_metadata
-
+import borgmatic.actions.json
 import borgmatic.borg.create
 import borgmatic.borg.state
 import borgmatic.config.validate
@@ -39,7 +36,7 @@ def create_borgmatic_manifest(config, config_paths, dry_run):
     with open(borgmatic_manifest_path, 'w') as config_list_file:
         json.dump(
             {
-                'borgmatic_version': importlib_metadata.version('borgmatic'),
+                'borgmatic_version': importlib.metadata.version('borgmatic'),
                 'config_paths': config_paths,
             },
             config_list_file,
@@ -50,6 +47,7 @@ def run_create(
     config_filename,
     repository,
     config,
+    config_paths,
     hook_context,
     local_borg_version,
     create_arguments,
@@ -78,22 +76,24 @@ def run_create(
     )
     logger.info(f'{repository.get("label", repository["path"])}: Creating archive{dry_run_label}')
     borgmatic.hooks.dispatch.call_hooks_even_if_unconfigured(
-        'remove_database_dumps',
+        'remove_data_source_dumps',
         config,
         repository['path'],
-        borgmatic.hooks.dump.DATABASE_HOOK_NAMES,
+        borgmatic.hooks.dump.DATA_SOURCE_HOOK_NAMES,
         global_arguments.dry_run,
     )
     active_dumps = borgmatic.hooks.dispatch.call_hooks(
-        'dump_databases',
+        'dump_data_sources',
         config,
         repository['path'],
-        borgmatic.hooks.dump.DATABASE_HOOK_NAMES,
+        borgmatic.hooks.dump.DATA_SOURCE_HOOK_NAMES,
         global_arguments.dry_run,
     )
     if config.get('store_config_files', True):
         create_borgmatic_manifest(
-            config, global_arguments.used_config_paths, global_arguments.dry_run
+            config,
+            config_paths,
+            global_arguments.dry_run,
         )
     stream_processes = [process for processes in active_dumps.values() for process in processes]
 
@@ -101,6 +101,7 @@ def run_create(
         global_arguments.dry_run,
         repository['path'],
         config,
+        config_paths,
         local_borg_version,
         global_arguments,
         local_path=local_path,
@@ -111,14 +112,14 @@ def run_create(
         list_files=create_arguments.list_files,
         stream_processes=stream_processes,
     )
-    if json_output:  # pragma: nocover
-        yield json.loads(json_output)
+    if json_output:
+        yield borgmatic.actions.json.parse_json(json_output, repository.get('label'))
 
     borgmatic.hooks.dispatch.call_hooks_even_if_unconfigured(
-        'remove_database_dumps',
+        'remove_data_source_dumps',
         config,
         config_filename,
-        borgmatic.hooks.dump.DATABASE_HOOK_NAMES,
+        borgmatic.hooks.dump.DATA_SOURCE_HOOK_NAMES,
         global_arguments.dry_run,
     )
     borgmatic.hooks.command.execute_hook(

borgmatic/actions/info.py

@@ -1,7 +1,7 @@
-import json
 import logging
 
 import borgmatic.actions.arguments
+import borgmatic.actions.json
 import borgmatic.borg.info
 import borgmatic.borg.rlist
 import borgmatic.config.validate
@@ -26,7 +26,7 @@ def run_info(
     if info_arguments.repository is None or borgmatic.config.validate.repositories_match(
         repository, info_arguments.repository
     ):
-        if not info_arguments.json:  # pragma: nocover
+        if not info_arguments.json:
             logger.answer(
                 f'{repository.get("label", repository["path"])}: Displaying archive summary information'
             )
@@ -48,5 +48,5 @@ def run_info(
             local_path,
             remote_path,
         )
-        if json_output:  # pragma: nocover
-            yield json.loads(json_output)
+        if json_output:
+            yield borgmatic.actions.json.parse_json(json_output, repository.get('label'))

borgmatic/actions/json.py

@@ -0,0 +1,16 @@
+import json
+
+
+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.
+    '''
+    json_data = json.loads(borg_json_output)
+
+    if 'repository' not in json_data:
+        return json_data
+
+    json_data['repository']['label'] = label or ''
+
+    return json_data

borgmatic/actions/list.py

@@ -1,7 +1,7 @@
-import json
 import logging
 
 import borgmatic.actions.arguments
+import borgmatic.actions.json
 import borgmatic.borg.list
 import borgmatic.config.validate
 
@@ -25,10 +25,10 @@ def run_list(
     if list_arguments.repository is None or borgmatic.config.validate.repositories_match(
         repository, list_arguments.repository
     ):
-        if not list_arguments.json:  # pragma: nocover
-            if list_arguments.find_paths:
+        if not list_arguments.json:
+            if list_arguments.find_paths:  # pragma: no cover
                 logger.answer(f'{repository.get("label", repository["path"])}: Searching archives')
-            elif not list_arguments.archive:
+            elif not list_arguments.archive:  # pragma: no cover
                 logger.answer(f'{repository.get("label", repository["path"])}: Listing archives')
 
         archive_name = borgmatic.borg.rlist.resolve_archive_name(
@@ -49,5 +49,5 @@ def run_list(
             local_path,
             remote_path,
         )
-        if json_output:  # pragma: nocover
-            yield json.loads(json_output)
+        if json_output:
+            yield borgmatic.actions.json.parse_json(json_output, repository.get('label'))

borgmatic/actions/restore.py

@@ -17,27 +17,31 @@ logger = logging.getLogger(__name__)
 UNSPECIFIED_HOOK = object()
 
 
-def get_configured_database(
-    config, archive_database_names, hook_name, database_name, configuration_database_name=None
+def get_configured_data_source(
+    config,
+    archive_data_source_names,
+    hook_name,
+    data_source_name,
+    configuration_data_source_name=None,
 ):
     '''
-    Find the first database with the given hook name and database name in the configuration dict and
-    the given archive database names dict (from hook name to database names contained in a
-    particular backup archive). If UNSPECIFIED_HOOK is given as the hook name, search all database
-    hooks for the named database. If a configuration database name is given, use that instead of the
-    database name to lookup the database in the given hooks configuration.
+    Find the first data source with the given hook name and data source name in the configuration
+    dict and the given archive data source names dict (from hook name to data source names contained
+    in a particular backup archive). If UNSPECIFIED_HOOK is given as the hook name, search all data
+    source hooks for the named data source. If a configuration data source name is given, use that
+    instead of the data source name to lookup the data source in the given hooks configuration.
 
-    Return the found database as a tuple of (found hook name, database configuration dict) or (None,
-    None) if not found.
+    Return the found data source as a tuple of (found hook name, data source configuration dict) or
+    (None, None) if not found.
     '''
-    if not configuration_database_name:
-        configuration_database_name = database_name
+    if not configuration_data_source_name:
+        configuration_data_source_name = data_source_name
 
     if hook_name == UNSPECIFIED_HOOK:
         hooks_to_search = {
             hook_name: value
             for (hook_name, value) in config.items()
-            if hook_name in borgmatic.hooks.dump.DATABASE_HOOK_NAMES
+            if hook_name in borgmatic.hooks.dump.DATA_SOURCE_HOOK_NAMES
         }
     else:
         try:
@@ -47,24 +51,17 @@ def get_configured_database(
 
     return next(
         (
-            (name, hook_database)
+            (name, hook_data_source)
             for (name, hook) in hooks_to_search.items()
-            for hook_database in hook
-            if hook_database['name'] == configuration_database_name
-            and database_name in archive_database_names.get(name, [])
+            for hook_data_source in hook
+            if hook_data_source['name'] == configuration_data_source_name
+            and data_source_name in archive_data_source_names.get(name, [])
         ),
         (None, None),
     )
 
 
-def get_configured_hook_name_and_database(hooks, database_name):
-    '''
-    Find the hook name and first database dict with the given database name in the configured hooks
-    dict. This searches across all database hooks.
-    '''
-
-
-def restore_single_database(
+def restore_single_data_source(
     repository,
     config,
     local_borg_version,
@@ -73,27 +70,27 @@ def restore_single_database(
     remote_path,
     archive_name,
     hook_name,
-    database,
+    data_source,
     connection_params,
 ):  # pragma: no cover
     '''
-    Given (among other things) an archive name, a database hook name, the hostname, port,
-    username/password as connection params, and a configured database configuration dict, restore
-    that database from the archive.
+    Given (among other things) an archive name, a data source hook name, the hostname, port,
+    username/password as connection params, and a configured data source configuration dict, restore
+    that data source from the archive.
     '''
     logger.info(
-        f'{repository.get("label", repository["path"])}: Restoring database {database["name"]}'
+        f'{repository.get("label", repository["path"])}: Restoring data source {data_source["name"]}'
     )
 
     dump_pattern = borgmatic.hooks.dispatch.call_hooks(
-        'make_database_dump_pattern',
+        'make_data_source_dump_pattern',
         config,
         repository['path'],
-        borgmatic.hooks.dump.DATABASE_HOOK_NAMES,
-        database['name'],
+        borgmatic.hooks.dump.DATA_SOURCE_HOOK_NAMES,
+        data_source['name'],
     )[hook_name]
 
-    # Kick off a single database extract to stdout.
+    # Kick off a single data source extract to stdout.
     extract_process = borgmatic.borg.extract.extract_archive(
         dry_run=global_arguments.dry_run,
         repository=repository['path'],
@@ -107,23 +104,23 @@ def restore_single_database(
         destination_path='/',
         # A directory format dump isn't a single file, and therefore can't extract
         # to stdout. In this case, the extract_process return value is None.
-        extract_to_stdout=bool(database.get('format') != 'directory'),
+        extract_to_stdout=bool(data_source.get('format') != 'directory'),
     )
 
-    # Run a single database restore, consuming the extract stdout (if any).
+    # Run a single data source restore, consuming the extract stdout (if any).
     borgmatic.hooks.dispatch.call_hooks(
-        function_name='restore_database_dump',
+        function_name='restore_data_source_dump',
         config=config,
         log_prefix=repository['path'],
         hook_names=[hook_name],
-        database=database,
+        data_source=data_source,
         dry_run=global_arguments.dry_run,
         extract_process=extract_process,
         connection_params=connection_params,
     )
 
 
-def collect_archive_database_names(
+def collect_archive_data_source_names(
     repository,
     archive,
     config,
@@ -135,60 +132,62 @@ def collect_archive_database_names(
     '''
     Given a local or remote repository path, a resolved archive name, a configuration dict, the
     local Borg version, global_arguments an argparse.Namespace, and local and remote Borg paths,
-    query the archive for the names of databases it contains and return them as a dict from hook
-    name to a sequence of database names.
+    query the archive for the names of data sources it contains as dumps and return them as a dict
+    from hook name to a sequence of data source names.
     '''
     borgmatic_source_directory = os.path.expanduser(
         config.get(
             'borgmatic_source_directory', borgmatic.borg.state.DEFAULT_BORGMATIC_SOURCE_DIRECTORY
         )
     ).lstrip('/')
-    parent_dump_path = os.path.expanduser(
-        borgmatic.hooks.dump.make_database_dump_path(borgmatic_source_directory, '*_databases/*/*')
-    )
     dump_paths = borgmatic.borg.list.capture_archive_listing(
         repository,
         archive,
         config,
         local_borg_version,
         global_arguments,
-        list_path=parent_dump_path,
+        list_paths=[
+            os.path.expanduser(
+                borgmatic.hooks.dump.make_data_source_dump_path(borgmatic_source_directory, pattern)
+            )
+            for pattern in ('*_databases/*/*',)
+        ],
         local_path=local_path,
         remote_path=remote_path,
     )
 
-    # Determine the database names corresponding to the dumps found in the archive and
+    # Determine the data source names corresponding to the dumps found in the archive and
     # add them to restore_names.
-    archive_database_names = {}
+    archive_data_source_names = {}
 
     for dump_path in dump_paths:
         try:
-            (hook_name, _, database_name) = dump_path.split(
+            (hook_name, _, data_source_name) = dump_path.split(
                 borgmatic_source_directory + os.path.sep, 1
             )[1].split(os.path.sep)[0:3]
         except (ValueError, IndexError):
             logger.warning(
-                f'{repository}: Ignoring invalid database dump path "{dump_path}" in archive {archive}'
+                f'{repository}: Ignoring invalid data source dump path "{dump_path}" in archive {archive}'
             )
         else:
-            if database_name not in archive_database_names.get(hook_name, []):
-                archive_database_names.setdefault(hook_name, []).extend([database_name])
+            if data_source_name not in archive_data_source_names.get(hook_name, []):
+                archive_data_source_names.setdefault(hook_name, []).extend([data_source_name])
 
-    return archive_database_names
+    return archive_data_source_names
 
 
-def find_databases_to_restore(requested_database_names, archive_database_names):
+def find_data_sources_to_restore(requested_data_source_names, archive_data_source_names):
     '''
-    Given a sequence of requested database names to restore and a dict of hook name to the names of
-    databases found in an archive, return an expanded sequence of database names to restore,
-    replacing "all" with actual database names as appropriate.
+    Given a sequence of requested data source names to restore and a dict of hook name to the names
+    of data sources found in an archive, return an expanded sequence of data source names to
+    restore, replacing "all" with actual data source names as appropriate.
 
-    Raise ValueError if any of the requested database names cannot be found in the archive.
+    Raise ValueError if any of the requested data source names cannot be found in the archive.
     '''
-    # A map from database hook name to the database names to restore for that hook.
+    # A map from data source hook name to the data source names to restore for that hook.
     restore_names = (
-        {UNSPECIFIED_HOOK: requested_database_names}
-        if requested_database_names
+        {UNSPECIFIED_HOOK: requested_data_source_names}
+        if requested_data_source_names
         else {UNSPECIFIED_HOOK: ['all']}
     )
 
@@ -197,56 +196,59 @@ def find_databases_to_restore(requested_database_names, archive_database_names):
     if 'all' in restore_names[UNSPECIFIED_HOOK]:
         restore_names[UNSPECIFIED_HOOK].remove('all')
 
-        for hook_name, database_names in archive_database_names.items():
-            restore_names.setdefault(hook_name, []).extend(database_names)
+        for hook_name, data_source_names in archive_data_source_names.items():
+            restore_names.setdefault(hook_name, []).extend(data_source_names)
 
-            # If a database is to be restored as part of "all", then remove it from restore names so
-            # it doesn't get restored twice.
-            for database_name in database_names:
-                if database_name in restore_names[UNSPECIFIED_HOOK]:
-                    restore_names[UNSPECIFIED_HOOK].remove(database_name)
+            # If a data source is to be restored as part of "all", then remove it from restore names
+            # so it doesn't get restored twice.
+            for data_source_name in data_source_names:
+                if data_source_name in restore_names[UNSPECIFIED_HOOK]:
+                    restore_names[UNSPECIFIED_HOOK].remove(data_source_name)
 
     if not restore_names[UNSPECIFIED_HOOK]:
         restore_names.pop(UNSPECIFIED_HOOK)
 
     combined_restore_names = set(
-        name for database_names in restore_names.values() for name in database_names
+        name for data_source_names in restore_names.values() for name in data_source_names
     )
-    combined_archive_database_names = set(
-        name for database_names in archive_database_names.values() for name in database_names
+    combined_archive_data_source_names = set(
+        name
+        for data_source_names in archive_data_source_names.values()
+        for name in data_source_names
     )
 
-    missing_names = sorted(set(combined_restore_names) - combined_archive_database_names)
+    missing_names = sorted(set(combined_restore_names) - combined_archive_data_source_names)
     if missing_names:
         joined_names = ', '.join(f'"{name}"' for name in missing_names)
         raise ValueError(
-            f"Cannot restore database{'s' if len(missing_names) > 1 else ''} {joined_names} missing from archive"
+            f"Cannot restore data source{'s' if len(missing_names) > 1 else ''} {joined_names} missing from archive"
         )
 
     return restore_names
 
 
-def ensure_databases_found(restore_names, remaining_restore_names, found_names):
+def ensure_data_sources_found(restore_names, remaining_restore_names, found_names):
     '''
-    Given a dict from hook name to database names to restore, a dict from hook name to remaining
-    database names to restore, and a sequence of found (actually restored) database names, raise
-    ValueError if requested databases to restore were missing from the archive and/or configuration.
+    Given a dict from hook name to data source names to restore, a dict from hook name to remaining
+    data source names to restore, and a sequence of found (actually restored) data source names,
+    raise ValueError if requested data source to restore were missing from the archive and/or
+    configuration.
     '''
     combined_restore_names = set(
         name
-        for database_names in tuple(restore_names.values())
+        for data_source_names in tuple(restore_names.values())
         + tuple(remaining_restore_names.values())
-        for name in database_names
+        for name in data_source_names
     )
 
     if not combined_restore_names and not found_names:
-        raise ValueError('No databases were found to restore')
+        raise ValueError('No data sources were found to restore')
 
     missing_names = sorted(set(combined_restore_names) - set(found_names))
     if missing_names:
         joined_names = ', '.join(f'"{name}"' for name in missing_names)
         raise ValueError(
-            f"Cannot restore database{'s' if len(missing_names) > 1 else ''} {joined_names} missing from borgmatic's configuration"
+            f"Cannot restore data source{'s' if len(missing_names) > 1 else ''} {joined_names} missing from borgmatic's configuration"
         )
 
 
@@ -263,7 +265,7 @@ def run_restore(
     Run the "restore" action for the given repository, but only if the repository matches the
     requested repository in restore arguments.
 
-    Raise ValueError if a configured database could not be found to restore.
+    Raise ValueError if a configured data source could not be found to restore.
     '''
     if restore_arguments.repository and not borgmatic.config.validate.repositories_match(
         repository, restore_arguments.repository
@@ -271,14 +273,14 @@ def run_restore(
         return
 
     logger.info(
-        f'{repository.get("label", repository["path"])}: Restoring databases from archive {restore_arguments.archive}'
+        f'{repository.get("label", repository["path"])}: Restoring data sources from archive {restore_arguments.archive}'
     )
 
     borgmatic.hooks.dispatch.call_hooks_even_if_unconfigured(
-        'remove_database_dumps',
+        'remove_data_source_dumps',
         config,
         repository['path'],
-        borgmatic.hooks.dump.DATABASE_HOOK_NAMES,
+        borgmatic.hooks.dump.DATA_SOURCE_HOOK_NAMES,
         global_arguments.dry_run,
     )
 
@@ -291,7 +293,7 @@ def run_restore(
         local_path,
         remote_path,
     )
-    archive_database_names = collect_archive_database_names(
+    archive_data_source_names = collect_archive_data_source_names(
         repository['path'],
         archive_name,
         config,
@@ -300,7 +302,9 @@ def run_restore(
         local_path,
         remote_path,
     )
-    restore_names = find_databases_to_restore(restore_arguments.databases, archive_database_names)
+    restore_names = find_data_sources_to_restore(
+        restore_arguments.data_sources, archive_data_source_names
+    )
     found_names = set()
     remaining_restore_names = {}
     connection_params = {
@@ -311,20 +315,20 @@ def run_restore(
         'restore_path': restore_arguments.restore_path,
     }
 
-    for hook_name, database_names in restore_names.items():
-        for database_name in database_names:
-            found_hook_name, found_database = get_configured_database(
-                config, archive_database_names, hook_name, database_name
+    for hook_name, data_source_names in restore_names.items():
+        for data_source_name in data_source_names:
+            found_hook_name, found_data_source = get_configured_data_source(
+                config, archive_data_source_names, hook_name, data_source_name
             )
 
-            if not found_database:
+            if not found_data_source:
                 remaining_restore_names.setdefault(found_hook_name or hook_name, []).append(
-                    database_name
+                    data_source_name
                 )
                 continue
 
-            found_names.add(database_name)
-            restore_single_database(
+            found_names.add(data_source_name)
+            restore_single_data_source(
                 repository,
                 config,
                 local_borg_version,
@@ -333,26 +337,26 @@ def run_restore(
                 remote_path,
                 archive_name,
                 found_hook_name or hook_name,
-                dict(found_database, **{'schemas': restore_arguments.schemas}),
+                dict(found_data_source, **{'schemas': restore_arguments.schemas}),
                 connection_params,
             )
 
-    # For any databases that weren't found via exact matches in the configuration, try to fallback
-    # to "all" entries.
-    for hook_name, database_names in remaining_restore_names.items():
-        for database_name in database_names:
-            found_hook_name, found_database = get_configured_database(
-                config, archive_database_names, hook_name, database_name, 'all'
+    # For any data sources that weren't found via exact matches in the configuration, try to
+    # fallback to "all" entries.
+    for hook_name, data_source_names in remaining_restore_names.items():
+        for data_source_name in data_source_names:
+            found_hook_name, found_data_source = get_configured_data_source(
+                config, archive_data_source_names, hook_name, data_source_name, 'all'
             )
 
-            if not found_database:
+            if not found_data_source:
                 continue
 
-            found_names.add(database_name)
-            database = copy.copy(found_database)
-            database['name'] = database_name
+            found_names.add(data_source_name)
+            data_source = copy.copy(found_data_source)
+            data_source['name'] = data_source_name
 
-            restore_single_database(
+            restore_single_data_source(
                 repository,
                 config,
                 local_borg_version,
@@ -361,16 +365,16 @@ def run_restore(
                 remote_path,
                 archive_name,
                 found_hook_name or hook_name,
-                dict(database, **{'schemas': restore_arguments.schemas}),
+                dict(data_source, **{'schemas': restore_arguments.schemas}),
                 connection_params,
             )
 
     borgmatic.hooks.dispatch.call_hooks_even_if_unconfigured(
-        'remove_database_dumps',
+        'remove_data_source_dumps',
         config,
         repository['path'],
-        borgmatic.hooks.dump.DATABASE_HOOK_NAMES,
+        borgmatic.hooks.dump.DATA_SOURCE_HOOK_NAMES,
         global_arguments.dry_run,
     )
 
-    ensure_databases_found(restore_names, remaining_restore_names, found_names)
+    ensure_data_sources_found(restore_names, remaining_restore_names, found_names)

borgmatic/actions/rinfo.py

@@ -1,6 +1,6 @@
-import json
 import logging
 
+import borgmatic.actions.json
 import borgmatic.borg.rinfo
 import borgmatic.config.validate
 
@@ -24,7 +24,7 @@ def run_rinfo(
     if rinfo_arguments.repository is None or borgmatic.config.validate.repositories_match(
         repository, rinfo_arguments.repository
     ):
-        if not rinfo_arguments.json:  # pragma: nocover
+        if not rinfo_arguments.json:
             logger.answer(
                 f'{repository.get("label", repository["path"])}: Displaying repository summary information'
             )
@@ -38,5 +38,5 @@ def run_rinfo(
             local_path=local_path,
             remote_path=remote_path,
         )
-        if json_output:  # pragma: nocover
-            yield json.loads(json_output)
+        if json_output:
+            yield borgmatic.actions.json.parse_json(json_output, repository.get('label'))

borgmatic/actions/rlist.py

@@ -1,6 +1,6 @@
-import json
 import logging
 
+import borgmatic.actions.json
 import borgmatic.borg.rlist
 import borgmatic.config.validate
 
@@ -24,7 +24,7 @@ def run_rlist(
     if rlist_arguments.repository is None or borgmatic.config.validate.repositories_match(
         repository, rlist_arguments.repository
     ):
-        if not rlist_arguments.json:  # pragma: nocover
+        if not rlist_arguments.json:
             logger.answer(f'{repository.get("label", repository["path"])}: Listing repository')
 
         json_output = borgmatic.borg.rlist.list_repository(
@@ -36,5 +36,5 @@ def run_rlist(
             local_path=local_path,
             remote_path=remote_path,
         )
-        if json_output:  # pragma: nocover
-            yield json.loads(json_output)
+        if json_output:
+            yield borgmatic.actions.json.parse_json(json_output, repository.get('label'))

borgmatic/borg/borg.py

@@ -1,4 +1,5 @@
 import logging
+import shlex
 
 import borgmatic.commands.arguments
 import borgmatic.logger
@@ -56,9 +57,8 @@ def run_arbitrary_borg(
     )
 
     return execute_command(
-        full_command,
+        tuple(shlex.quote(part) for part in full_command),
         output_file=DO_NOT_CAPTURE,
-        borg_local_path=local_path,
         shell=True,
         extra_environment=dict(
             (environment.make_environment(config) or {}),
@@ -67,4 +67,6 @@ def run_arbitrary_borg(
                 'ARCHIVE': archive if archive else '',
             },
         ),
+        borg_local_path=local_path,
+        borg_exit_codes=config.get('borg_exit_codes'),
     )

borgmatic/borg/break_lock.py

@@ -34,4 +34,9 @@ def break_lock(
     )
 
     borg_environment = environment.make_environment(config)
-    execute_command(full_command, borg_local_path=local_path, extra_environment=borg_environment)
+    execute_command(
+        full_command,
+        extra_environment=borg_environment,
+        borg_local_path=local_path,
+        borg_exit_codes=config.get('borg_exit_codes'),
+    )

borgmatic/borg/check.py

@@ -39,7 +39,11 @@ def parse_checks(config, only_checks=None):
         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'
@@ -119,6 +123,9 @@ def filter_checks_on_frequency(
 
     Raise ValueError if a frequency cannot be parsed.
     '''
+    if not checks:
+        return checks
+
     filtered_checks = list(checks)
 
     if force:
@@ -149,11 +156,13 @@ def filter_checks_on_frequency(
     return tuple(filtered_checks)
 
 
-def make_archive_filter_flags(local_borg_version, config, checks, check_last=None, prefix=None):
+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, 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.
+    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.
@@ -168,7 +177,7 @@ def make_archive_filter_flags(local_borg_version, config, checks, check_last=Non
             if prefix
             else (
                 flags.make_match_archives_flags(
-                    config.get('match_archives'),
+                    check_arguments.match_archives or config.get('match_archives'),
                     config.get('archive_name_format'),
                     local_borg_version,
                 )
@@ -353,18 +362,15 @@ def check_archives(
     repository_path,
     config,
     local_borg_version,
+    check_arguments,
     global_arguments,
     local_path='borg',
     remote_path=None,
-    progress=None,
-    repair=None,
-    only_checks=None,
-    force=None,
 ):
     '''
-    Given a local or remote repository path, a configuration dict, local/remote commands to run,
-    whether to include progress information, whether to attempt a repair, and an optional list of
-    checks to use instead of configured checks, check the contained Borg archives for consistency.
+    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.
 
     If there are no consistency checks to run, skip running them.
 
@@ -389,11 +395,11 @@ def check_archives(
 
     check_last = config.get('check_last', None)
     prefix = config.get('prefix')
-    configured_checks = parse_checks(config, only_checks)
+    configured_checks = parse_checks(config, check_arguments.only_checks)
     lock_wait = None
     extra_borg_options = config.get('extra_borg_options', {}).get('check', '')
     archive_filter_flags = make_archive_filter_flags(
-        local_borg_version, config, configured_checks, check_last, prefix
+        local_borg_version, config, configured_checks, check_arguments, check_last, prefix
     )
     archives_check_id = make_archives_check_id(archive_filter_flags)
 
@@ -401,7 +407,7 @@ def check_archives(
         config,
         borg_repository_id,
         configured_checks,
-        force,
+        check_arguments.force,
         archives_check_id,
     )
 
@@ -416,27 +422,37 @@ def check_archives(
 
         full_command = (
             (local_path, 'check')
-            + (('--repair',) if repair else ())
+            + (('--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 progress else ())
+            + (('--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)
         )
 
         borg_environment = environment.make_environment(config)
+        borg_exit_codes = config.get('borg_exit_codes')
 
         # The Borg repair option triggers an interactive prompt, which won't work when output is
         # captured. And progress messes with the terminal directly.
-        if repair or progress:
+        if check_arguments.repair or check_arguments.progress:
             execute_command(
-                full_command, output_file=DO_NOT_CAPTURE, extra_environment=borg_environment
+                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)
+            execute_command(
+                full_command,
+                extra_environment=borg_environment,
+                borg_local_path=local_path,
+                borg_exit_codes=borg_exit_codes,
+            )
 
         for check in checks:
             write_check_time(

borgmatic/borg/compact.py

@@ -48,6 +48,7 @@ def compact_segments(
     execute_command(
         full_command,
         output_log_level=logging.INFO,
-        borg_local_path=local_path,
         extra_environment=environment.make_environment(config),
+        borg_local_path=local_path,
+        borg_exit_codes=config.get('borg_exit_codes'),
     )

borgmatic/borg/create.py

@@ -215,9 +215,6 @@ def make_list_filter_flags(local_borg_version, dry_run):
         return f'{base_flags}-'
 
 
-DEFAULT_ARCHIVE_NAME_FORMAT = '{hostname}-{now:%Y-%m-%dT%H:%M:%S.%f}'  # noqa: FS003
-
-
 def collect_borgmatic_source_directories(borgmatic_source_directory):
     '''
     Return a list of borgmatic-specific source directories used for state like database backups.
@@ -275,7 +272,7 @@ def any_parent_directories(path, candidate_parents):
 
 
 def collect_special_file_paths(
-    create_command, local_path, working_directory, borg_environment, skip_directories
+    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
@@ -293,6 +290,7 @@ def collect_special_file_paths(
         working_directory=working_directory,
         extra_environment=borg_environment,
         borg_local_path=local_path,
+        borg_exit_codes=config.get('borg_exit_codes'),
     )
 
     paths = tuple(
@@ -326,6 +324,7 @@ def create_archive(
     dry_run,
     repository_path,
     config,
+    config_paths,
     local_borg_version,
     global_arguments,
     local_path='borg',
@@ -337,8 +336,9 @@ def create_archive(
     stream_processes=None,
 ):
     '''
-    Given vebosity/dry-run flags, a local or remote repository path, and a configuration dict,
-    create a Borg archive and return Borg's JSON output (if any).
+    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.
@@ -354,11 +354,7 @@ def create_archive(
             expand_directories(
                 tuple(config.get('source_directories', ()))
                 + borgmatic_source_directories
-                + tuple(
-                    global_arguments.used_config_paths
-                    if config.get('store_config_files', True)
-                    else ()
-                )
+                + tuple(config_paths if config.get('store_config_files', True) else ())
             )
         ),
         additional_directory_devices=map_directories_to_devices(
@@ -388,7 +384,7 @@ def create_archive(
     lock_wait = config.get('lock_wait', None)
     list_filter_flags = make_list_filter_flags(local_borg_version, dry_run)
     files_cache = config.get('files_cache')
-    archive_name_format = config.get('archive_name_format', DEFAULT_ARCHIVE_NAME_FORMAT)
+    archive_name_format = config.get('archive_name_format', flags.DEFAULT_ARCHIVE_NAME_FORMAT)
     extra_borg_options = config.get('extra_borg_options', {}).get('create', '')
 
     if feature.available(feature.Feature.ATIME, local_borg_version):
@@ -474,6 +470,7 @@ def create_archive(
         logger.debug(f'{repository_path}: Collecting special file paths')
         special_file_paths = collect_special_file_paths(
             create_flags + create_positional_arguments,
+            config,
             local_path,
             working_directory,
             borg_environment,
@@ -499,6 +496,7 @@ def create_archive(
         + (('--progress',) if progress else ())
         + (('--json',) if json else ())
     )
+    borg_exit_codes = config.get('borg_exit_codes')
 
     if stream_processes:
         return execute_command_with_processes(
@@ -506,9 +504,10 @@ def create_archive(
             stream_processes,
             output_log_level,
             output_file,
-            borg_local_path=local_path,
             working_directory=working_directory,
             extra_environment=borg_environment,
+            borg_local_path=local_path,
+            borg_exit_codes=borg_exit_codes,
         )
     elif output_log_level is None:
         return execute_command_and_capture_output(
@@ -516,13 +515,15 @@ def create_archive(
             working_directory=working_directory,
             extra_environment=borg_environment,
             borg_local_path=local_path,
+            borg_exit_codes=borg_exit_codes,
         )
     else:
         execute_command(
             create_flags + create_positional_arguments,
             output_log_level,
             output_file,
-            borg_local_path=local_path,
             working_directory=working_directory,
             extra_environment=borg_environment,
+            borg_local_path=local_path,
+            borg_exit_codes=borg_exit_codes,
         )

borgmatic/borg/environment.py

@@ -50,4 +50,8 @@ def make_environment(config):
         if value is not None:
             environment[environment_variable_name] = 'YES' if value else 'NO'
 
+    # On Borg 1.4.0a1+, take advantage of more specific exit codes. No effect on
+    # older versions of Borg.
+    environment['BORG_EXIT_CODES'] = 'modern'
+
     return environment

borgmatic/borg/export_key.py

@@ -65,6 +65,7 @@ def export_key(
         full_command,
         output_file=output_file,
         output_log_level=logging.ANSWER,
-        borg_local_path=local_path,
         extra_environment=environment.make_environment(config),
+        borg_local_path=local_path,
+        borg_exit_codes=config.get('borg_exit_codes'),
     )

borgmatic/borg/export_tar.py

@@ -69,6 +69,7 @@ def export_tar_archive(
         full_command,
         output_file=DO_NOT_CAPTURE if destination_path == '-' else None,
         output_log_level=output_log_level,
-        borg_local_path=local_path,
         extra_environment=environment.make_environment(config),
+        borg_local_path=local_path,
+        borg_exit_codes=config.get('borg_exit_codes'),
     )

borgmatic/borg/extract.py

@@ -57,7 +57,11 @@ def extract_last_archive_dry_run(
     )
 
     execute_command(
-        full_extract_command, working_directory=None, extra_environment=borg_environment
+        full_extract_command,
+        working_directory=None,
+        extra_environment=borg_environment,
+        borg_local_path=local_path,
+        borg_exit_codes=config.get('borg_exit_codes'),
     )
 
 
@@ -127,6 +131,7 @@ def extract_archive(
     )
 
     borg_environment = environment.make_environment(config)
+    borg_exit_codes = config.get('borg_exit_codes')
 
     # The progress output isn't compatible with captured and logged output, as progress messes with
     # the terminal directly.
@@ -136,6 +141,8 @@ def extract_archive(
             output_file=DO_NOT_CAPTURE,
             working_directory=destination_path,
             extra_environment=borg_environment,
+            borg_local_path=local_path,
+            borg_exit_codes=borg_exit_codes,
         )
         return None
 
@@ -146,10 +153,16 @@ def extract_archive(
             working_directory=destination_path,
             run_to_completion=False,
             extra_environment=borg_environment,
+            borg_local_path=local_path,
+            borg_exit_codes=borg_exit_codes,
         )
 
     # Don't give Borg local path so as to error on warnings, as "borg extract" only gives a warning
     # if the restore paths don't exist in the archive.
     execute_command(
-        full_command, working_directory=destination_path, extra_environment=borg_environment
+        full_command,
+        working_directory=destination_path,
+        extra_environment=borg_environment,
+        borg_local_path=local_path,
+        borg_exit_codes=borg_exit_codes,
     )

borgmatic/borg/flags.py

@@ -1,8 +1,12 @@
 import itertools
+import json
+import logging
 import re
 
 from borgmatic.borg import feature
 
+logger = logging.getLogger(__name__)
+
 
 def make_flags(name, value):
     '''
@@ -59,12 +63,15 @@ 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):
     '''
     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 archive name format, if
-    any. This is done by replacing certain archive name format placeholders for ephemeral data (like
-    "{now}") with globs.
+    return match archives flags to match archives created with the given (or default) archive name
+    format. This is done by replacing certain archive name format placeholders for ephemeral data
+    (like "{now}") with globs.
     '''
     if match_archives:
         if feature.available(feature.Feature.MATCH_ARCHIVES, local_borg_version):
@@ -72,10 +79,9 @@ def make_match_archives_flags(match_archives, archive_name_format, local_borg_ve
         else:
             return ('--glob-archives', re.sub(r'^sh:', '', match_archives))
 
-    if not archive_name_format:
-        return ()
-
-    derived_match_archives = re.sub(r'\{(now|utcnow|pid)([:%\w\.-]*)\}', '*', archive_name_format)
+    derived_match_archives = re.sub(
+        r'\{(now|utcnow|pid)([:%\w\.-]*)\}', '*', archive_name_format or DEFAULT_ARCHIVE_NAME_FORMAT
+    )
 
     if derived_match_archives == '*':
         return ()
@@ -84,3 +90,26 @@ def make_match_archives_flags(match_archives, archive_name_format, local_borg_ve
         return ('--match-archives', f'sh:{derived_match_archives}')
     else:
         return ('--glob-archives', f'{derived_match_archives}')
+
+
+def warn_for_aggressive_archive_flags(json_command, json_output):
+    '''
+    Given a JSON archives command and the resulting JSON string output from running it, parse the
+    JSON and warn if the command used an archive flag but the output indicates zero archives were
+    found.
+    '''
+    archive_flags_used = {'--glob-archives', '--match-archives'}.intersection(set(json_command))
+
+    if not archive_flags_used:
+        return
+
+    try:
+        if len(json.loads(json_output)['archives']) == 0:
+            logger.warning('An archive filter was applied, but no matching archives were found.')
+            logger.warning(
+                'Try adding --match-archives "*" or adjusting archive_name_format/match_archives in configuration.'
+            )
+    except json.JSONDecodeError as error:
+        logger.debug(f'Cannot parse JSON output from archive command: {error}')
+    except (TypeError, KeyError):
+        logger.debug('Cannot parse JSON output from archive command: No "archives" key found')

borgmatic/borg/info.py

@@ -1,3 +1,4 @@
+import argparse
 import logging
 
 import borgmatic.logger
@@ -7,24 +8,21 @@ from borgmatic.execute import execute_command, execute_command_and_capture_outpu
 logger = logging.getLogger(__name__)
 
 
-def display_archives_info(
+def make_info_command(
     repository_path,
     config,
     local_borg_version,
     info_arguments,
     global_arguments,
-    local_path='borg',
-    remote_path=None,
+    local_path,
+    remote_path,
 ):
     '''
-    Given a local or remote repository path, a configuration dict, the local Borg version, global
-    arguments as an argparse.Namespace, and the arguments to the info action, display summary
-    information for Borg archives in the repository or return JSON summary information.
+    Given a local or remote repository path, a configuration dict, the local Borg version, the
+    arguments to the info action as an argparse.Namespace, and global arguments, return a command
+    as a tuple to display summary information for archives in the repository.
     '''
-    borgmatic.logger.add_custom_log_levels()
-    lock_wait = config.get('lock_wait', None)
-
-    full_command = (
+    return (
         (local_path, 'info')
         + (
             ('--info',)
@@ -38,7 +36,7 @@ def display_archives_info(
         )
         + flags.make_flags('remote-path', remote_path)
         + flags.make_flags('log-json', global_arguments.log_json)
-        + flags.make_flags('lock-wait', lock_wait)
+        + flags.make_flags('lock-wait', config.get('lock_wait'))
         + (
             (
                 flags.make_flags('match-archives', f'sh:{info_arguments.prefix}*')
@@ -62,16 +60,59 @@ def display_archives_info(
         + flags.make_repository_flags(repository_path, local_borg_version)
     )
 
+
+def display_archives_info(
+    repository_path,
+    config,
+    local_borg_version,
+    info_arguments,
+    global_arguments,
+    local_path='borg',
+    remote_path=None,
+):
+    '''
+    Given a local or remote repository path, a configuration dict, the local Borg version, the
+    arguments to the info action as an argparse.Namespace, and global arguments, display summary
+    information for Borg archives in the repository or return JSON summary information.
+    '''
+    borgmatic.logger.add_custom_log_levels()
+
+    main_command = make_info_command(
+        repository_path,
+        config,
+        local_borg_version,
+        info_arguments,
+        global_arguments,
+        local_path,
+        remote_path,
+    )
+    json_command = make_info_command(
+        repository_path,
+        config,
+        local_borg_version,
+        argparse.Namespace(**dict(info_arguments.__dict__, json=True)),
+        global_arguments,
+        local_path,
+        remote_path,
+    )
+    borg_exit_codes = config.get('borg_exit_codes')
+
+    json_info = execute_command_and_capture_output(
+        json_command,
+        extra_environment=environment.make_environment(config),
+        borg_local_path=local_path,
+        borg_exit_codes=borg_exit_codes,
+    )
+
     if info_arguments.json:
-        return execute_command_and_capture_output(
-            full_command,
-            extra_environment=environment.make_environment(config),
-            borg_local_path=local_path,
-        )
-    else:
-        execute_command(
-            full_command,
-            output_log_level=logging.ANSWER,
-            borg_local_path=local_path,
-            extra_environment=environment.make_environment(config),
-        )
+        return json_info
+
+    flags.warn_for_aggressive_archive_flags(json_command, json_info)
+
+    execute_command(
+        main_command,
+        output_log_level=logging.ANSWER,
+        extra_environment=environment.make_environment(config),
+        borg_local_path=local_path,
+        borg_exit_codes=borg_exit_codes,
+    )

borgmatic/borg/list.py

@@ -92,13 +92,13 @@ def capture_archive_listing(
     config,
     local_borg_version,
     global_arguments,
-    list_path=None,
+    list_paths=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 path in which to list files, and
+    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.
     '''
@@ -113,7 +113,7 @@ def capture_archive_listing(
                 argparse.Namespace(
                     repository=repository_path,
                     archive=archive,
-                    paths=[f'sh:{list_path}'],
+                    paths=[f'sh:{path}' for path in list_paths] if list_paths else None,
                     find_paths=None,
                     json=None,
                     format='{path}{NL}',  # noqa: FS003
@@ -124,6 +124,7 @@ def capture_archive_listing(
             ),
             extra_environment=borg_environment,
             borg_local_path=local_path,
+            borg_exit_codes=config.get('borg_exit_codes'),
         )
         .strip('\n')
         .split('\n')
@@ -189,6 +190,7 @@ def list_archive(
         )
 
     borg_environment = environment.make_environment(config)
+    borg_exit_codes = config.get('borg_exit_codes')
 
     # If there are any paths to find (and there's not a single archive already selected), start by
     # getting a list of archives to search.
@@ -219,6 +221,7 @@ def list_archive(
                 ),
                 extra_environment=borg_environment,
                 borg_local_path=local_path,
+                borg_exit_codes=borg_exit_codes,
             )
             .strip('\n')
             .split('\n')
@@ -251,6 +254,7 @@ def list_archive(
         execute_command(
             main_command,
             output_log_level=logging.ANSWER,
-            borg_local_path=local_path,
             extra_environment=borg_environment,
+            borg_local_path=local_path,
+            borg_exit_codes=borg_exit_codes,
         )

borgmatic/borg/mount.py

@@ -65,9 +65,15 @@ def mount_archive(
         execute_command(
             full_command,
             output_file=DO_NOT_CAPTURE,
-            borg_local_path=local_path,
             extra_environment=borg_environment,
+            borg_local_path=local_path,
+            borg_exit_codes=config.get('borg_exit_codes'),
         )
         return
 
-    execute_command(full_command, borg_local_path=local_path, extra_environment=borg_environment)
+    execute_command(
+        full_command,
+        extra_environment=borg_environment,
+        borg_local_path=local_path,
+        borg_exit_codes=config.get('borg_exit_codes'),
+    )

borgmatic/borg/prune.py

@@ -94,6 +94,7 @@ def prune_archives(
     execute_command(
         full_command,
         output_log_level=output_log_level,
-        borg_local_path=local_path,
         extra_environment=environment.make_environment(config),
+        borg_local_path=local_path,
+        borg_exit_codes=config.get('borg_exit_codes'),
     )

borgmatic/borg/rcreate.py

@@ -81,6 +81,7 @@ def create_repository(
     execute_command(
         rcreate_command,
         output_file=DO_NOT_CAPTURE,
-        borg_local_path=local_path,
         extra_environment=environment.make_environment(config),
+        borg_local_path=local_path,
+        borg_exit_codes=config.get('borg_exit_codes'),
     )

borgmatic/borg/rinfo.py

@@ -49,17 +49,20 @@ def display_repository_info(
     )
 
     extra_environment = environment.make_environment(config)
+    borg_exit_codes = config.get('borg_exit_codes')
 
     if rinfo_arguments.json:
         return execute_command_and_capture_output(
             full_command,
             extra_environment=extra_environment,
             borg_local_path=local_path,
+            borg_exit_codes=borg_exit_codes,
         )
     else:
         execute_command(
             full_command,
             output_log_level=logging.ANSWER,
-            borg_local_path=local_path,
             extra_environment=extra_environment,
+            borg_local_path=local_path,
+            borg_exit_codes=borg_exit_codes,
         )

borgmatic/borg/rlist.py

@@ -1,3 +1,4 @@
+import argparse
 import logging
 
 import borgmatic.logger
@@ -44,6 +45,7 @@ def resolve_archive_name(
         full_command,
         extra_environment=environment.make_environment(config),
         borg_local_path=local_path,
+        borg_exit_codes=config.get('borg_exit_codes'),
     )
     try:
         latest_archive = output.strip().splitlines()[-1]
@@ -137,15 +139,33 @@ def list_repository(
         local_path,
         remote_path,
     )
+    json_command = make_rlist_command(
+        repository_path,
+        config,
+        local_borg_version,
+        argparse.Namespace(**dict(rlist_arguments.__dict__, json=True)),
+        global_arguments,
+        local_path,
+        remote_path,
+    )
+    borg_exit_codes = config.get('borg_exit_codes')
+
+    json_listing = execute_command_and_capture_output(
+        json_command,
+        extra_environment=borg_environment,
+        borg_local_path=local_path,
+        borg_exit_codes=borg_exit_codes,
+    )
 
     if rlist_arguments.json:
-        return execute_command_and_capture_output(
-            main_command, extra_environment=borg_environment, borg_local_path=local_path
-        )
-    else:
-        execute_command(
-            main_command,
-            output_log_level=logging.ANSWER,
-            borg_local_path=local_path,
-            extra_environment=borg_environment,
-        )
+        return json_listing
+
+    flags.warn_for_aggressive_archive_flags(json_command, json_listing)
+
+    execute_command(
+        main_command,
+        output_log_level=logging.ANSWER,
+        extra_environment=borg_environment,
+        borg_local_path=local_path,
+        borg_exit_codes=borg_exit_codes,
+    )

borgmatic/borg/transfer.py

@@ -56,5 +56,6 @@ def transfer_archives(
         output_log_level=logging.ANSWER,
         output_file=DO_NOT_CAPTURE if transfer_arguments.progress else None,
         borg_local_path=local_path,
+        borg_exit_codes=config.get('borg_exit_codes'),
         extra_environment=environment.make_environment(config),
     )

borgmatic/borg/umount.py

@@ -5,7 +5,7 @@ from borgmatic.execute import execute_command
 logger = logging.getLogger(__name__)
 
 
-def unmount_archive(mount_point, local_path='borg'):
+def unmount_archive(config, mount_point, local_path='borg'):
     '''
     Given a mounted filesystem mount point, and an optional local Borg paths, umount the filesystem
     from the mount point.
@@ -17,4 +17,6 @@ def unmount_archive(mount_point, local_path='borg'):
         + (mount_point,)
     )
 
-    execute_command(full_command)
+    execute_command(
+        full_command, borg_local_path=local_path, borg_exit_codes=config.get('borg_exit_codes')
+    )

borgmatic/borg/version.py

@@ -22,6 +22,7 @@ def local_borg_version(config, local_path='borg'):
         full_command,
         extra_environment=environment.make_environment(config),
         borg_local_path=local_path,
+        borg_exit_codes=config.get('borg_exit_codes'),
     )
 
     try:

borgmatic/commands/arguments.py

@@ -259,28 +259,28 @@ def make_parsers():
         type=int,
         choices=range(-2, 3),
         default=0,
-        help='Display verbose progress to the console (disabled, errors only, default, some, or lots: -2, -1, 0, 1, or 2)',
+        help='Display verbose progress to the console: -2 (disabled), -1 (errors only), 0 (responses to actions, the default), 1 (info about steps borgmatic is taking), or 2 (debug)',
     )
     global_group.add_argument(
         '--syslog-verbosity',
         type=int,
         choices=range(-2, 3),
-        default=0,
-        help='Log verbose progress to syslog (disabled, errors only, default, some, or lots: -2, -1, 0, 1, or 2). Ignored when console is interactive or --log-file is given',
+        default=-2,
+        help='Log verbose progress to syslog: -2 (disabled, the default), -1 (errors only), 0 (responses to actions), 1 (info about steps borgmatic is taking), or 2 (debug)',
     )
     global_group.add_argument(
         '--log-file-verbosity',
         type=int,
         choices=range(-2, 3),
-        default=0,
-        help='Log verbose progress to log file (disabled, errors only, default, some, or lots: -2, -1, 0, 1, or 2). Only used when --log-file is given',
+        default=1,
+        help='When --log-file is given, log verbose progress to file: -2 (disabled), -1 (errors only), 0 (responses to actions), 1 (info about steps borgmatic is taking, the default), or 2 (debug)',
     )
     global_group.add_argument(
         '--monitoring-verbosity',
         type=int,
         choices=range(-2, 3),
-        default=0,
-        help='Log verbose progress to monitoring integrations that support logging (from disabled, errors only, default, some, or lots: -2, -1, 0, 1, or 2)',
+        default=1,
+        help='When a monitoring integration supporting logging is configured, log verbose progress to it: -2 (disabled), -1 (errors only), responses to actions (0), 1 (info about steps borgmatic is taking, the default), or 2 (debug)',
     )
     global_group.add_argument(
         '--log-file',
@@ -302,7 +302,7 @@ def make_parsers():
         metavar='OPTION.SUBOPTION=VALUE',
         dest='overrides',
         action='append',
-        help='Configuration file option to override with specified value, can specify flag multiple times',
+        help='Configuration file option to override with specified value, see documentation for overriding list or key/value options, can specify flag multiple times',
     )
     global_group.add_argument(
         '--no-environment-interpolation',
@@ -467,8 +467,8 @@ def make_parsers():
     prune_parser = action_parsers.add_parser(
         'prune',
         aliases=ACTION_ALIASES['prune'],
-        help='Prune archives according to the retention policy (with Borg 1.2+, run compact afterwards to actually free space)',
-        description='Prune archives according to the retention policy (with Borg 1.2+, run compact afterwards to actually free space)',
+        help='Prune archives according to the retention policy (with Borg 1.2+, you must run compact afterwards to actually free space)',
+        description='Prune archives according to the retention policy (with Borg 1.2+, you must run compact afterwards to actually free space)',
         add_help=False,
     )
     prune_group = prune_parser.add_argument_group('prune arguments')
@@ -604,11 +604,18 @@ def make_parsers():
         action='store_true',
         help='Attempt to repair any inconsistencies found (for interactive use)',
     )
+    check_group.add_argument(
+        '-a',
+        '--match-archives',
+        '--glob-archives',
+        metavar='PATTERN',
+        help='Only check archives with names matching this pattern',
+    )
     check_group.add_argument(
         '--only',
         metavar='CHECK',
         choices=('repository', 'archives', 'data', 'extract'),
-        dest='only',
+        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)',
     )
@@ -724,6 +731,11 @@ def make_parsers():
         action='store_true',
         help='Display progress for each file as it is extracted',
     )
+    config_bootstrap_group.add_argument(
+        '--ssh-command',
+        metavar='COMMAND',
+        help='Command to use instead of "ssh"',
+    )
     config_bootstrap_group.add_argument(
         '-h', '--help', action='help', help='Show this help message and exit'
     )
@@ -906,8 +918,8 @@ def make_parsers():
     restore_parser = action_parsers.add_parser(
         'restore',
         aliases=ACTION_ALIASES['restore'],
-        help='Restore database dumps from a named archive',
-        description='Restore database dumps from a named archive. (To extract files instead, use "borgmatic extract".)',
+        help='Restore data source (e.g. database) dumps from a named archive',
+        description='Restore data source (e.g. database) dumps from a named archive. (To extract files instead, use "borgmatic extract".)',
         add_help=False,
     )
     restore_group = restore_parser.add_argument_group('restore arguments')
@@ -919,18 +931,19 @@ def make_parsers():
         '--archive', help='Name of archive to restore from (or "latest")', required=True
     )
     restore_group.add_argument(
+        '--data-source',
         '--database',
         metavar='NAME',
-        dest='databases',
+        dest='data_sources',
         action='append',
-        help="Name of database to restore from archive, must be defined in borgmatic's configuration, can specify flag multiple times, defaults to all databases",
+        help="Name of data source (e.g. database) to restore from archive, must be defined in borgmatic's configuration, can specify flag multiple times, defaults to all data sources in the archive",
     )
     restore_group.add_argument(
         '--schema',
         metavar='NAME',
         dest='schemas',
         action='append',
-        help='Name of schema to restore from the database, can specify flag multiple times, defaults to all schemas. Schemas are only supported for PostgreSQL and MongoDB databases',
+        help='Name of schema to restore from the data source, can specify flag multiple times, defaults to all schemas. Schemas are only supported for PostgreSQL and MongoDB databases',
     )
     restore_group.add_argument(
         '--hostname',
@@ -938,7 +951,7 @@ def make_parsers():
     )
     restore_group.add_argument(
         '--port',
-        help='Port to restore to. Defaults to the "restore_port" option in borgmatic\'s configuration',
+        help='Database port to restore to. Defaults to the "restore_port" option in borgmatic\'s configuration',
     )
     restore_group.add_argument(
         '--username',
@@ -1327,4 +1340,7 @@ def parse_arguments(*unparsed_arguments):
             'With the info action, only one of --archive, --prefix, or --match-archives flags can be used.'
         )
 
+    if 'borg' in arguments and arguments['global'].dry_run:
+        raise ValueError('With the borg action, --dry-run is not supported.')
+
     return arguments

borgmatic/commands/borgmatic.py

@@ -1,4 +1,5 @@
 import collections
+import importlib.metadata
 import json
 import logging
 import os
@@ -9,11 +10,6 @@ from subprocess import CalledProcessError
 
 import colorama
 
-try:
-    import importlib_metadata
-except ModuleNotFoundError:  # pragma: nocover
-    import importlib.metadata as importlib_metadata
-
 import borgmatic.actions.borg
 import borgmatic.actions.break_lock
 import borgmatic.actions.check
@@ -48,11 +44,25 @@ from borgmatic.verbosity import verbosity_to_log_level
 logger = logging.getLogger(__name__)
 
 
-def run_configuration(config_filename, config, arguments):
+def get_skip_actions(config, arguments):
     '''
-    Given a config filename, the corresponding parsed config dict, and command-line arguments as a
-    dict from subparser name to a namespace of parsed arguments, execute the defined create, prune,
-    compact, check, and/or other actions.
+    Given a configuration dict and command-line arguments as an argparse.Namespace, return a list of
+    the configured action names to skip. Omit "check" from this list though if "check --force" is
+    part of the command-like arguments.
+    '''
+    skip_actions = config.get('skip_actions', [])
+
+    if 'check' in arguments and arguments['check'].force:
+        return [action for action in skip_actions if action != 'check']
+
+    return skip_actions
+
+
+def run_configuration(config_filename, config, config_paths, arguments):
+    '''
+    Given a config filename, the corresponding parsed config dict, a sequence of loaded
+    configuration paths, and command-line arguments as a dict from subparser name to a namespace of
+    parsed arguments, execute the defined create, prune, compact, check, and/or other actions.
 
     Yield a combination of:
 
@@ -70,9 +80,16 @@ def run_configuration(config_filename, config, arguments):
     using_primary_action = {'create', 'prune', 'compact', 'check'}.intersection(arguments)
     monitoring_log_level = verbosity_to_log_level(global_arguments.monitoring_verbosity)
     monitoring_hooks_are_activated = using_primary_action and monitoring_log_level != DISABLED
+    skip_actions = get_skip_actions(config, arguments)
+
+    if skip_actions:
+        logger.debug(
+            f"{config_filename}: Skipping {'/'.join(skip_actions)} action{'s' if len(skip_actions) > 1 else ''} due to configured skip_actions"
+        )
 
     try:
         local_borg_version = borg_version.local_borg_version(config, local_path)
+        logger.debug(f'{config_filename}: Borg {local_borg_version}')
     except (OSError, CalledProcessError, ValueError) as error:
         yield from log_error_records(f'{config_filename}: Error getting local Borg version', error)
         return
@@ -127,6 +144,7 @@ def run_configuration(config_filename, config, arguments):
                     arguments=arguments,
                     config_filename=config_filename,
                     config=config,
+                    config_paths=config_paths,
                     local_path=local_path,
                     remote_path=remote_path,
                     local_borg_version=local_borg_version,
@@ -247,6 +265,7 @@ def run_actions(
     arguments,
     config_filename,
     config,
+    config_paths,
     local_path,
     remote_path,
     local_borg_version,
@@ -254,9 +273,9 @@ def run_actions(
 ):
     '''
     Given parsed command-line arguments as an argparse.ArgumentParser instance, the configuration
-    filename, several different configuration dicts, local and remote paths to Borg, a local Borg
-    version string, and a repository name, run all actions from the command-line arguments on the
-    given repository.
+    filename, a configuration dict, a sequence of loaded configuration paths, local and remote paths
+    to Borg, a local Borg version string, and a repository name, run all actions from the
+    command-line arguments on the given repository.
 
     Yield JSON output strings from executing any actions that produce JSON.
 
@@ -274,6 +293,7 @@ def run_actions(
         'repositories': ','.join([repo['path'] for repo in config['repositories']]),
         'log_file': global_arguments.log_file if global_arguments.log_file else '',
     }
+    skip_actions = set(get_skip_actions(config, arguments))
 
     command.execute_hook(
         config.get('before_actions'),
@@ -285,7 +305,7 @@ def run_actions(
     )
 
     for action_name, action_arguments in arguments.items():
-        if action_name == 'rcreate':
+        if action_name == 'rcreate' and action_name not in skip_actions:
             borgmatic.actions.rcreate.run_rcreate(
                 repository,
                 config,
@@ -295,7 +315,7 @@ def run_actions(
                 local_path,
                 remote_path,
             )
-        elif action_name == 'transfer':
+        elif action_name == 'transfer' and action_name not in skip_actions:
             borgmatic.actions.transfer.run_transfer(
                 repository,
                 config,
@@ -305,11 +325,12 @@ def run_actions(
                 local_path,
                 remote_path,
             )
-        elif action_name == 'create':
+        elif action_name == 'create' and action_name not in skip_actions:
             yield from borgmatic.actions.create.run_create(
                 config_filename,
                 repository,
                 config,
+                config_paths,
                 hook_context,
                 local_borg_version,
                 action_arguments,
@@ -318,7 +339,7 @@ def run_actions(
                 local_path,
                 remote_path,
             )
-        elif action_name == 'prune':
+        elif action_name == 'prune' and action_name not in skip_actions:
             borgmatic.actions.prune.run_prune(
                 config_filename,
                 repository,
@@ -331,7 +352,7 @@ def run_actions(
                 local_path,
                 remote_path,
             )
-        elif action_name == 'compact':
+        elif action_name == 'compact' and action_name not in skip_actions:
             borgmatic.actions.compact.run_compact(
                 config_filename,
                 repository,
@@ -344,7 +365,7 @@ def run_actions(
                 local_path,
                 remote_path,
             )
-        elif action_name == 'check':
+        elif action_name == 'check' and action_name not in skip_actions:
             if checks.repository_enabled_for_checks(repository, config):
                 borgmatic.actions.check.run_check(
                     config_filename,
@@ -357,7 +378,7 @@ def run_actions(
                     local_path,
                     remote_path,
                 )
-        elif action_name == 'extract':
+        elif action_name == 'extract' and action_name not in skip_actions:
             borgmatic.actions.extract.run_extract(
                 config_filename,
                 repository,
@@ -369,7 +390,7 @@ def run_actions(
                 local_path,
                 remote_path,
             )
-        elif action_name == 'export-tar':
+        elif action_name == 'export-tar' and action_name not in skip_actions:
             borgmatic.actions.export_tar.run_export_tar(
                 repository,
                 config,
@@ -379,7 +400,7 @@ def run_actions(
                 local_path,
                 remote_path,
             )
-        elif action_name == 'mount':
+        elif action_name == 'mount' and action_name not in skip_actions:
             borgmatic.actions.mount.run_mount(
                 repository,
                 config,
@@ -389,7 +410,7 @@ def run_actions(
                 local_path,
                 remote_path,
             )
-        elif action_name == 'restore':
+        elif action_name == 'restore' and action_name not in skip_actions:
             borgmatic.actions.restore.run_restore(
                 repository,
                 config,
@@ -399,7 +420,7 @@ def run_actions(
                 local_path,
                 remote_path,
             )
-        elif action_name == 'rlist':
+        elif action_name == 'rlist' and action_name not in skip_actions:
             yield from borgmatic.actions.rlist.run_rlist(
                 repository,
                 config,
@@ -409,7 +430,7 @@ def run_actions(
                 local_path,
                 remote_path,
             )
-        elif action_name == 'list':
+        elif action_name == 'list' and action_name not in skip_actions:
             yield from borgmatic.actions.list.run_list(
                 repository,
                 config,
@@ -419,7 +440,7 @@ def run_actions(
                 local_path,
                 remote_path,
             )
-        elif action_name == 'rinfo':
+        elif action_name == 'rinfo' and action_name not in skip_actions:
             yield from borgmatic.actions.rinfo.run_rinfo(
                 repository,
                 config,
@@ -429,7 +450,7 @@ def run_actions(
                 local_path,
                 remote_path,
             )
-        elif action_name == 'info':
+        elif action_name == 'info' and action_name not in skip_actions:
             yield from borgmatic.actions.info.run_info(
                 repository,
                 config,
@@ -439,7 +460,7 @@ def run_actions(
                 local_path,
                 remote_path,
             )
-        elif action_name == 'break-lock':
+        elif action_name == 'break-lock' and action_name not in skip_actions:
             borgmatic.actions.break_lock.run_break_lock(
                 repository,
                 config,
@@ -449,7 +470,7 @@ def run_actions(
                 local_path,
                 remote_path,
             )
-        elif action_name == 'export':
+        elif action_name == 'export' and action_name not in skip_actions:
             borgmatic.actions.export_key.run_export_key(
                 repository,
                 config,
@@ -459,7 +480,7 @@ def run_actions(
                 local_path,
                 remote_path,
             )
-        elif action_name == 'borg':
+        elif action_name == 'borg' and action_name not in skip_actions:
             borgmatic.actions.borg.run_borg(
                 repository,
                 config,
@@ -484,13 +505,15 @@ def load_configurations(config_filenames, overrides=None, resolve_env=True):
     '''
     Given a sequence of configuration filenames, load and validate each configuration file. Return
     the results as a tuple of: dict of configuration filename to corresponding parsed configuration,
-    and sequence of logging.LogRecord instances containing any parse errors.
+    a sequence of paths for all loaded configuration files (including includes), and a sequence of
+    logging.LogRecord instances containing any parse errors.
 
     Log records are returned here instead of being logged directly because logging isn't yet
     initialized at this point!
     '''
     # Dict mapping from config filename to corresponding parsed config dict.
     configs = collections.OrderedDict()
+    config_paths = set()
     logs = []
 
     # Parse and load each configuration file.
@@ -507,9 +530,10 @@ def load_configurations(config_filenames, overrides=None, resolve_env=True):
             ]
         )
         try:
-            configs[config_filename], parse_logs = validate.parse_configuration(
+            configs[config_filename], paths, parse_logs = validate.parse_configuration(
                 config_filename, validate.schema_filename(), overrides, resolve_env
             )
+            config_paths.update(paths)
             logs.extend(parse_logs)
         except PermissionError:
             logs.extend(
@@ -539,7 +563,7 @@ def load_configurations(config_filenames, overrides=None, resolve_env=True):
                 ]
             )
 
-    return (configs, logs)
+    return (configs, sorted(config_paths), logs)
 
 
 def log_record(suppress_log=False, **kwargs):
@@ -555,9 +579,6 @@ def log_record(suppress_log=False, **kwargs):
     return record
 
 
-MAX_CAPTURED_OUTPUT_LENGTH = 1000
-
-
 def log_error_records(
     message, error=None, levelno=logging.CRITICAL, log_command_error_output=False
 ):
@@ -579,20 +600,24 @@ def log_error_records(
         raise error
     except CalledProcessError as error:
         yield log_record(levelno=levelno, levelname=level_name, msg=message)
+
         if error.output:
             try:
                 output = error.output.decode('utf-8')
             except (UnicodeDecodeError, AttributeError):
                 output = error.output
 
-            # Suppress these logs for now and save full error output for the log summary at the end.
-            yield log_record(
-                levelno=levelno,
-                levelname=level_name,
-                msg=output[:MAX_CAPTURED_OUTPUT_LENGTH]
-                + ' ...' * (len(output) > MAX_CAPTURED_OUTPUT_LENGTH),
-                suppress_log=True,
-            )
+            # Suppress these logs for now and save the error output for the log summary at the end.
+            # Log a separate record per line, as some errors can be really verbose and overflow the
+            # per-record size limits imposed by some logging backends.
+            for output_line in output.splitlines():
+                yield log_record(
+                    levelno=levelno,
+                    levelname=level_name,
+                    msg=output_line,
+                    suppress_log=True,
+                )
+
         yield log_record(levelno=levelno, levelname=level_name, msg=error)
     except (ValueError, OSError) as error:
         yield log_record(levelno=levelno, levelname=level_name, msg=message)
@@ -705,12 +730,12 @@ def collect_highlander_action_summary_logs(configs, arguments, configuration_par
         return
 
 
-def collect_configuration_run_summary_logs(configs, arguments):
+def collect_configuration_run_summary_logs(configs, config_paths, arguments):
     '''
-    Given a dict of configuration filename to corresponding parsed configuration and parsed
-    command-line arguments as a dict from subparser name to a parsed namespace of arguments, run
-    each configuration file and yield a series of logging.LogRecord instances containing summary
-    information about each run.
+    Given a dict of configuration filename to corresponding parsed configuration, a sequence of
+    loaded configuration paths, and parsed command-line arguments as a dict from subparser name to a
+    parsed namespace of arguments, run each configuration file and yield a series of
+    logging.LogRecord instances containing summary information about each run.
 
     As a side effect of running through these configuration files, output their JSON results, if
     any, to stdout.
@@ -755,7 +780,7 @@ def collect_configuration_run_summary_logs(configs, arguments):
     # Execute the actions corresponding to each configuration file.
     json_results = []
     for config_filename, config in configs.items():
-        results = list(run_configuration(config_filename, config, arguments))
+        results = list(run_configuration(config_filename, config, config_paths, arguments))
         error_logs = tuple(result for result in results if isinstance(result, logging.LogRecord))
 
         if error_logs:
@@ -776,6 +801,7 @@ def collect_configuration_run_summary_logs(configs, arguments):
         logger.info(f"Unmounting mount point {arguments['umount'].mount_point}")
         try:
             borg_umount.unmount_archive(
+                config,
                 mount_point=arguments['umount'].mount_point,
                 local_path=get_local_path(configs),
             )
@@ -826,7 +852,7 @@ def main(extra_summary_logs=[]):  # pragma: no cover
 
     global_arguments = arguments['global']
     if global_arguments.version:
-        print(importlib_metadata.version('borgmatic'))
+        print(importlib.metadata.version('borgmatic'))
         sys.exit(0)
     if global_arguments.bash_completion:
         print(borgmatic.commands.completion.bash.bash_completion())
@@ -836,8 +862,7 @@ def main(extra_summary_logs=[]):  # pragma: no cover
         sys.exit(0)
 
     config_filenames = tuple(collect.collect_config_filenames(global_arguments.config_paths))
-    global_arguments.used_config_paths = list(config_filenames)
-    configs, parse_logs = load_configurations(
+    configs, config_paths, parse_logs = load_configurations(
         config_filenames, global_arguments.overrides, global_arguments.resolve_env
     )
     configuration_parse_errors = (
@@ -874,7 +899,7 @@ def main(extra_summary_logs=[]):  # pragma: no cover
                     configs, arguments, configuration_parse_errors
                 )
             )
-            or list(collect_configuration_run_summary_logs(configs, arguments))
+            or list(collect_configuration_run_summary_logs(configs, config_paths, arguments))
         )
     )
     summary_logs_max_level = max(log.levelno for log in summary_logs)

borgmatic/config/checks.py

@@ -1,9 +1,9 @@
-def repository_enabled_for_checks(repository, consistency):
+def repository_enabled_for_checks(repository, config):
     '''
-    Given a repository name and a consistency configuration dict, return whether the repository
-    is enabled to have consistency checks run.
+    Given a repository name and a configuration dict, return whether the
+    repository is enabled to have consistency checks run.
     '''
-    if not consistency.get('check_repositories'):
+    if not config.get('check_repositories'):
         return True
 
-    return repository in consistency['check_repositories']
+    return repository in config['check_repositories']

borgmatic/config/constants.py

@@ -0,0 +1,61 @@
+import shlex
+
+
+def coerce_scalar(value):
+    '''
+    Given a configuration value, coerce it to an integer or a boolean as appropriate and return the
+    result.
+    '''
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        pass
+
+    if value == 'true' or value == 'True':
+        return True
+    if value == 'false' or value == 'False':
+        return False
+
+    return value
+
+
+def apply_constants(value, constants, shell_escape=False):
+    '''
+    Given a configuration value (bool, dict, int, list, or string) and a dict of named constants,
+    replace any configuration string values of the form "{constant}" (or containing it) with the
+    value of the correspondingly named key from the constants. Recurse as necessary into nested
+    configuration to find values to replace.
+
+    For instance, if a configuration value contains "{foo}", replace it with the value of the "foo"
+    key found within the configuration's "constants".
+
+    If shell escape is True, then escape the constant's value before applying it.
+
+    Return the configuration value and modify the original.
+    '''
+    if not value or not constants:
+        return value
+
+    if isinstance(value, str):
+        for constant_name, constant_value in constants.items():
+            value = value.replace(
+                '{' + constant_name + '}',
+                shlex.quote(str(constant_value)) if shell_escape else str(constant_value),
+            )
+
+        # Support constants within non-string scalars by coercing the value to its appropriate type.
+        value = coerce_scalar(value)
+    elif isinstance(value, list):
+        for index, list_value in enumerate(value):
+            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)
+
+    return value

borgmatic/config/environment.py

@@ -1,21 +1,22 @@
 import os
 import re
 
-_VARIABLE_PATTERN = re.compile(
+VARIABLE_PATTERN = re.compile(
     r'(?P<escape>\\)?(?P<variable>\$\{(?P<name>[A-Za-z0-9_]+)((:?-)(?P<default>[^}]+))?\})'
 )
 
 
-def _resolve_string(matcher):
+def resolve_string(matcher):
     '''
-    Get the value from environment given a matcher containing a name and an optional default value.
-    If the variable is not defined in environment and no default value is provided, an Error is raised.
+    Given a matcher containing a name and an optional default value, get the value from environment.
+
+    Raise ValueError if the variable is not defined in environment and no default value is provided.
     '''
     if matcher.group('escape') is not None:
-        # in case of escaped envvar, unescape it
+        # In the case of an escaped environment variable, unescape it.
         return matcher.group('variable')
 
-    # resolve the env var
+    # Resolve the environment variable.
     name, default = matcher.group('name'), matcher.group('default')
     out = os.getenv(name, default=default)
 
@@ -27,19 +28,24 @@ def _resolve_string(matcher):
 
 def resolve_env_variables(item):
     '''
-    Resolves variables like or ${FOO} from given configuration with values from process environment
-    Supported formats:
-     - ${FOO} will return FOO env variable
-     - ${FOO-bar} or ${FOO:-bar} will return FOO env variable if it exists, else "bar"
+    Resolves variables like or ${FOO} from given configuration with values from process environment.
 
-    If any variable is missing in environment and no default value is provided, an Error is raised.
+    Supported formats:
+
+     * ${FOO} will return FOO env variable
+     * ${FOO-bar} or ${FOO:-bar} will return FOO env variable if it exists, else "bar"
+
+    Raise if any variable is missing in environment and no default value is provided.
     '''
     if isinstance(item, str):
-        return _VARIABLE_PATTERN.sub(_resolve_string, item)
+        return VARIABLE_PATTERN.sub(resolve_string, item)
+
     if isinstance(item, list):
-        for i, subitem in enumerate(item):
-            item[i] = resolve_env_variables(subitem)
+        for index, subitem in enumerate(item):
+            item[index] = resolve_env_variables(subitem)
+
     if isinstance(item, dict):
         for key, value in item.items():
             item[key] = resolve_env_variables(value)
+
     return item

borgmatic/config/generate.py

@@ -3,7 +3,7 @@ import io
 import os
 import re
 
-from ruamel import yaml
+import ruamel.yaml
 
 from borgmatic.config import load, normalize
 
@@ -17,7 +17,7 @@ def insert_newline_before_comment(config, field_name):
     field and its comments.
     '''
     config.ca.items[field_name][1].insert(
-        0, yaml.tokens.CommentToken('\n', yaml.error.CommentMark(0), None)
+        0, ruamel.yaml.tokens.CommentToken('\n', ruamel.yaml.error.CommentMark(0), None)
     )
 
 
@@ -32,12 +32,12 @@ def schema_to_sample_configuration(schema, level=0, parent_is_sequence=False):
         return example
 
     if schema_type == 'array':
-        config = yaml.comments.CommentedSeq(
+        config = ruamel.yaml.comments.CommentedSeq(
             [schema_to_sample_configuration(schema['items'], level, parent_is_sequence=True)]
         )
         add_comments_to_configuration_sequence(config, schema, indent=(level * INDENT))
     elif schema_type == 'object':
-        config = yaml.comments.CommentedMap(
+        config = ruamel.yaml.comments.CommentedMap(
             [
                 (field_name, schema_to_sample_configuration(sub_schema, level + 1))
                 for field_name, sub_schema in schema['properties'].items()
@@ -101,7 +101,7 @@ def render_configuration(config):
     '''
     Given a config data structure of nested OrderedDicts, render the config as YAML and return it.
     '''
-    dumper = yaml.YAML()
+    dumper = ruamel.yaml.YAML(typ='rt')
     dumper.indent(mapping=INDENT, sequence=INDENT + SEQUENCE_INDENT, offset=INDENT)
     rendered = io.StringIO()
     dumper.dump(config, rendered)
@@ -225,8 +225,7 @@ def merge_source_configuration_into_destination(destination_config, source_confi
     favoring values from the source when there are collisions.
 
     The purpose of this is to upgrade configuration files from old versions of borgmatic by adding
-    new
-    configuration keys and comments.
+    new configuration keys and comments.
     '''
     if not source_config:
         return destination_config
@@ -236,7 +235,9 @@ def merge_source_configuration_into_destination(destination_config, source_confi
     for field_name, source_value in source_config.items():
         # Since this key/value is from the source configuration, leave it uncommented and remove any
         # sentinel that would cause it to get commented out.
-        remove_commented_out_sentinel(destination_config, field_name)
+        remove_commented_out_sentinel(
+            ruamel.yaml.comments.CommentedMap(destination_config), field_name
+        )
 
         # This is a mapping. Recurse for this key/value.
         if isinstance(source_value, collections.abc.Mapping):
@@ -248,7 +249,7 @@ def merge_source_configuration_into_destination(destination_config, source_confi
         # This is a sequence. Recurse for each item in it.
         if isinstance(source_value, collections.abc.Sequence) and not isinstance(source_value, str):
             destination_value = destination_config[field_name]
-            destination_config[field_name] = yaml.comments.CommentedSeq(
+            destination_config[field_name] = ruamel.yaml.comments.CommentedSeq(
                 [
                     merge_source_configuration_into_destination(
                         destination_value[index] if index < len(destination_value) else None,
@@ -275,7 +276,7 @@ def generate_sample_configuration(
     schema. If a source filename is provided, merge the parsed contents of that configuration into
     the generated configuration.
     '''
-    schema = yaml.round_trip_load(open(schema_filename))
+    schema = ruamel.yaml.YAML(typ='safe').load(open(schema_filename))
     source_config = None
 
     if source_filename:

borgmatic/config/load.py

@@ -1,6 +1,5 @@
 import functools
 import itertools
-import json
 import logging
 import operator
 import os
@@ -10,18 +9,18 @@ import ruamel.yaml
 logger = logging.getLogger(__name__)
 
 
-def probe_and_include_file(filename, include_directories):
+def probe_and_include_file(filename, include_directories, config_paths):
     '''
-    Given a filename to include and a list of include directories to search for matching files,
-    probe for the file, load it, and return the loaded configuration as a data structure of nested
-    dicts, lists, etc.
+    Given a filename to include, a list of include directories to search for matching files, and a
+    set of configuration paths, probe for the file, load it, and return the loaded configuration as
+    a data structure of nested dicts, lists, etc. Add the filename to the given configuration paths.
 
     Raise FileNotFoundError if the included file was not found.
     '''
     expanded_filename = os.path.expanduser(filename)
 
     if os.path.isabs(expanded_filename):
-        return load_configuration(expanded_filename)
+        return load_configuration(expanded_filename, config_paths)
 
     candidate_filenames = {
         os.path.join(directory, expanded_filename) for directory in include_directories
@@ -29,32 +28,33 @@ def probe_and_include_file(filename, include_directories):
 
     for candidate_filename in candidate_filenames:
         if os.path.exists(candidate_filename):
-            return load_configuration(candidate_filename)
+            return load_configuration(candidate_filename, config_paths)
 
     raise FileNotFoundError(
         f'Could not find include {filename} at {" or ".join(candidate_filenames)}'
     )
 
 
-def include_configuration(loader, filename_node, include_directory):
+def include_configuration(loader, filename_node, include_directory, config_paths):
     '''
     Given a ruamel.yaml.loader.Loader, a ruamel.yaml.nodes.ScalarNode containing the included
-    filename (or a list containing multiple such filenames), and an include directory path to search
-    for matching files, load the given YAML filenames (ignoring the given loader so we can use our
-    own) and return their contents as data structure of nested dicts, lists, etc. If the given
+    filename (or a list containing multiple such filenames), an include directory path to search for
+    matching files, and a set of configuration paths, load the given YAML filenames (ignoring the
+    given loader so we can use our own) and return their contents as data structure of nested dicts,
+    lists, etc. Add the names of included files to the given configuration paths. If the given
     filename node's value is a scalar string, then the return value will be a single value. But if
     the given node value is a list, then the return value will be a list of values, one per loaded
     configuration file.
 
-    If a filename is relative, probe for it within 1. the current working directory and 2. the given
-    include directory.
+    If a filename is relative, probe for it within: 1. the current working directory and 2. the
+    given include directory.
 
     Raise FileNotFoundError if an included file was not found.
     '''
     include_directories = [os.getcwd(), os.path.abspath(include_directory)]
 
     if isinstance(filename_node.value, str):
-        return probe_and_include_file(filename_node.value, include_directories)
+        return probe_and_include_file(filename_node.value, include_directories, config_paths)
 
     if (
         isinstance(filename_node.value, list)
@@ -64,7 +64,7 @@ def include_configuration(loader, filename_node, include_directory):
         # Reversing the values ensures the correct ordering if these includes are subsequently
         # merged together.
         return [
-            probe_and_include_file(node.value, include_directories)
+            probe_and_include_file(node.value, include_directories, config_paths)
             for node in reversed(filename_node.value)
         ]
 
@@ -110,11 +110,17 @@ class Include_constructor(ruamel.yaml.SafeConstructor):
     separate YAML configuration files. Example syntax: `option: !include common.yaml`
     '''
 
-    def __init__(self, preserve_quotes=None, loader=None, include_directory=None):
+    def __init__(
+        self, preserve_quotes=None, loader=None, include_directory=None, config_paths=None
+    ):
         super(Include_constructor, self).__init__(preserve_quotes, loader)
         self.add_constructor(
             '!include',
-            functools.partial(include_configuration, include_directory=include_directory),
+            functools.partial(
+                include_configuration,
+                include_directory=include_directory,
+                config_paths=config_paths,
+            ),
         )
 
         # These are catch-all error handlers for tags that don't get applied and removed by
@@ -156,46 +162,36 @@ class Include_constructor(ruamel.yaml.SafeConstructor):
         node.value = deep_merge_nodes(node.value)
 
 
-def load_configuration(filename):
+def load_configuration(filename, config_paths=None):
     '''
     Load the given configuration file and return its contents as a data structure of nested dicts
-    and lists. Also, replace any "{constant}" strings with the value of the "constant" key in the
-    "constants" option of the configuration file.
+    and lists. Add the filename to the given configuration paths set, and also add any included
+    configuration filenames.
 
     Raise ruamel.yaml.error.YAMLError if something goes wrong parsing the YAML, or RecursionError
     if there are too many recursive includes.
     '''
+    if config_paths is None:
+        config_paths = set()
 
-    # Use an embedded derived class for the include constructor so as to capture the filename
-    # value. (functools.partial doesn't work for this use case because yaml.Constructor has to be
-    # an actual class.)
-    class Include_constructor_with_include_directory(Include_constructor):
+    # Use an embedded derived class for the include constructor so as to capture the include
+    # directory and configuration paths values. (functools.partial doesn't work for this use case
+    # because yaml.Constructor has to be an actual class.)
+    class Include_constructor_with_extras(Include_constructor):
         def __init__(self, preserve_quotes=None, loader=None):
-            super(Include_constructor_with_include_directory, self).__init__(
-                preserve_quotes, loader, include_directory=os.path.dirname(filename)
+            super(Include_constructor_with_extras, self).__init__(
+                preserve_quotes,
+                loader,
+                include_directory=os.path.dirname(filename),
+                config_paths=config_paths,
             )
 
     yaml = ruamel.yaml.YAML(typ='safe')
-    yaml.Constructor = Include_constructor_with_include_directory
+    yaml.Constructor = Include_constructor_with_extras
+    config_paths.add(filename)
 
     with open(filename) as file:
-        file_contents = file.read()
-        config = yaml.load(file_contents)
-
-        try:
-            has_constants = bool(config and 'constants' in config)
-        except TypeError:
-            has_constants = False
-
-        if has_constants:
-            for key, value in config['constants'].items():
-                value = json.dumps(value)
-                file_contents = file_contents.replace(f'{{{key}}}', value.strip('"'))
-
-            config = yaml.load(file_contents)
-            del config['constants']
-
-        return config
+        return yaml.load(file.read())
 
 
 def filter_omitted_nodes(nodes, values):

borgmatic/config/normalize.py

@@ -39,7 +39,7 @@ def normalize_sections(config_filename, config):
     for section_name in ('location', 'storage', 'retention', 'consistency', 'output', 'hooks'):
         section_config = config.get(section_name)
 
-        if section_config:
+        if section_config is not None:
             any_section_upgraded = True
             del config[section_name]
             config.update(section_config)
@@ -50,7 +50,7 @@ def normalize_sections(config_filename, config):
                 dict(
                     levelno=logging.WARNING,
                     levelname='WARNING',
-                    msg=f'{config_filename}: Configuration sections (like location: and storage:) are deprecated and support will be removed from a future release. To prepare for this, move your options out of sections to the global scope.',
+                    msg=f'{config_filename}: Configuration sections (like location:, storage:, retention:, consistency:, and hooks:) are deprecated and support will be removed from a future release. To prepare for this, move your options out of sections to the global scope.',
                 )
             )
         ]
@@ -90,7 +90,7 @@ def normalize(config_filename, config):
                 dict(
                     levelno=logging.WARNING,
                     levelname='WARNING',
-                    msg=f'{config_filename}: The healthchecks hook now expects a mapping value. String values for this option are deprecated and support will be removed from a future release.',
+                    msg=f'{config_filename}: The healthchecks hook now expects a key/value pair with "ping_url" as a key. String values for this option are deprecated and support will be removed from a future release.',
                 )
             )
         )
@@ -192,7 +192,7 @@ def normalize(config_filename, config):
     # Upgrade remote repositories to ssh:// syntax, required in Borg 2.
     repositories = config.get('repositories')
     if repositories:
-        if isinstance(repositories[0], str):
+        if any(isinstance(repository, str) for repository in repositories):
             logs.append(
                 logging.makeLogRecord(
                     dict(
@@ -202,7 +202,10 @@ def normalize(config_filename, config):
                     )
                 )
             )
-            config['repositories'] = [{'path': repository} for repository in repositories]
+            config['repositories'] = [
+                {'path': repository} if isinstance(repository, str) else repository
+                for repository in repositories
+            ]
             repositories = config['repositories']
 
         config['repositories'] = []

borgmatic/config/override.py

@@ -13,6 +13,11 @@ def set_values(config, keys, value):
 
     first_key = keys[0]
     if len(keys) == 1:
+        if isinstance(config, list):
+            raise ValueError(
+                'When overriding a list option, the value must use list syntax (e.g., "[foo, bar]" or "[{key: value}]" as appropriate)'
+            )
+
         config[first_key] = value
         return
 
@@ -22,13 +27,19 @@ def set_values(config, keys, value):
     set_values(config[first_key], keys[1:], value)
 
 
-def convert_value_type(value):
+def convert_value_type(value, option_type):
     '''
-    Given a string value, determine its logical type (string, boolean, integer, etc.), and return it
-    converted to that type.
+    Given a string value and its schema type as a string, determine its logical type (string,
+    boolean, integer, etc.), and return it converted to that type.
+
+    If the option type is a string, leave the value as a string so that special characters in it
+    don't get interpreted as YAML during conversion.
 
     Raise ruamel.yaml.error.YAMLError if there's a parse issue with the YAML.
     '''
+    if option_type == 'string':
+        return value
+
     return ruamel.yaml.YAML(typ='safe').load(io.StringIO(value))
 
 
@@ -46,11 +57,32 @@ def strip_section_names(parsed_override_key):
     return parsed_override_key
 
 
-def parse_overrides(raw_overrides):
+def type_for_option(schema, option_keys):
     '''
-    Given a sequence of configuration file override strings in the form of "option.suboption=value",
-    parse and return a sequence of tuples (keys, values), where keys is a sequence of strings. For
-    instance, given the following raw overrides:
+    Given a configuration schema and a sequence of keys identifying an option, e.g.
+    ('extra_borg_options', 'init'), return the schema type of that option as a string.
+
+    Return None if the option or its type cannot be found in the schema.
+    '''
+    option_schema = schema
+
+    for key in option_keys:
+        try:
+            option_schema = option_schema['properties'][key]
+        except KeyError:
+            return None
+
+    try:
+        return option_schema['type']
+    except KeyError:
+        return None
+
+
+def parse_overrides(raw_overrides, schema):
+    '''
+    Given a sequence of configuration file override strings in the form of "option.suboption=value"
+    and a configuration schema dict, parse and return a sequence of tuples (keys, values), where
+    keys is a sequence of strings. For instance, given the following raw overrides:
 
         ['my_option.suboption=value1', 'other_option=value2']
 
@@ -71,10 +103,13 @@ def parse_overrides(raw_overrides):
     for raw_override in raw_overrides:
         try:
             raw_keys, value = raw_override.split('=', 1)
+            keys = strip_section_names(tuple(raw_keys.split('.')))
+            option_type = type_for_option(schema, keys)
+
             parsed_overrides.append(
                 (
-                    strip_section_names(tuple(raw_keys.split('.'))),
-                    convert_value_type(value),
+                    keys,
+                    convert_value_type(value, option_type),
                 )
             )
         except ValueError:
@@ -87,12 +122,13 @@ def parse_overrides(raw_overrides):
     return tuple(parsed_overrides)
 
 
-def apply_overrides(config, raw_overrides):
+def apply_overrides(config, schema, raw_overrides):
     '''
-    Given a configuration dict and a sequence of configuration file override strings in the form of
-    "option.suboption=value", parse each override and set it the configuration dict.
+    Given a configuration dict, a corresponding configuration schema dict, and a sequence of
+    configuration file override strings in the form of "option.suboption=value", parse each override
+    and set it into the configuration dict.
     '''
-    overrides = parse_overrides(raw_overrides)
+    overrides = parse_overrides(raw_overrides, schema)
 
     for keys, value in overrides:
         set_values(config, keys, value)

borgmatic/config/schema.yaml

@@ -6,14 +6,15 @@ properties:
     constants:
         type: object
         description: |
-            Constants to use in the configuration file. All occurrences of the
-            constant name within curly braces will be replaced with the value.
-            For example, if you have a constant named "hostname" with the value
-            "myhostname", then the string "{hostname}" will be replaced with
-            "myhostname" in the configuration file.
+            Constants to use in the configuration file. Within option values,
+            all occurrences of the constant name in curly braces will be
+            replaced with the constant value. For example, if you have a
+            constant named "app_name" with the value "myapp", then the string
+            "{app_name}" will be replaced with "myapp" in the configuration
+            file.
         example:
-            hostname: myhostname
-            prefix: myprefix
+            app_name: myapp
+            user: myuser
     source_directories:
         type: array
         items:
@@ -216,7 +217,7 @@ properties:
             Store configuration files used to create a backup in the backup
             itself. Defaults to true. Changing this to false prevents "borgmatic
             bootstrap" from extracting configuration files from the backup.
-        example: true
+        example: false
     source_directories_must_exist:
         type: boolean
         description: |
@@ -287,14 +288,17 @@ properties:
     retry_wait:
         type: integer
         description: |
-            Wait time between retries (in seconds) to allow transient issues to
-            pass. Increases after each retry as a form of backoff. Defaults to 0
-            (no wait).
+            Wait time between retries (in seconds) to allow transient issues
+            to pass. Increases after each retry by that same wait time as a
+            form of backoff. Defaults to 0 (no wait).
         example: 10
     temporary_directory:
         type: string
         description: |
-            Directory where temporary files are stored. Defaults to $TMPDIR.
+            Directory where temporary Borg files are stored. Defaults to
+            $TMPDIR. See "Resource Usage" at
+            https://borgbackup.readthedocs.io/en/stable/usage/general.html for
+            details.
         example: /path/to/tmpdir
     ssh_command:
         type: string
@@ -337,6 +341,37 @@ properties:
             Path for Borg encryption key files. Defaults to
             $borg_base_directory/.config/borg/keys
         example: /path/to/base/config/keys
+    borg_exit_codes:
+        type: array
+        items:
+            type: object
+            required: ['code', 'treat_as']
+            additionalProperties: false
+            properties:
+                code:
+                    type: integer
+                    not: {enum: [0]}
+                    description: |
+                        The exit code for an existing Borg warning or error.
+                    example: 100
+                treat_as:
+                    type: string
+                    enum: ['error', 'warning']
+                    description: |
+                        Whether to consider the exit code as an error or as a
+                        warning in borgmatic.
+                    example: error
+        description: |
+            A list of Borg exit codes that should be elevated to errors or
+            squashed to warnings as indicated. By default, Borg error exit codes
+            (2 to 99) are treated as errors while warning exit codes (1 and
+            100+) are treated as warnings. Exit codes other than 1 and 2 are
+            only present in Borg 1.4.0+.
+        example:
+            - code: 13
+              treat_as: warning
+            - code: 100
+              treat_as: error
     umask:
         type: integer
         description: |
@@ -423,7 +458,9 @@ properties:
             command-line invocation.
     keep_within:
         type: string
-        description: Keep all archives within this time interval.
+        description: |
+            Keep all archives within this time interval. See "skip_actions" for
+            disabling pruning altogether.
         example: 3H
     keep_secondly:
         type: integer
@@ -479,13 +516,13 @@ properties:
                         - disabled
                     description: |
                         Name of consistency check to run: "repository",
-                        "archives", "data", and/or "extract". Set to "disabled"
-                        to disable all consistency checks. "repository" checks
-                        the consistency of the repository, "archives" checks all
-                        of the archives, "data" verifies the integrity of the
-                        data within the archives, and "extract" does an
-                        extraction dry-run of the most recent archive. Note that
-                        "data" implies "archives".
+                        "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
@@ -525,6 +562,38 @@ properties:
             Apply color to console output. Can be overridden with --no-color
             command-line flag. Defaults to true.
         example: false
+    skip_actions:
+        type: array
+        items:
+            type: string
+            enum:
+                - rcreate
+                - transfer
+                - prune
+                - compact
+                - create
+                - check
+                - extract
+                - config
+                - export-tar
+                - mount
+                - umount
+                - restore
+                - rlist
+                - list
+                - rinfo
+                - info
+                - break-lock
+                - key
+                - borg
+        description: |
+            List of one or more actions to skip running for this configuration
+            file, even if specified on the command-line (explicitly or
+            implicitly). This is handy for append-only configurations where you
+            never want to run "compact" or checkless configuration where you
+            want to skip "check". Defaults to not skipping any actions.
+        example:
+          - compact
     before_actions:
         type: array
         items:
@@ -1306,6 +1375,99 @@ properties:
                 example:
                     - start
                     - finish
+    apprise:
+        type: object
+        required: ['services']
+        additionalProperties: false
+        properties:
+            services:
+                type: array
+                items:
+                    type: object
+                    required:
+                        - url
+                        - label
+                    properties:
+                        url:
+                            type: string
+                            example: "gotify://hostname/token"
+                        label:
+                            type: string
+                            example: gotify
+                description: |
+                    A list of Apprise services to publish to with URLs and
+                    labels. The labels are used for logging. A full list of
+                    services and their configuration can be found at
+                    https://github.com/caronc/apprise/wiki.
+                example:
+                    - url: "kodi://user@hostname"
+                      label: kodi
+                    - url: "line://Token@User"
+                      label: line
+            start:
+                type: object
+                required: ['body']
+                properties:
+                    title:
+                        type: string
+                        description: |
+                            Specify the message title. If left unspecified, no
+                            title is sent.
+                        example: Ping!
+                    body:
+                        type: string
+                        description: |
+                            Specify the message body.
+                        example: Starting backup process.
+            finish:
+                type: object
+                required: ['body']
+                properties:
+                    title:
+                        type: string
+                        description: |
+                            Specify the message title. If left unspecified, no
+                            title is sent.
+                        example: Ping!
+                    body:
+                        type: string
+                        description: |
+                            Specify the message body.
+                        example: Backups successfully made.
+            fail:
+                type: object
+                required: ['body']
+                properties:
+                    title:
+                        type: string
+                        description: |
+                            Specify the message title. If left unspecified, no
+                            title is sent.
+                        example: Ping!
+                    body:
+                        type: string
+                        description: |
+                            Specify the message body.
+                        example: Your backups have failed.
+            states:
+                type: array
+                items:
+                    type: string
+                    enum:
+                        - start
+                        - finish
+                        - fail
+                    uniqueItems: true
+                description: |
+                    List of one or more monitoring states to ping for: "start",
+                    "finish", and/or "fail". Defaults to pinging for failure
+                    only. For each selected state, corresponding configuration
+                    for the message title and body should be given. If any is
+                    left unspecified, a generic message is emitted instead.
+                example:
+                    - start
+                    - finish
+
     healthchecks:
         type: object
         required: ['ping_url']
@@ -1400,6 +1562,36 @@ properties:
                     ends, or errors.
                 example: https://cronhub.io/ping/1f5e3410-254c-5587
         description: |
-            Configuration for a monitoring integration with Crunhub. Create an
+            Configuration for a monitoring integration with Cronhub. Create an
             account at https://cronhub.io if you'd like to use this service. See
             borgmatic monitoring documentation for details.
+    loki:
+        type: object
+        required: ['url', 'labels']
+        additionalProperties: false
+        properties:
+            url:
+                type: string
+                description: |
+                    Grafana loki log URL to notify when a backup begins,
+                    ends, or fails.
+                example: "http://localhost:3100/loki/api/v1/push"
+            labels:
+                type: object
+                additionalProperties:
+                    type: string
+                description: |
+                    Allows setting custom labels for the logging stream. At
+                    least one label is required. "__hostname" gets replaced by
+                    the machine hostname automatically. "__config" gets replaced
+                    by just the name of the configuration file. "__config_path"
+                    gets replaced by the full path of the configuration file.
+                example:
+                    app: "borgmatic"
+                    config: "__config"
+                    hostname: "__hostname"
+        description: |
+            Configuration for a monitoring integration with Grafana loki. You
+            can send the logs to a self-hosted instance or create an account at
+            https://grafana.com/auth/sign-up/create-user. See borgmatic
+            monitoring documentation for details.

borgmatic/config/validate.py

@@ -4,7 +4,7 @@ import jsonschema
 import ruamel.yaml
 
 import borgmatic.config
-from borgmatic.config import environment, load, normalize, override
+from borgmatic.config import constants, environment, load, normalize, override
 
 
 def schema_filename():
@@ -97,23 +97,28 @@ def parse_configuration(config_filename, schema_filename, overrides=None, resolv
             'checks': ['repository', 'archives'],
         }
 
-    Also return a sequence of logging.LogRecord instances containing any warnings about the
-    configuration.
+    Also return a set of loaded configuration paths and a sequence of logging.LogRecord instances
+    containing any warnings about the configuration.
 
     Raise FileNotFoundError if the file does not exist, PermissionError if the user does not
     have permissions to read the file, or Validation_error if the config does not match the schema.
     '''
+    config_paths = set()
+
     try:
-        config = load.load_configuration(config_filename)
+        config = load.load_configuration(config_filename, config_paths)
         schema = load.load_configuration(schema_filename)
     except (ruamel.yaml.error.YAMLError, RecursionError) as error:
         raise Validation_error(config_filename, (str(error),))
 
-    override.apply_overrides(config, overrides)
-    logs = normalize.normalize(config_filename, config)
+    override.apply_overrides(config, schema, overrides)
+    constants.apply_constants(config, config.get('constants') if config else {})
+
     if resolve_env:
         environment.resolve_env_variables(config)
 
+    logs = normalize.normalize(config_filename, config)
+
     try:
         validator = jsonschema.Draft7Validator(schema)
     except AttributeError:  # pragma: no cover
@@ -127,7 +132,7 @@ def parse_configuration(config_filename, schema_filename, overrides=None, resolv
 
     apply_logical_validation(config_filename, config)
 
-    return config, logs
+    return config, config_paths, logs
 
 
 def normalize_repository_path(repository):

borgmatic/execute.py

@@ -1,4 +1,5 @@
 import collections
+import enum
 import logging
 import os
 import select
@@ -8,22 +9,61 @@ logger = logging.getLogger(__name__)
 
 
 ERROR_OUTPUT_MAX_LINE_COUNT = 25
-BORG_ERROR_EXIT_CODE = 2
+BORG_ERROR_EXIT_CODE_START = 2
+BORG_ERROR_EXIT_CODE_END = 99
 
 
-def exit_code_indicates_error(command, exit_code, borg_local_path=None):
+class Exit_status(enum.Enum):
+    STILL_RUNNING = 1
+    SUCCESS = 2
+    WARNING = 3
+    ERROR = 4
+
+
+def interpret_exit_code(command, exit_code, borg_local_path=None, borg_exit_codes=None):
     '''
-    Return True if the given exit code from running a command corresponds to an error. If a Borg
-    local path is given and matches the process' command, then treat exit code 1 as a warning
-    instead of an error.
+    Return an Exit_status value (e.g. SUCCESS, ERROR, or WARNING) based on interpreting the given
+    exit code. If a Borg local path is given and matches the process' command, then interpret the
+    exit code based on Borg's documented exit code semantics. And if Borg exit codes are given as a
+    sequence of exit code configuration dicts, then take those configured preferences into account.
     '''
     if exit_code is None:
-        return False
+        return Exit_status.STILL_RUNNING
+    if exit_code == 0:
+        return Exit_status.SUCCESS
 
     if borg_local_path and command[0] == borg_local_path:
-        return bool(exit_code < 0 or exit_code >= BORG_ERROR_EXIT_CODE)
+        # First try looking for the exit code in the borg_exit_codes configuration.
+        for entry in borg_exit_codes or ():
+            if entry.get('code') == exit_code:
+                treat_as = entry.get('treat_as')
 
-    return bool(exit_code != 0)
+                if treat_as == 'error':
+                    logger.error(
+                        f'Treating exit code {exit_code} as an error, as per configuration'
+                    )
+                    return Exit_status.ERROR
+                elif treat_as == 'warning':
+                    logger.warning(
+                        f'Treating exit code {exit_code} as a warning, as per configuration'
+                    )
+                    return Exit_status.WARNING
+
+        # If the exit code doesn't have explicit configuration, then fall back to the default Borg
+        # behavior.
+        return (
+            Exit_status.ERROR
+            if (
+                exit_code < 0
+                or (
+                    exit_code >= BORG_ERROR_EXIT_CODE_START
+                    and exit_code <= BORG_ERROR_EXIT_CODE_END
+                )
+            )
+            else Exit_status.WARNING
+        )
+
+    return Exit_status.ERROR
 
 
 def command_for_process(process):
@@ -60,7 +100,7 @@ def append_last_lines(last_lines, captured_output, line, output_log_level):
         logger.log(output_log_level, line)
 
 
-def log_outputs(processes, exclude_stdouts, output_log_level, borg_local_path):
+def log_outputs(processes, exclude_stdouts, output_log_level, borg_local_path, borg_exit_codes):
     '''
     Given a sequence of subprocess.Popen() instances for multiple processes, log the output for each
     process with the requested log level. Additionally, raise a CalledProcessError if a process
@@ -68,7 +108,8 @@ def log_outputs(processes, exclude_stdouts, output_log_level, borg_local_path):
     path).
 
     If output log level is None, then instead of logging, capture output for each process and return
-    it as a dict from the process to its output.
+    it as a dict from the process to its output. Use the given Borg local path and exit code
+    configuration to decide what's an error and what's a warning.
 
     For simplicity, it's assumed that the output buffer for each process is its stdout. But if any
     stdouts are given to exclude, then for any matching processes, log from their stderr instead.
@@ -132,10 +173,13 @@ def log_outputs(processes, exclude_stdouts, output_log_level, borg_local_path):
 
             if exit_code is None:
                 still_running = True
+                command = process.args.split(' ') if isinstance(process.args, str) else process.args
+                continue
 
             command = process.args.split(' ') if isinstance(process.args, str) else process.args
-            # If any process errors, then raise accordingly.
-            if exit_code_indicates_error(command, exit_code, borg_local_path):
+            exit_status = interpret_exit_code(command, exit_code, borg_local_path, borg_exit_codes)
+
+            if exit_status in (Exit_status.ERROR, Exit_status.WARNING):
                 # If an error occurs, include its output in the raised exception so that we don't
                 # inadvertently hide error output.
                 output_buffer = output_buffer_for_process(process, exclude_stdouts)
@@ -161,9 +205,13 @@ def log_outputs(processes, exclude_stdouts, output_log_level, borg_local_path):
                         other_process.stdout.read(0)
                         other_process.kill()
 
-                raise subprocess.CalledProcessError(
-                    exit_code, command_for_process(process), '\n'.join(last_lines)
-                )
+                if exit_status == Exit_status.ERROR:
+                    raise subprocess.CalledProcessError(
+                        exit_code, command_for_process(process), '\n'.join(last_lines)
+                    )
+
+                still_running = False
+                break
 
     if captured_outputs:
         return {
@@ -171,19 +219,19 @@ def log_outputs(processes, exclude_stdouts, output_log_level, borg_local_path):
         }
 
 
-def log_command(full_command, input_file=None, output_file=None):
+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.
+    paths and extra environment variables (with omitted values in case they contain passwords).
     '''
     logger.debug(
-        ' '.join(full_command)
+        ' '.join(tuple(f'{key}=***' for key in (environment or {}).keys()) + tuple(full_command))
         + (f" < {getattr(input_file, 'name', '')}" if input_file else '')
         + (f" > {getattr(output_file, 'name', '')}" if output_file else '')
     )
 
 
-# An sentinel passed as an output file to execute_command() to indicate that the command's output
+# A sentinel passed as an output file to execute_command() to indicate that the command's output
 # should be allowed to flow through to stdout without being captured for logging. Useful for
 # commands with interactive prompts or those that mess directly with the console.
 DO_NOT_CAPTURE = object()
@@ -198,6 +246,7 @@ def execute_command(
     extra_environment=None,
     working_directory=None,
     borg_local_path=None,
+    borg_exit_codes=None,
     run_to_completion=True,
 ):
     '''
@@ -208,12 +257,13 @@ def execute_command(
     augment the current environment, and pass the result into the command. If a working directory is
     given, use that as the present working directory when running the command. If a Borg local path
     is given, and the command matches it (regardless of arguments), treat exit code 1 as a warning
-    instead of an error. If run to completion is False, then return the process for the command
-    without executing it to completion.
+    instead of an error. But if Borg exit codes are given as a sequence of exit code configuration
+    dicts, then use that configuration to decide what's an error and what's a warning. If run to
+    completion is False, then return the process for the command without executing it to completion.
 
     Raise subprocesses.CalledProcessError if an error occurs while running the command.
     '''
-    log_command(full_command, input_file, output_file)
+    log_command(full_command, input_file, output_file, extra_environment)
     environment = {**os.environ, **extra_environment} if extra_environment else None
     do_not_capture = bool(output_file is DO_NOT_CAPTURE)
     command = ' '.join(full_command) if shell else full_command
@@ -231,7 +281,11 @@ def execute_command(
         return process
 
     log_outputs(
-        (process,), (input_file, output_file), output_log_level, borg_local_path=borg_local_path
+        (process,),
+        (input_file, output_file),
+        output_log_level,
+        borg_local_path,
+        borg_exit_codes,
     )
 
 
@@ -242,6 +296,7 @@ def execute_command_and_capture_output(
     extra_environment=None,
     working_directory=None,
     borg_local_path=None,
+    borg_exit_codes=None,
 ):
     '''
     Execute the given command (a sequence of command/argument strings), capturing and returning its
@@ -250,11 +305,13 @@ def execute_command_and_capture_output(
     given, then use it to augment the current environment, and pass the result into the command. If
     a working directory is given, use that as the present working directory when running the
     command. If a Borg local path is given, and the command matches it (regardless of arguments),
-    treat exit code 1 as a warning instead of an error.
+    treat exit code 1 as a warning instead of an error. But if Borg exit codes are given as a
+    sequence of exit code configuration dicts, then use that configuration to decide what's an error
+    and what's a warning.
 
     Raise subprocesses.CalledProcessError if an error occurs while running the command.
     '''
-    log_command(full_command)
+    log_command(full_command, environment=extra_environment)
     environment = {**os.environ, **extra_environment} if extra_environment else None
     command = ' '.join(full_command) if shell else full_command
 
@@ -267,7 +324,10 @@ def execute_command_and_capture_output(
             cwd=working_directory,
         )
     except subprocess.CalledProcessError as error:
-        if exit_code_indicates_error(command, error.returncode, borg_local_path):
+        if (
+            interpret_exit_code(command, error.returncode, borg_local_path, borg_exit_codes)
+            == Exit_status.ERROR
+        ):
             raise
         output = error.output
 
@@ -284,6 +344,7 @@ def execute_command_with_processes(
     extra_environment=None,
     working_directory=None,
     borg_local_path=None,
+    borg_exit_codes=None,
 ):
     '''
     Execute the given command (a sequence of command/argument strings) and log its output at the
@@ -298,12 +359,14 @@ def execute_command_with_processes(
     use it to augment the current environment, and pass the result into the command. If a working
     directory is given, use that as the present working directory when running the command. If a
     Borg local path is given, then for any matching command or process (regardless of arguments),
-    treat exit code 1 as a warning instead of an error.
+    treat exit code 1 as a warning instead of an error. But if Borg exit codes are given as a
+    sequence of exit code configuration dicts, then use that configuration to decide what's an error
+    and what's a warning.
 
     Raise subprocesses.CalledProcessError if an error occurs while running the command or in the
     upstream process.
     '''
-    log_command(full_command, input_file, output_file)
+    log_command(full_command, input_file, output_file, extra_environment)
     environment = {**os.environ, **extra_environment} if extra_environment else None
     do_not_capture = bool(output_file is DO_NOT_CAPTURE)
     command = ' '.join(full_command) if shell else full_command
@@ -333,7 +396,8 @@ def execute_command_with_processes(
         tuple(processes) + (command_process,),
         (input_file, output_file),
         output_log_level,
-        borg_local_path=borg_local_path,
+        borg_local_path,
+        borg_exit_codes,
     )
 
     if output_log_level is None:

borgmatic/hooks/apprise.py

@@ -0,0 +1,79 @@
+import logging
+import operator
+
+logger = logging.getLogger(__name__)
+
+
+def initialize_monitor(
+    ping_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):
+    '''
+    Ping the configured Apprise service URLs. Use the given configuration filename in any log
+    entries. If this is a dry run, then don't actually ping anything.
+    '''
+    try:
+        import apprise
+        from apprise import NotifyFormat, NotifyType
+    except ImportError:  # pragma: no cover
+        logger.warning('Unable to import Apprise in monitoring hook')
+        return
+
+    state_to_notify_type = {
+        'start': NotifyType.INFO,
+        'finish': NotifyType.SUCCESS,
+        'fail': NotifyType.FAILURE,
+        'log': NotifyType.INFO,
+    }
+
+    run_states = hook_config.get('states', ['fail'])
+
+    if state.name.lower() not in run_states:
+        return
+
+    state_config = hook_config.get(
+        state.name.lower(),
+        {
+            'title': f'A borgmatic {state.name} event happened',
+            'body': f'A borgmatic {state.name} event happened',
+        },
+    )
+
+    if not hook_config.get('services'):
+        logger.info(f'{config_filename}: No Apprise services to ping')
+        return
+
+    dry_run_string = ' (dry run; not actually pinging)' if dry_run else ''
+    labels_string = ', '.join(map(operator.itemgetter('label'), hook_config.get('services')))
+    logger.info(f'{config_filename}: Pinging Apprise services: {labels_string}{dry_run_string}')
+
+    apprise_object = apprise.Apprise()
+    apprise_object.add(list(map(operator.itemgetter('url'), hook_config.get('services'))))
+
+    if dry_run:
+        return
+
+    result = apprise_object.notify(
+        title=state_config.get('title', ''),
+        body=state_config.get('body'),
+        body_format=NotifyFormat.TEXT,
+        notify_type=state_to_notify_type[state.name.lower()],
+    )
+
+    if result is False:
+        logger.warning(f'{config_filename}: Error sending some Apprise notifications')
+
+
+def destroy_monitor(
+    ping_url_or_uuid, config, config_filename, monitoring_log_level, dry_run
+):  # pragma: no cover
+    '''
+    No destruction is necessary for this monitor.
+    '''
+    pass

borgmatic/hooks/command.py

@@ -1,6 +1,7 @@
 import logging
 import os
 import re
+import shlex
 
 from borgmatic import execute
 
@@ -16,7 +17,7 @@ def interpolate_context(config_filename, hook_description, command, context):
     names/values, interpolate the values by "{name}" into the command and return the result.
     '''
     for name, value in context.items():
-        command = command.replace(f'{{{name}}}', str(value))
+        command = command.replace(f'{{{name}}}', shlex.quote(str(value)))
 
     for unsupported_variable in re.findall(r'{\w+}', command):
         logger.warning(

borgmatic/hooks/dispatch.py

@@ -1,9 +1,11 @@
 import logging
 
 from borgmatic.hooks import (
+    apprise,
     cronhub,
     cronitor,
     healthchecks,
+    loki,
     mariadb,
     mongodb,
     mysql,
@@ -16,6 +18,7 @@ from borgmatic.hooks import (
 logger = logging.getLogger(__name__)
 
 HOOK_NAME_TO_MODULE = {
+    'apprise': apprise,
     'cronhub': cronhub,
     'cronitor': cronitor,
     'healthchecks': healthchecks,
@@ -26,6 +29,7 @@ HOOK_NAME_TO_MODULE = {
     'pagerduty': pagerduty,
     'postgresql_databases': postgresql,
     'sqlite_databases': sqlite,
+    'loki': loki,
 }
 
 

borgmatic/hooks/dump.py

@@ -6,7 +6,7 @@ from borgmatic.borg.state import DEFAULT_BORGMATIC_SOURCE_DIRECTORY
 
 logger = logging.getLogger(__name__)
 
-DATABASE_HOOK_NAMES = (
+DATA_SOURCE_HOOK_NAMES = (
     'mariadb_databases',
     'mysql_databases',
     'mongodb_databases',
@@ -15,26 +15,26 @@ DATABASE_HOOK_NAMES = (
 )
 
 
-def make_database_dump_path(borgmatic_source_directory, database_hook_name):
+def make_data_source_dump_path(borgmatic_source_directory, data_source_hook_name):
     '''
-    Given a borgmatic source directory (or None) and a database hook name, construct a database dump
-    path.
+    Given a borgmatic source directory (or None) and a data source hook name, construct a data
+    source dump path.
     '''
     if not borgmatic_source_directory:
         borgmatic_source_directory = DEFAULT_BORGMATIC_SOURCE_DIRECTORY
 
-    return os.path.join(borgmatic_source_directory, database_hook_name)
+    return os.path.join(borgmatic_source_directory, data_source_hook_name)
 
 
-def make_database_dump_filename(dump_path, name, hostname=None):
+def make_data_source_dump_filename(dump_path, name, hostname=None):
     '''
-    Based on the given dump directory path, database name, and hostname, return a filename to use
-    for the database dump. The hostname defaults to localhost.
+    Based on the given dump directory path, data source name, and hostname, return a filename to use
+    for the data source dump. The hostname defaults to localhost.
 
-    Raise ValueError if the database name is invalid.
+    Raise ValueError if the data source name is invalid.
     '''
     if os.path.sep in name:
-        raise ValueError(f'Invalid database name {name}')
+        raise ValueError(f'Invalid data source name {name}')
 
     return os.path.join(os.path.expanduser(dump_path), hostname or 'localhost', name)
 
@@ -54,14 +54,14 @@ def create_named_pipe_for_dump(dump_path):
     os.mkfifo(dump_path, mode=0o600)
 
 
-def remove_database_dumps(dump_path, database_type_name, log_prefix, dry_run):
+def remove_data_source_dumps(dump_path, data_source_type_name, log_prefix, dry_run):
     '''
-    Remove all database dumps in the given dump directory path (including the directory itself). If
-    this is a dry run, then don't actually remove anything.
+    Remove all data source dumps in the given dump directory path (including the directory itself).
+    If this is a dry run, then don't actually remove anything.
     '''
     dry_run_label = ' (dry run; not actually removing anything)' if dry_run else ''
 
-    logger.debug(f'{log_prefix}: Removing {database_type_name} database dumps{dry_run_label}')
+    logger.debug(f'{log_prefix}: Removing {data_source_type_name} data source dumps{dry_run_label}')
 
     expanded_path = os.path.expanduser(dump_path)
 

borgmatic/hooks/loki.py

@@ -0,0 +1,154 @@
+import json
+import logging
+import os
+import platform
+import time
+
+import requests
+
+from borgmatic.hooks import monitor
+
+logger = logging.getLogger(__name__)
+
+MONITOR_STATE_TO_LOKI = {
+    monitor.State.START: 'Started',
+    monitor.State.FINISH: 'Finished',
+    monitor.State.FAIL: 'Failed',
+}
+
+# Threshold at which logs get flushed to loki
+MAX_BUFFER_LINES = 100
+
+
+class Loki_log_buffer:
+    '''
+    A log buffer that allows to output the logs as loki requests in json. Allows
+    adding labels to the log stream and takes care of communication with loki.
+    '''
+
+    def __init__(self, url, dry_run):
+        self.url = url
+        self.dry_run = dry_run
+        self.root = {'streams': [{'stream': {}, 'values': []}]}
+
+    def add_value(self, value):
+        '''
+        Add a log entry to the stream.
+        '''
+        timestamp = str(time.time_ns())
+        self.root['streams'][0]['values'].append((timestamp, value))
+
+    def add_label(self, label, value):
+        '''
+        Add a label to the logging stream.
+        '''
+        self.root['streams'][0]['stream'][label] = value
+
+    def to_request(self):
+        return json.dumps(self.root)
+
+    def __len__(self):
+        '''
+        Gets the number of lines currently in the buffer.
+        '''
+        return len(self.root['streams'][0]['values'])
+
+    def flush(self):
+        if self.dry_run:
+            # Just empty the buffer and skip
+            self.root['streams'][0]['values'] = []
+            logger.info('Skipped uploading logs to loki due to dry run')
+            return
+
+        if len(self) == 0:
+            # Skip as there are not logs to send yet
+            return
+
+        request_body = self.to_request()
+        self.root['streams'][0]['values'] = []
+        request_header = {'Content-Type': 'application/json'}
+
+        try:
+            result = requests.post(self.url, headers=request_header, data=request_body, timeout=5)
+            result.raise_for_status()
+        except requests.RequestException:
+            logger.warning('Failed to upload logs to loki')
+
+
+class Loki_log_handler(logging.Handler):
+    '''
+    A log handler that sends logs to loki.
+    '''
+
+    def __init__(self, url, dry_run):
+        super().__init__()
+        self.buffer = Loki_log_buffer(url, dry_run)
+
+    def emit(self, record):
+        '''
+        Add a log record from the logging module to the stream.
+        '''
+        self.raw(record.getMessage())
+
+    def add_label(self, key, value):
+        '''
+        Add a label to the logging stream.
+        '''
+        self.buffer.add_label(key, value)
+
+    def raw(self, msg):
+        '''
+        Add an arbitrary string as a log entry to the stream.
+        '''
+        self.buffer.add_value(msg)
+
+        if len(self.buffer) > MAX_BUFFER_LINES:
+            self.buffer.flush()
+
+    def flush(self):
+        '''
+        Send the logs to loki and empty the buffer.
+        '''
+        self.buffer.flush()
+
+
+def initialize_monitor(hook_config, config, config_filename, monitoring_log_level, dry_run):
+    '''
+    Add a handler to the root logger to regularly send the logs to loki.
+    '''
+    url = hook_config.get('url')
+    loki = Loki_log_handler(url, dry_run)
+
+    for key, value in hook_config.get('labels').items():
+        if value == '__hostname':
+            loki.add_label(key, platform.node())
+        elif value == '__config':
+            loki.add_label(key, os.path.basename(config_filename))
+        elif value == '__config_path':
+            loki.add_label(key, config_filename)
+        else:
+            loki.add_label(key, value)
+
+    logging.getLogger().addHandler(loki)
+
+
+def ping_monitor(hook_config, config, config_filename, state, monitoring_log_level, dry_run):
+    '''
+    Add an entry to the loki logger with the current state.
+    '''
+    for handler in tuple(logging.getLogger().handlers):
+        if isinstance(handler, Loki_log_handler):
+            if state in MONITOR_STATE_TO_LOKI.keys():
+                handler.raw(f'{config_filename}: {MONITOR_STATE_TO_LOKI[state]} backup')
+
+
+def destroy_monitor(hook_config, config, config_filename, monitoring_log_level, dry_run):
+    '''
+    Remove the monitor handler that was added to the root logger.
+    '''
+    logger = logging.getLogger()
+
+    for handler in tuple(logger.handlers):
+        if isinstance(handler, Loki_log_handler):
+            handler.flush()
+            logger.removeHandler(handler)

borgmatic/hooks/mariadb.py

@@ -16,7 +16,7 @@ def make_dump_path(config):  # pragma: no cover
     '''
     Make the dump path from the given configuration dict and the name of this hook.
     '''
-    return dump.make_database_dump_path(
+    return dump.make_data_source_dump_path(
         config.get('borgmatic_source_directory'), 'mariadb_databases'
     )
 
@@ -62,16 +62,17 @@ def execute_dump_command(
 ):
     '''
     Kick off a dump for the given MariaDB database (provided as a configuration dict) to a named
-    pipe constructed from the given dump path and database names. Use the given log prefix in any
+    pipe constructed from the given dump path and database name. Use the given log prefix in any
     log entries.
 
     Return a subprocess.Popen instance for the dump process ready to spew to a named pipe. But if
     this is a dry run, then don't actually dump anything and return None.
     '''
     database_name = database['name']
-    dump_filename = dump.make_database_dump_filename(
+    dump_filename = dump.make_data_source_dump_filename(
         dump_path, database['name'], database.get('hostname')
     )
+
     if os.path.exists(dump_filename):
         logger.warning(
             f'{log_prefix}: Skipping duplicate dump of MariaDB database "{database_name}" to {dump_filename}'
@@ -106,7 +107,7 @@ def execute_dump_command(
     )
 
 
-def dump_databases(databases, config, log_prefix, dry_run):
+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
     dicts, one dict describing each database as per the configuration schema. Use the given
@@ -165,49 +166,55 @@ def dump_databases(databases, config, log_prefix, dry_run):
     return [process for process in processes if process]
 
 
-def remove_database_dumps(databases, config, log_prefix, dry_run):  # pragma: no cover
+def remove_data_source_dumps(databases, config, log_prefix, dry_run):  # pragma: no cover
     '''
     Remove all database dump files for this hook regardless of the given databases. Use the given
     configuration dict to construct the destination path and the log prefix in any log entries. If
     this is a dry run, then don't actually remove anything.
     '''
-    dump.remove_database_dumps(make_dump_path(config), 'MariaDB', log_prefix, dry_run)
+    dump.remove_data_source_dumps(make_dump_path(config), 'MariaDB', log_prefix, dry_run)
 
 
-def make_database_dump_pattern(databases, config, log_prefix, name=None):  # pragma: no cover
+def make_data_source_dump_pattern(databases, config, log_prefix, name=None):  # pragma: no cover
     '''
     Given a sequence of configurations dicts, a configuration dict, a prefix to log with, and a
     database name to match, return the corresponding glob patterns to match the database dump in an
     archive.
     '''
-    return dump.make_database_dump_filename(make_dump_path(config), name, hostname='*')
+    return dump.make_data_source_dump_filename(make_dump_path(config), name, hostname='*')
 
 
-def restore_database_dump(
-    hook_config, config, log_prefix, database, dry_run, extract_process, connection_params
+def restore_data_source_dump(
+    hook_config, config, log_prefix, data_source, dry_run, extract_process, connection_params
 ):
     '''
-    Restore a database from the given extract stream. The database is supplied as a configuration
-    dict, but the given hook configuration is ignored. The given configuration dict is used to
-    construct the destination path, and the given log prefix is used for any log entries. If this is
-    a dry run, then don't actually restore anything. Trigger the given active extract process (an
-    instance of subprocess.Popen) to produce output to consume.
+    Restore a database from the given extract stream. The database is supplied as a data source
+    configuration dict, but the given hook configuration is ignored. The given configuration dict is
+    used to construct the destination path, and the given log prefix is used for any log entries. If
+    this is a dry run, then don't actually restore anything. Trigger the given active extract
+    process (an instance of subprocess.Popen) to produce output to consume.
     '''
     dry_run_label = ' (dry run; not actually restoring anything)' if dry_run else ''
-    hostname = connection_params['hostname'] or database.get(
-        'restore_hostname', database.get('hostname')
+    hostname = connection_params['hostname'] or data_source.get(
+        'restore_hostname', data_source.get('hostname')
     )
-    port = str(connection_params['port'] or database.get('restore_port', database.get('port', '')))
-    username = connection_params['username'] or database.get(
-        'restore_username', database.get('username')
+    port = str(
+        connection_params['port'] or data_source.get('restore_port', data_source.get('port', ''))
     )
-    password = connection_params['password'] or database.get(
-        'restore_password', database.get('password')
+    username = connection_params['username'] or data_source.get(
+        'restore_username', data_source.get('username')
+    )
+    password = connection_params['password'] or data_source.get(
+        'restore_password', data_source.get('password')
     )
 
     restore_command = (
         ('mariadb', '--batch')
-        + (tuple(database['restore_options'].split(' ')) if 'restore_options' in database else ())
+        + (
+            tuple(data_source['restore_options'].split(' '))
+            if 'restore_options' in data_source
+            else ()
+        )
         + (('--host', hostname) if hostname else ())
         + (('--port', str(port)) if port else ())
         + (('--protocol', 'tcp') if hostname or port else ())
@@ -215,7 +222,7 @@ def restore_database_dump(
     )
     extra_environment = {'MYSQL_PWD': password} if password else None
 
-    logger.debug(f"{log_prefix}: Restoring MariaDB database {database['name']}{dry_run_label}")
+    logger.debug(f"{log_prefix}: Restoring MariaDB database {data_source['name']}{dry_run_label}")
     if dry_run:
         return
 

borgmatic/hooks/mongodb.py

@@ -1,4 +1,5 @@
 import logging
+import shlex
 
 from borgmatic.execute import execute_command, execute_command_with_processes
 from borgmatic.hooks import dump
@@ -10,12 +11,12 @@ def make_dump_path(config):  # pragma: no cover
     '''
     Make the dump path from the given configuration dict and the name of this hook.
     '''
-    return dump.make_database_dump_path(
+    return dump.make_data_source_dump_path(
         config.get('borgmatic_source_directory'), 'mongodb_databases'
     )
 
 
-def dump_databases(databases, config, log_prefix, dry_run):
+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
     dicts, one dict describing each database as per the configuration schema. Use the configuration
@@ -31,7 +32,7 @@ def dump_databases(databases, config, log_prefix, dry_run):
     processes = []
     for database in databases:
         name = database['name']
-        dump_filename = dump.make_database_dump_filename(
+        dump_filename = dump.make_data_source_dump_filename(
             make_dump_path(config), name, database.get('hostname')
         )
         dump_format = database.get('format', 'archive')
@@ -62,62 +63,66 @@ def build_dump_command(database, dump_filename, dump_format):
 
     return (
         ('mongodump',)
-        + (('--out', dump_filename) if dump_format == 'directory' else ())
-        + (('--host', database['hostname']) if 'hostname' in database else ())
-        + (('--port', str(database['port'])) if 'port' in database else ())
-        + (('--username', database['username']) if 'username' in database else ())
-        + (('--password', database['password']) if 'password' in database else ())
+        + (('--out', shlex.quote(dump_filename)) if dump_format == 'directory' else ())
+        + (('--host', shlex.quote(database['hostname'])) if 'hostname' in database else ())
+        + (('--port', shlex.quote(str(database['port']))) if 'port' in database else ())
+        + (('--username', shlex.quote(database['username'])) if 'username' in database else ())
+        + (('--password', shlex.quote(database['password'])) if 'password' in database else ())
         + (
-            ('--authenticationDatabase', database['authentication_database'])
+            ('--authenticationDatabase', shlex.quote(database['authentication_database']))
             if 'authentication_database' in database
             else ()
         )
-        + (('--db', database['name']) if not all_databases else ())
-        + (tuple(database['options'].split(' ')) if 'options' in database else ())
-        + (('--archive', '>', dump_filename) if dump_format != 'directory' else ())
+        + (('--db', shlex.quote(database['name'])) if not all_databases else ())
+        + (
+            tuple(shlex.quote(option) for option in database['options'].split(' '))
+            if 'options' in database
+            else ()
+        )
+        + (('--archive', '>', shlex.quote(dump_filename)) if dump_format != 'directory' else ())
     )
 
 
-def remove_database_dumps(databases, config, log_prefix, dry_run):  # pragma: no cover
+def remove_data_source_dumps(databases, config, log_prefix, dry_run):  # pragma: no cover
     '''
     Remove all database dump files for this hook regardless of the given databases. Use the log
     prefix in any log entries. Use the given configuration dict to construct the destination path.
     If this is a dry run, then don't actually remove anything.
     '''
-    dump.remove_database_dumps(make_dump_path(config), 'MongoDB', log_prefix, dry_run)
+    dump.remove_data_source_dumps(make_dump_path(config), 'MongoDB', log_prefix, dry_run)
 
 
-def make_database_dump_pattern(databases, config, log_prefix, name=None):  # pragma: no cover
+def make_data_source_dump_pattern(databases, config, log_prefix, name=None):  # pragma: no cover
     '''
     Given a sequence of database configurations dicts, a configuration dict, a prefix to log with,
     and a database name to match, return the corresponding glob patterns to match the database dump
     in an archive.
     '''
-    return dump.make_database_dump_filename(make_dump_path(config), name, hostname='*')
+    return dump.make_data_source_dump_filename(make_dump_path(config), name, hostname='*')
 
 
-def restore_database_dump(
-    hook_config, config, log_prefix, database, dry_run, extract_process, connection_params
+def restore_data_source_dump(
+    hook_config, config, log_prefix, data_source, dry_run, extract_process, connection_params
 ):
     '''
-    Restore a database from the given extract stream. The database is supplied as a configuration
-    dict, but the given hook configuration is ignored. The given configuration dict is used to
-    construct the destination path, and the given log prefix is used for any log entries. If this is
-    a dry run, then don't actually restore anything. Trigger the given active extract process (an
-    instance of subprocess.Popen) to produce output to consume.
+    Restore a database from the given extract stream. The database is supplied as a data source
+    configuration dict, but the given hook configuration is ignored. The given configuration dict is
+    used to construct the destination path, and the given log prefix is used for any log entries. If
+    this is a dry run, then don't actually restore anything. Trigger the given active extract
+    process (an instance of subprocess.Popen) to produce output to consume.
 
     If the extract process is None, then restore the dump from the filesystem rather than from an
     extract stream.
     '''
     dry_run_label = ' (dry run; not actually restoring anything)' if dry_run else ''
-    dump_filename = dump.make_database_dump_filename(
-        make_dump_path(config), database['name'], database.get('hostname')
+    dump_filename = dump.make_data_source_dump_filename(
+        make_dump_path(config), data_source['name'], data_source.get('hostname')
     )
     restore_command = build_restore_command(
-        extract_process, database, dump_filename, connection_params
+        extract_process, data_source, dump_filename, connection_params
     )
 
-    logger.debug(f"{log_prefix}: Restoring MongoDB database {database['name']}{dry_run_label}")
+    logger.debug(f"{log_prefix}: Restoring MongoDB database {data_source['name']}{dry_run_label}")
     if dry_run:
         return
 

borgmatic/hooks/monitor.py

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

borgmatic/hooks/mysql.py

@@ -16,7 +16,9 @@ def make_dump_path(config):  # pragma: no cover
     '''
     Make the dump path from the given configuration dict and the name of this hook.
     '''
-    return dump.make_database_dump_path(config.get('borgmatic_source_directory'), 'mysql_databases')
+    return dump.make_data_source_dump_path(
+        config.get('borgmatic_source_directory'), 'mysql_databases'
+    )
 
 
 SYSTEM_DATABASE_NAMES = ('information_schema', 'mysql', 'performance_schema', 'sys')
@@ -60,16 +62,17 @@ def execute_dump_command(
 ):
     '''
     Kick off a dump for the given MySQL/MariaDB database (provided as a configuration dict) to a
-    named pipe constructed from the given dump path and database names. Use the given log prefix in
+    named pipe constructed from the given dump path and database name. Use the given log prefix in
     any log entries.
 
     Return a subprocess.Popen instance for the dump process ready to spew to a named pipe. But if
     this is a dry run, then don't actually dump anything and return None.
     '''
     database_name = database['name']
-    dump_filename = dump.make_database_dump_filename(
+    dump_filename = dump.make_data_source_dump_filename(
         dump_path, database['name'], database.get('hostname')
     )
+
     if os.path.exists(dump_filename):
         logger.warning(
             f'{log_prefix}: Skipping duplicate dump of MySQL database "{database_name}" to {dump_filename}'
@@ -104,7 +107,7 @@ def execute_dump_command(
     )
 
 
-def dump_databases(databases, config, log_prefix, dry_run):
+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
     of dicts, one dict describing each database as per the configuration schema. Use the given
@@ -162,49 +165,55 @@ def dump_databases(databases, config, log_prefix, dry_run):
     return [process for process in processes if process]
 
 
-def remove_database_dumps(databases, config, log_prefix, dry_run):  # pragma: no cover
+def remove_data_source_dumps(databases, config, log_prefix, dry_run):  # pragma: no cover
     '''
     Remove all database dump files for this hook regardless of the given databases. Use the given
     configuration dict to construct the destination path and the log prefix in any log entries. If
     this is a dry run, then don't actually remove anything.
     '''
-    dump.remove_database_dumps(make_dump_path(config), 'MySQL', log_prefix, dry_run)
+    dump.remove_data_source_dumps(make_dump_path(config), 'MySQL', log_prefix, dry_run)
 
 
-def make_database_dump_pattern(databases, config, log_prefix, name=None):  # pragma: no cover
+def make_data_source_dump_pattern(databases, config, log_prefix, name=None):  # pragma: no cover
     '''
     Given a sequence of configurations dicts, a configuration dict, a prefix to log with, and a
     database name to match, return the corresponding glob patterns to match the database dump in an
     archive.
     '''
-    return dump.make_database_dump_filename(make_dump_path(config), name, hostname='*')
+    return dump.make_data_source_dump_filename(make_dump_path(config), name, hostname='*')
 
 
-def restore_database_dump(
-    hook_config, config, log_prefix, database, dry_run, extract_process, connection_params
+def restore_data_source_dump(
+    hook_config, config, log_prefix, data_source, dry_run, extract_process, connection_params
 ):
     '''
-    Restore a database from the given extract stream. The database is supplied as a configuration
-    dict, but the given hook configuration is ignored. The given configuration dict is used to
-    construct the destination path, and the given log prefix is used for any log entries. If this is
-    a dry run, then don't actually restore anything. Trigger the given active extract process (an
-    instance of subprocess.Popen) to produce output to consume.
+    Restore a database from the given extract stream. The database is supplied as a data source
+    configuration dict, but the given hook configuration is ignored. The given configuration dict is
+    used to construct the destination path, and the given log prefix is used for any log entries. If
+    this is a dry run, then don't actually restore anything. Trigger the given active extract
+    process (an instance of subprocess.Popen) to produce output to consume.
     '''
     dry_run_label = ' (dry run; not actually restoring anything)' if dry_run else ''
-    hostname = connection_params['hostname'] or database.get(
-        'restore_hostname', database.get('hostname')
+    hostname = connection_params['hostname'] or data_source.get(
+        'restore_hostname', data_source.get('hostname')
     )
-    port = str(connection_params['port'] or database.get('restore_port', database.get('port', '')))
-    username = connection_params['username'] or database.get(
-        'restore_username', database.get('username')
+    port = str(
+        connection_params['port'] or data_source.get('restore_port', data_source.get('port', ''))
     )
-    password = connection_params['password'] or database.get(
-        'restore_password', database.get('password')
+    username = connection_params['username'] or data_source.get(
+        'restore_username', data_source.get('username')
+    )
+    password = connection_params['password'] or data_source.get(
+        'restore_password', data_source.get('password')
     )
 
     restore_command = (
         ('mysql', '--batch')
-        + (tuple(database['restore_options'].split(' ')) if 'restore_options' in database else ())
+        + (
+            tuple(data_source['restore_options'].split(' '))
+            if 'restore_options' in data_source
+            else ()
+        )
         + (('--host', hostname) if hostname else ())
         + (('--port', str(port)) if port else ())
         + (('--protocol', 'tcp') if hostname or port else ())
@@ -212,7 +221,7 @@ def restore_database_dump(
     )
     extra_environment = {'MYSQL_PWD': password} if password else None
 
-    logger.debug(f"{log_prefix}: Restoring MySQL database {database['name']}{dry_run_label}")
+    logger.debug(f"{log_prefix}: Restoring MySQL database {data_source['name']}{dry_run_label}")
     if dry_run:
         return
 

borgmatic/hooks/postgresql.py

@@ -18,7 +18,7 @@ def make_dump_path(config):  # pragma: no cover
     '''
     Make the dump path from the given configuration dict and the name of this hook.
     '''
-    return dump.make_database_dump_path(
+    return dump.make_data_source_dump_path(
         config.get('borgmatic_source_directory'), 'postgresql_databases'
     )
 
@@ -92,7 +92,7 @@ def database_names_to_dump(database, extra_environment, log_prefix, dry_run):
     )
 
 
-def dump_databases(databases, config, log_prefix, dry_run):
+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
     dicts, one dict describing each database as per the configuration schema. Use the given
@@ -126,7 +126,7 @@ def dump_databases(databases, config, log_prefix, dry_run):
             dump_format = database.get('format', None if database_name == 'all' else 'custom')
             default_dump_command = 'pg_dumpall' if database_name == 'all' else 'pg_dump'
             dump_command = database.get('pg_dump_command') or default_dump_command
-            dump_filename = dump.make_database_dump_filename(
+            dump_filename = dump.make_data_source_dump_filename(
                 dump_path, database_name, database.get('hostname')
             )
             if os.path.exists(dump_filename):
@@ -137,23 +137,31 @@ def dump_databases(databases, config, log_prefix, dry_run):
 
             command = (
                 (
-                    dump_command,
+                    shlex.quote(dump_command),
                     '--no-password',
                     '--clean',
                     '--if-exists',
                 )
-                + (('--host', database['hostname']) if 'hostname' in database else ())
-                + (('--port', str(database['port'])) if 'port' in database else ())
-                + (('--username', database['username']) if 'username' in database else ())
+                + (('--host', shlex.quote(database['hostname'])) if 'hostname' in database else ())
+                + (('--port', shlex.quote(str(database['port']))) if 'port' in database else ())
+                + (
+                    ('--username', shlex.quote(database['username']))
+                    if 'username' in database
+                    else ()
+                )
                 + (('--no-owner',) if database.get('no_owner', False) else ())
-                + (('--format', dump_format) if dump_format else ())
-                + (('--file', dump_filename) if dump_format == 'directory' else ())
-                + (tuple(database['options'].split(' ')) if 'options' in database else ())
-                + (() if database_name == 'all' else (database_name,))
+                + (('--format', shlex.quote(dump_format)) if dump_format else ())
+                + (('--file', shlex.quote(dump_filename)) if dump_format == 'directory' else ())
+                + (
+                    tuple(shlex.quote(option) for option in database['options'].split(' '))
+                    if 'options' in database
+                    else ()
+                )
+                + (() if database_name == 'all' else (shlex.quote(database_name),))
                 # Use shell redirection rather than the --file flag to sidestep synchronization issues
                 # when pg_dump/pg_dumpall tries to write to a named pipe. But for the directory dump
                 # format in a particular, a named destination is required, and redirection doesn't work.
-                + (('>', dump_filename) if dump_format != 'directory' else ())
+                + (('>', shlex.quote(dump_filename)) if dump_format != 'directory' else ())
             )
 
             logger.debug(
@@ -183,33 +191,33 @@ def dump_databases(databases, config, log_prefix, dry_run):
     return processes
 
 
-def remove_database_dumps(databases, config, log_prefix, dry_run):  # pragma: no cover
+def remove_data_source_dumps(databases, config, log_prefix, dry_run):  # pragma: no cover
     '''
     Remove all database dump files for this hook regardless of the given databases. Use the given
     configuration dict to construct the destination path and the log prefix in any log entries. If
     this is a dry run, then don't actually remove anything.
     '''
-    dump.remove_database_dumps(make_dump_path(config), 'PostgreSQL', log_prefix, dry_run)
+    dump.remove_data_source_dumps(make_dump_path(config), 'PostgreSQL', log_prefix, dry_run)
 
 
-def make_database_dump_pattern(databases, config, log_prefix, name=None):  # pragma: no cover
+def make_data_source_dump_pattern(databases, config, log_prefix, name=None):  # pragma: no cover
     '''
     Given a sequence of configurations dicts, a configuration dict, a prefix to log with, and a
     database name to match, return the corresponding glob patterns to match the database dump in an
     archive.
     '''
-    return dump.make_database_dump_filename(make_dump_path(config), name, hostname='*')
+    return dump.make_data_source_dump_filename(make_dump_path(config), name, hostname='*')
 
 
-def restore_database_dump(
-    hook_config, config, log_prefix, database, dry_run, extract_process, connection_params
+def restore_data_source_dump(
+    hook_config, config, log_prefix, data_source, dry_run, extract_process, connection_params
 ):
     '''
-    Restore a database from the given extract stream. The database is supplied as a configuration
-    dict, but the given hook configuration is ignored. The given configuration dict is used to
-    construct the destination path, and the given log prefix is used for any log entries. If this is
-    a dry run, then don't actually restore anything. Trigger the given active extract process (an
-    instance of subprocess.Popen) to produce output to consume.
+    Restore a database from the given extract stream. The database is supplied as a data source
+    configuration dict, but the given hook configuration is ignored. The given configuration dict is
+    used to construct the destination path, and the given log prefix is used for any log entries. If
+    this is a dry run, then don't actually restore anything. Trigger the given active extract
+    process (an instance of subprocess.Popen) to produce output to consume.
 
     If the extract process is None, then restore the dump from the filesystem rather than from an
     extract stream.
@@ -218,54 +226,66 @@ def restore_database_dump(
     hostname, port, username, and password.
     '''
     dry_run_label = ' (dry run; not actually restoring anything)' if dry_run else ''
-    hostname = connection_params['hostname'] or database.get(
-        'restore_hostname', database.get('hostname')
+    hostname = connection_params['hostname'] or data_source.get(
+        'restore_hostname', data_source.get('hostname')
     )
-    port = str(connection_params['port'] or database.get('restore_port', database.get('port', '')))
-    username = connection_params['username'] or database.get(
-        'restore_username', database.get('username')
+    port = str(
+        connection_params['port'] or data_source.get('restore_port', data_source.get('port', ''))
+    )
+    username = connection_params['username'] or data_source.get(
+        'restore_username', data_source.get('username')
     )
 
-    all_databases = bool(database['name'] == 'all')
-    dump_filename = dump.make_database_dump_filename(
-        make_dump_path(config), database['name'], database.get('hostname')
+    all_databases = bool(data_source['name'] == 'all')
+    dump_filename = dump.make_data_source_dump_filename(
+        make_dump_path(config), data_source['name'], data_source.get('hostname')
     )
-    psql_command = shlex.split(database.get('psql_command') or 'psql')
+    psql_command = shlex.split(data_source.get('psql_command') or 'psql')
     analyze_command = (
         tuple(psql_command)
         + ('--no-password', '--no-psqlrc', '--quiet')
         + (('--host', hostname) if hostname else ())
         + (('--port', port) if port else ())
         + (('--username', username) if username else ())
-        + (('--dbname', database['name']) if not all_databases else ())
-        + (tuple(database['analyze_options'].split(' ')) if 'analyze_options' in database else ())
+        + (('--dbname', data_source['name']) if not all_databases else ())
+        + (
+            tuple(data_source['analyze_options'].split(' '))
+            if 'analyze_options' in data_source
+            else ()
+        )
         + ('--command', 'ANALYZE')
     )
-    use_psql_command = all_databases or database.get('format') == 'plain'
-    pg_restore_command = shlex.split(database.get('pg_restore_command') or 'pg_restore')
+    use_psql_command = all_databases or data_source.get('format') == 'plain'
+    pg_restore_command = shlex.split(data_source.get('pg_restore_command') or 'pg_restore')
     restore_command = (
         tuple(psql_command if use_psql_command else pg_restore_command)
         + ('--no-password',)
         + (('--no-psqlrc',) if use_psql_command else ('--if-exists', '--exit-on-error', '--clean'))
-        + (('--dbname', database['name']) if not all_databases else ())
+        + (('--dbname', data_source['name']) if not all_databases else ())
         + (('--host', hostname) if hostname else ())
         + (('--port', port) if port else ())
         + (('--username', username) if username else ())
-        + (('--no-owner',) if database.get('no_owner', False) else ())
-        + (tuple(database['restore_options'].split(' ')) if 'restore_options' in database else ())
+        + (('--no-owner',) if data_source.get('no_owner', False) else ())
+        + (
+            tuple(data_source['restore_options'].split(' '))
+            if 'restore_options' in data_source
+            else ()
+        )
         + (() if extract_process else (dump_filename,))
         + tuple(
-            itertools.chain.from_iterable(('--schema', schema) for schema in database['schemas'])
-            if database.get('schemas')
+            itertools.chain.from_iterable(('--schema', schema) for schema in data_source['schemas'])
+            if data_source.get('schemas')
             else ()
         )
     )
 
     extra_environment = make_extra_environment(
-        database, restore_connection_params=connection_params
+        data_source, restore_connection_params=connection_params
     )
 
-    logger.debug(f"{log_prefix}: Restoring PostgreSQL database {database['name']}{dry_run_label}")
+    logger.debug(
+        f"{log_prefix}: Restoring PostgreSQL database {data_source['name']}{dry_run_label}"
+    )
     if dry_run:
         return
 

borgmatic/hooks/sqlite.py

@@ -1,5 +1,6 @@
 import logging
 import os
+import shlex
 
 from borgmatic.execute import execute_command, execute_command_with_processes
 from borgmatic.hooks import dump
@@ -11,17 +12,19 @@ def make_dump_path(config):  # pragma: no cover
     '''
     Make the dump path from the given configuration dict and the name of this hook.
     '''
-    return dump.make_database_dump_path(
+    return dump.make_data_source_dump_path(
         config.get('borgmatic_source_directory'), 'sqlite_databases'
     )
 
 
-def dump_databases(databases, config, log_prefix, dry_run):
+def dump_data_sources(databases, config, log_prefix, dry_run):
     '''
-    Dump the given SQLite3 databases to a file. The databases are supplied as a sequence of
+    Dump the given SQLite3 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. If this is a dry
-    run, then don't actually dump anything.
+    construct the destination path and the given log prefix in any log entries.
+
+    Return a sequence of subprocess.Popen instances for the dump processes ready to spew to a named
+    pipe. But if this is a dry run, then don't actually dump anything and return an empty sequence.
     '''
     dry_run_label = ' (dry run; not actually dumping anything)' if dry_run else ''
     processes = []
@@ -39,7 +42,8 @@ def dump_databases(databases, config, log_prefix, dry_run):
             )
 
         dump_path = make_dump_path(config)
-        dump_filename = dump.make_database_dump_filename(dump_path, database['name'])
+        dump_filename = dump.make_data_source_dump_filename(dump_path, database['name'])
+
         if os.path.exists(dump_filename):
             logger.warning(
                 f'{log_prefix}: Skipping duplicate dump of SQLite database at {database_path} to {dump_filename}'
@@ -48,10 +52,10 @@ def dump_databases(databases, config, log_prefix, dry_run):
 
         command = (
             'sqlite3',
-            database_path,
+            shlex.quote(database_path),
             '.dump',
             '>',
-            dump_filename,
+            shlex.quote(dump_filename),
         )
         logger.debug(
             f'{log_prefix}: Dumping SQLite database at {database_path} to {dump_filename}{dry_run_label}'
@@ -59,43 +63,43 @@ def dump_databases(databases, config, log_prefix, dry_run):
         if dry_run:
             continue
 
-        dump.create_parent_directory_for_dump(dump_filename)
+        dump.create_named_pipe_for_dump(dump_filename)
         processes.append(execute_command(command, shell=True, run_to_completion=False))
 
     return processes
 
 
-def remove_database_dumps(databases, config, log_prefix, dry_run):  # pragma: no cover
+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
     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.
     '''
-    dump.remove_database_dumps(make_dump_path(config), 'SQLite', log_prefix, dry_run)
+    dump.remove_data_source_dumps(make_dump_path(config), 'SQLite', log_prefix, dry_run)
 
 
-def make_database_dump_pattern(databases, config, log_prefix, name=None):  # pragma: no cover
+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.
     '''
-    return dump.make_database_dump_filename(make_dump_path(config), name)
+    return dump.make_data_source_dump_filename(make_dump_path(config), name)
 
 
-def restore_database_dump(
-    hook_config, config, log_prefix, database, dry_run, extract_process, connection_params
+def restore_data_source_dump(
+    hook_config, config, log_prefix, data_source, dry_run, extract_process, connection_params
 ):
     '''
-    Restore a database from the given extract stream. The database is supplied as a configuration
-    dict, but the given hook configuration is ignored. The given configuration dict is used to
-    construct the destination path, and the given log prefix is used for any log entries. If this is
-    a dry run, then don't actually restore anything. Trigger the given active extract process (an
-    instance of subprocess.Popen) to produce output to consume.
+    Restore a database from the given extract stream. The database is supplied as a data source
+    configuration dict, but the given hook configuration is ignored. The given configuration dict is
+    used to construct the destination path, and the given log prefix is used for any log entries. If
+    this is a dry run, then don't actually restore anything. Trigger the given active extract
+    process (an instance of subprocess.Popen) to produce output to consume.
     '''
     dry_run_label = ' (dry run; not actually restoring anything)' if dry_run else ''
-    database_path = connection_params['restore_path'] or database.get(
-        'restore_path', database.get('path')
+    database_path = connection_params['restore_path'] or data_source.get(
+        'restore_path', data_source.get('path')
     )
 
     logger.debug(f'{log_prefix}: Restoring SQLite database at {database_path}{dry_run_label}')

borgmatic/logger.py

@@ -166,15 +166,15 @@ def configure_logging(
 
     Raise FileNotFoundError or PermissionError if the log file could not be opened for writing.
     '''
+    add_custom_log_levels()
+
     if syslog_log_level is None:
-        syslog_log_level = console_log_level
+        syslog_log_level = logging.DISABLED
     if log_file_log_level is None:
         log_file_log_level = console_log_level
     if monitoring_log_level is None:
         monitoring_log_level = console_log_level
 
-    add_custom_log_levels()
-
     # Log certain log levels to console stderr and others to stdout. This supports use cases like
     # grepping (non-error) output.
     console_disabled = logging.NullHandler()
@@ -194,8 +194,11 @@ def configure_logging(
     console_handler.setFormatter(Console_color_formatter())
     console_handler.setLevel(console_log_level)
 
-    syslog_path = None
-    if log_file is None and syslog_log_level != logging.DISABLED:
+    handlers = [console_handler]
+
+    if syslog_log_level != logging.DISABLED:
+        syslog_path = None
+
         if os.path.exists('/dev/log'):
             syslog_path = '/dev/log'
         elif os.path.exists('/var/run/syslog'):
@@ -203,14 +206,15 @@ def configure_logging(
         elif os.path.exists('/var/run/log'):
             syslog_path = '/var/run/log'
 
-    if syslog_path and not interactive_console():
-        syslog_handler = logging.handlers.SysLogHandler(address=syslog_path)
-        syslog_handler.setFormatter(
-            logging.Formatter('borgmatic: {levelname} {message}', style='{')  # noqa: FS003
-        )
-        syslog_handler.setLevel(syslog_log_level)
-        handlers = (console_handler, syslog_handler)
-    elif log_file and log_file_log_level != logging.DISABLED:
+        if syslog_path:
+            syslog_handler = logging.handlers.SysLogHandler(address=syslog_path)
+            syslog_handler.setFormatter(
+                logging.Formatter('borgmatic: {levelname} {message}', style='{')  # noqa: FS003
+            )
+            syslog_handler.setLevel(syslog_log_level)
+            handlers.append(syslog_handler)
+
+    if log_file and log_file_log_level != logging.DISABLED:
         file_handler = logging.handlers.WatchedFileHandler(log_file)
         file_handler.setFormatter(
             logging.Formatter(
@@ -218,11 +222,9 @@ def configure_logging(
             )
         )
         file_handler.setLevel(log_file_log_level)
-        handlers = (console_handler, file_handler)
-    else:
-        handlers = (console_handler,)
+        handlers.append(file_handler)
 
     logging.basicConfig(
-        level=min(console_log_level, syslog_log_level, log_file_log_level, monitoring_log_level),
+        level=min(handler.level for handler in handlers),
         handlers=handlers,
     )

borgmatic/signals.py

@@ -23,12 +23,20 @@ def handle_signal(signal_number, frame):
     if signal_number == signal.SIGTERM:
         logger.critical('Exiting due to TERM signal')
         sys.exit(EXIT_CODE_FROM_SIGNAL + signal.SIGTERM)
+    elif signal_number == signal.SIGINT:
+        raise KeyboardInterrupt()
 
 
 def configure_signals():
     '''
     Configure borgmatic's signal handlers to pass relevant signals through to any child processes
-    like Borg. Note that SIGINT gets passed through even without these changes.
+    like Borg.
     '''
-    for signal_number in (signal.SIGHUP, signal.SIGTERM, signal.SIGUSR1, signal.SIGUSR2):
+    for signal_number in (
+        signal.SIGHUP,
+        signal.SIGINT,
+        signal.SIGTERM,
+        signal.SIGUSR1,
+        signal.SIGUSR2,
+    ):
         signal.signal(signal_number, handle_signal)

docs/_includes/components/toc.css

@@ -2,13 +2,13 @@
 	font-size: 1rem; /* Reset */
 }
 .elv-toc details {
-	--details-force-closed: (max-width: 63.9375em); /* 1023px */
+	--details-force-closed: (max-width: 79.9375em); /* 1023px */
 }
 .elv-toc details > summary {
 	font-size: 1.375rem; /* 22px /16 */
 	margin-bottom: .5em;
 }
-@media (min-width: 64em) { /* 1024px */
+@media (min-width: 80em) {
 	.elv-toc {
 		position: absolute;
 		left: 3rem;

docs/_includes/index.css

@@ -121,7 +121,7 @@ main h1:first-child,
 main .elv-toc + h1 {
 	border-bottom: 2px dotted #666;
 }
-@media (min-width: 64em) { /* 1024px */
+@media (min-width: 80em) {
 	main .elv-toc + h1,
 	main .elv-toc + h2 {
 		margin-top: 0;
@@ -243,10 +243,10 @@ footer.elv-layout {
 .elv-layout-full {
 	max-width: none;
 }
-@media (min-width: 64em) { /* 1024px */
+@media (min-width: 80em) {
 	.elv-layout-toc {
 		padding-left: 15rem;
-		max-width: 60rem;
+		max-width: 76rem;
 		margin-right: 1rem;
 		position: relative;
 	}

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

@@ -126,7 +126,7 @@ for more information.
 ## Hook output
 
 Any output produced by your hooks shows up both at the console and in syslog
-(when run in a non-interactive console). For more information, read about <a
+(when enabled). For more information, read about <a
 href="https://torsion.org/borgmatic/docs/how-to/inspect-your-backups/">inspecting
 your backups</a>.
 

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

@@ -0,0 +1,86 @@
+---
+title: How to customize warnings and errors
+eleventyNavigation:
+  key: 💥 Customize warnings/errors
+  parent: How-to guides
+  order: 12
+---
+## When things go wrong
+
+After Borg runs, it indicates whether it succeeded via its exit code, a
+numeric ID indicating success, warning, or error. borgmatic consumes this exit
+code to decide how to respond. Normally, a Borg error results in a borgmatic
+error, while a Borg warning or success doesn't.
+
+But if that default behavior isn't sufficient for your needs, you can
+customize how borgmatic interprets [Borg's exit
+codes](https://borgbackup.readthedocs.io/en/stable/usage/general.html#return-codes).
+For instance, to elevate Borg warnings to errors, thereby causing borgmatic to
+error on them, use the following borgmatic configuration:
+
+```yaml
+borg_exit_codes:
+   - exit_code: 1
+     treat_as: error
+```
+
+Be aware though that Borg exits with a warning code for a variety of benign
+situations such as files changing while they're being read, so this example
+may not meet your needs. Keep reading though for more granular exit code
+configuration.
+
+Here's an example that squashes Borg errors to warnings:
+
+```yaml
+borg_exit_codes:
+   - exit_code: 2
+     treat_as: warning
+```
+
+Be careful with this example though, because it prevents borgmatic from
+erroring when Borg errors, which may not be desirable.
+
+
+### More granular configuration
+
+<span class="minilink minilink-addedin">New in Borg version 1.4</span> Borg
+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).
+The `rc:` numeric value there tells you the exit code for each.
+
+For instance, this borgmatic configuration elevates all Borg backup file
+permission warnings (exit code `105`)—and only those warnings—to errors:
+
+```yaml
+borg_exit_codes:
+   - exit_code: 105
+     treat_as: error
+```
+
+The following configuration does that *and* elevates backup file not found
+warnings (exit code `107`) to errors as well:
+
+```yaml
+borg_exit_codes:
+   - exit_code: 105
+     treat_as: error
+   - exit_code: 107
+     treat_as: error
+```
+
+If you don't know the exit code for a particular Borg error or warning you're
+experiencing, you can usually find it in your borgmatic output when
+`--verbosity 2` is enabled. For instance, here's a snippet of that output when
+a backup file is not found:
+
+```
+/noexist: stat: [Errno 2] No such file or directory: '/noexist'
+...
+terminating with warning status, rc 107
+```
+
+So if you want to configure borgmatic to treat this as an error instead of a
+warning, the exit status to use is `107`.

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

@@ -51,6 +51,11 @@ cron job), while only running expensive consistency checks with `check` on a
 much less frequent basis (e.g. with `borgmatic check` called from a separate
 cron job).
 
+<span class="minilink minilink-addedin">New in version 1.8.5</span> Instead of
+(or in addition to) specifying actions on the command-line, you can configure
+borgmatic to [skip particular
+actions](https://torsion.org/borgmatic/docs/how-to/set-up-backups/#skipping-actions).
+
 
 ### Consistency check configuration
 
@@ -116,8 +121,17 @@ this option in the `consistency:` section of your configuration.
 
 This tells borgmatic to run the `repository` consistency check at most once
 every two weeks for a given repository and the `archives` check at most once a
-month. The `frequency` value is a number followed by a unit of time, e.g. "3
-days", "1 week", "2 months", etc.
+month. The `frequency` value is a number followed by a unit of time, e.g. `3
+days`, `1 week`, `2 months`, etc. The set of possible time units is as
+follows (singular or plural):
+
+ * `second`
+ * `minute`
+ * `hour`
+ * `day`
+ * `week` (7 days)
+ * `month` (30 days)
+ * `year` (365 days)
 
 The `frequency` defaults to `always` for a check configured without a
 `frequency`, which means run this check every time checks run. But if you omit
@@ -139,6 +153,10 @@ though—or the most frequently configured check will apply.
 If you want to temporarily ignore your configured frequencies, you can invoke
 `borgmatic check --force` to run checks unconditionally.
 
+<span class="minilink minilink-addedin">New in version 1.8.6</span> `borgmatic
+check --force` runs `check` even if it's specified in the `skip_actions`
+option.
+
 
 ### Running only checks
 
@@ -162,7 +180,16 @@ location:
 If that's still too slow, you can disable consistency checks entirely,
 either for a single repository or for all repositories.
 
-Disabling all consistency checks looks like this:
+<span class="minilink minilink-addedin">New in version 1.8.5</span> Disabling
+all consistency checks looks like this:
+
+```yaml
+skip_actions:
+    - check
+```
+
+<span class="minilink minilink-addedin">Prior to version 1.8.5</span> Use this
+configuration instead:
 
 ```yaml
 checks:
@@ -170,10 +197,10 @@ checks:
 ```
 
 <span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
-this option in the `consistency:` section of your configuration.
+`checks:` in the `consistency:` section of your configuration.
 
-<span class="minilink minilink-addedin">Prior to version 1.6.2</span> `checks`
-was a plain list of strings without the `name:` part. For instance:
+<span class="minilink minilink-addedin">Prior to version 1.6.2</span>
+`checks:` was a plain list of strings without the `name:` part. For instance:
 
 ```yaml
 checks:

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

@@ -3,11 +3,16 @@ title: How to develop on borgmatic
 eleventyNavigation:
   key: 🏗️ Develop on borgmatic
   parent: How-to guides
-  order: 13
+  order: 14
 ---
 ## Source code
 
-To get set up to develop on borgmatic, first clone it via HTTPS or SSH:
+To get set up to develop on borgmatic, first [`install
+pipx`](https://torsion.org/borgmatic/docs/how-to/set-up-backups/#installation)
+to make managing your borgmatic environment easy without impacting other
+Python applications on your system.
+
+Then, clone borgmatic via HTTPS or SSH:
 
 ```bash
 git clone https://projects.torsion.org/borgmatic-collective/borgmatic.git
@@ -19,39 +24,34 @@ Or:
 git clone ssh://git@projects.torsion.org:3022/borgmatic-collective/borgmatic.git
 ```
 
-Then, install borgmatic
-"[editable](https://pip.pypa.io/en/stable/cli/pip_install/#editable-installs)"
+Finally, install borgmatic
+"[editable](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs)"
 so that you can run borgmatic actions during development to make sure your
-changes work.
+changes work:
 
 ```bash
 cd borgmatic
-pip3 install --user --editable .
+pipx ensurepath
+pipx install --editable .
 ```
 
-Note that this will typically install the borgmatic commands into
-`~/.local/bin`, which may or may not be on your PATH. There are other ways to
-install borgmatic editable as well, for instance into the system Python
-install (so without `--user`, as root), or even into a
-[virtualenv](https://virtualenv.pypa.io/en/stable/). How or where you install
-borgmatic is up to you, but generally an editable install makes development
-and testing easier.
-
 To get oriented with the borgmatic source code, have a look at the [source
 code reference](https://torsion.org/borgmatic/docs/reference/source-code/).
 
 
 ## Automated tests
 
-Assuming you've cloned the borgmatic source code as described above, and
-you're in the `borgmatic/` working copy, install tox, which is used for
-setting up testing environments:
+Assuming you've cloned the borgmatic source code as described above and you're
+in the `borgmatic/` working copy, install tox, which is used for setting up
+testing environments. You can either install a system package of tox (likely
+called `tox` or `python-tox`) or you can install tox with pipx:
 
 ```bash
-pip3 install --user tox
+pipx install tox
 ```
 
-Finally, to actually run tests, run:
+Finally, to actually run tests, run tox from inside the borgmatic
+sourcedirectory:
 
 ```bash
 tox

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

@@ -149,9 +149,10 @@ borgmatic umount --mount-point /mnt
 
 <span class="minilink minilink-addedin">New in version 1.7.15</span> borgmatic
 automatically stores all the configuration files used to create an archive
-inside the archive itself. This is useful in cases where you've lost a
-configuration file or you want to see what configurations were used to create a
-particular archive.
+inside the archive itself. They are stored in the archive using their full
+paths from the machine being backed up. This is useful in cases where you've
+lost a configuration file or you want to see what configurations were used to
+create a particular archive.
 
 To extract the configuration files from an archive, use the `config bootstrap`
 action. For example:
@@ -166,8 +167,8 @@ configuration file used to create this archive was located at
 `/etc/borgmatic/config.yaml` when the archive was created.
 
 Note that to run the `config bootstrap` action, you don't need to have a
-borgmatic configuration file. You only need to specify the repository to use via
-the `--repository` flag; borgmatic will figure out the rest.
+borgmatic configuration file. You only need to specify the repository to use
+via the `--repository` flag; borgmatic will figure out the rest.
 
 If a destination directory is not specified, the configuration files will be
 extracted to their original locations, silently *overwriting* any configuration
@@ -182,8 +183,16 @@ If you want to extract the configuration file from a specific archive, use the
 borgmatic config bootstrap --repository repo.borg --archive host-2023-01-02T04:06:07.080910 --destination /tmp
 ```
 
+See the output of `config bootstrap --help` for additional flags you may need
+for bootstrapping.
+
 <span class="minilink minilink-addedin">New in version 1.8.1</span> Set the
 `store_config_files` option to `false` to disable the automatic backup of
 borgmatic configuration files, for instance if they contain sensitive
 information you don't want to store even inside your encrypted backups. If you
 do this though, the `config bootstrap` action will no longer work.
+
+<span class="minilink minilink-addedin">New in version 1.8.7</span> Included
+configuration files are stored in each backup archive. This means that the
+`config bootstrap` action not only extracts the top-level configuration files
+but also the includes they depend upon.

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

@@ -116,27 +116,30 @@ archive, complete with file sizes.
 
 ## Logging
 
-By default, borgmatic logs to a local syslog-compatible daemon if one is
-present and borgmatic is running in a non-interactive console. Where those
-logs show up depends on your particular system. If you're using systemd, try
-running `journalctl -xe`. Otherwise, try viewing `/var/log/syslog` or
-similar.
-
-You can customize the log level used for syslog logging with the
-`--syslog-verbosity` flag, and this is independent from the console logging
-`--verbosity` flag described above. For instance, to get additional
-information about the progress of the backup as it proceeds:
+By default, borgmatic logs to the console. You can enable simultaneous syslog
+logging and customize its log level with the `--syslog-verbosity` flag, which
+is independent from the console logging `--verbosity` flag described above.
+For instance, to enable syslog logging, run:
 
 ```bash
 borgmatic --syslog-verbosity 1
 ```
 
-Or to increase syslog logging to include debug spew:
+To increase syslog logging further to include debugging information, run:
 
 ```bash
 borgmatic --syslog-verbosity 2
 ```
 
+See above for further details about the verbosity levels.
+
+Where these logs show up depends on your particular system. If you're using
+systemd, try running `journalctl -xe`. Otherwise, try viewing
+`/var/log/syslog` or similar.
+
+<span class="minilink minilink-addedin">Prior to version 1.8.3</span>borgmatic
+logged to syslog by default whenever run at a non-interactive console.
+
 ### Rate limiting
 
 If you are using rsyslog or systemd's journal, be aware that by default they
@@ -165,7 +168,7 @@ Note that if you use the `--log-file` flag, you are responsible for rotating
 the log file so it doesn't grow too large, for example with
 [logrotate](https://wiki.archlinux.org/index.php/Logrotate).
 
-You can the `--log-file-verbosity` flag to customize the log file's log level:
+You can use the `--log-file-verbosity` flag to customize the log file's log level:
 
 ```bash
 borgmatic --log-file /path/to/file.log --log-file-verbosity 2
@@ -197,5 +200,5 @@ See the [Python logging
 documentation](https://docs.python.org/3/library/logging.html#logrecord-attributes)
 for additional placeholders.
 
-Note that this `--log-file-format` flg only applies to the specified
+Note that this `--log-file-format` flag only applies to the specified
 `--log-file` and not to syslog or other logging.

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

@@ -139,8 +139,8 @@ Some borgmatic command-line actions also have a `--match-archives` flag that
 overrides both the auto-matching behavior and the `match_archives`
 configuration option.
 
-<span class="minilink minilink-addedin">Prior to 1.7.11</span> The way to
-limit the archives used for the `prune` action was a `prefix` option in the
+<span class="minilink minilink-addedin">Prior to version 1.7.11</span> The way
+to limit the archives used for the `prune` action was a `prefix` option in the
 `retention` section for matching against the start of archive names. And the
 option for limiting the archives used for the `check` action was a separate
 `prefix` in the `consistency` section. Both of these options are deprecated in
@@ -151,7 +151,7 @@ in newer versions of borgmatic.
 ## Configuration includes
 
 Once you have multiple different configuration files, you might want to share
-common configuration options across these files with having to copy and paste
+common configuration options across these files without having to copy and paste
 them. To achieve this, you can put fragments of common configuration options
 into a file and then include or inline that file into one or more borgmatic
 configuration files.
@@ -301,7 +301,7 @@ options via an include and then overrides one of them locally:
 <<: !include /etc/borgmatic/common.yaml
 
 constants:
-    hostname: myhostname
+    base_directory: /opt
 
 repositories:
     - path: repo.borg
@@ -311,13 +311,13 @@ This is what `common.yaml` might look like:
 
 ```yaml
 constants:
-    prefix: myprefix
-    hostname: otherhost
+    app_name: myapp
+    base_directory: /var/lib
 ```
 
-Once this include gets merged in, the resulting configuration would have a
-`prefix` value of `myprefix` and an overridden `hostname` value of
-`myhostname`.
+Once this include gets merged in, the resulting configuration would have an
+`app_name` value of `myapp` and an overridden `base_directory` value of
+`/opt`.
 
 When there's an option collision between the local file and the merged
 include, the local file's option takes precedence.
@@ -495,21 +495,29 @@ borgmatic create --override parent_option.option1=value1 --override parent_optio
 forget to specify the section that an option is in. That looks like a prefix
 on the option name, e.g. `location.repositories`.
 
-Note that each value is parsed as an actual YAML string, so you can even set
-list values by using brackets. For instance:
+Note that each value is parsed as an actual YAML string, so you can set list
+values by using brackets. For instance:
 
 ```bash
 borgmatic create --override repositories=[test1.borg,test2.borg]
 ```
 
-Or even a single list element:
+Or a single list element:
 
 ```bash
 borgmatic create --override repositories=[/root/test.borg]
 ```
 
-If your override value contains special YAML characters like colons, then
-you'll need quotes for it to parse correctly:
+Or a single list element that is a key/value pair:
+
+```bash
+borgmatic create --override repositories="[{path: test.borg, label: test}]"
+```
+
+If your override value contains characters like colons or spaces, then you'll
+need to use quotes for it to parse correctly.
+
+Another example:
 
 ```bash
 borgmatic create --override repositories="['user@server:test.borg']"
@@ -518,16 +526,12 @@ borgmatic create --override repositories="['user@server:test.borg']"
 There is not currently a way to override a single element of a list without
 replacing the whole list.
 
-Note that if you override an option of the list type (like
-`location.repositories`), you do need to use the `[ ]` list syntax. See the
-[configuration
+Using the `[ ]` list syntax is required when overriding an option of the list
+type (like `location.repositories`). See the [configuration
 reference](https://torsion.org/borgmatic/docs/reference/configuration/) for
 which options are list types. (YAML list values look like `- this` with an
 indentation and a leading dash.)
 
-Be sure to quote your overrides if they contain spaces or other characters
-that your shell may interpret.
-
 An alternate to command-line overrides is passing in your values via
 [environment
 variables](https://torsion.org/borgmatic/docs/how-to/provide-your-passwords/).
@@ -540,8 +544,7 @@ tool is borgmatic's support for defining custom constants. This is similar to
 the [variable interpolation
 feature](https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/#variable-interpolation)
 for command hooks, but the constants feature lets you substitute your own
-custom values into anywhere in the entire configuration file. (Constants don't
-work across includes or separate configuration files though.)
+custom values into any option values in the entire configuration file.
 
 Here's an example usage:
 
@@ -564,10 +567,15 @@ forget to specify the section (like `location:` or `storage:`) that any option
 is in.
 
 In this example, when borgmatic runs, all instances of `{user}` get replaced
-with `foo` and all instances of `{archive-prefix}` get replaced with `bar-`.
-(And in this particular example, `{now}` doesn't get replaced with anything,
-but gets passed directly to Borg.) After substitution, the logical result
-looks something like this:
+with `foo` and all instances of `{archive_prefix}` get replaced with `bar`.
+And `{now}` doesn't get replaced with anything, but gets passed directly to
+Borg, which has its own
+[placeholders](https://borgbackup.readthedocs.io/en/stable/usage/help.html#borg-help-placeholders)
+using the same syntax as borgmatic constants. So borgmatic options like
+`archive_name_format` that get passed directly to Borg can use either Borg
+placeholders or borgmatic constants or both!
+
+After substitution, the logical result looks something like this:
 
 ```yaml
 source_directories:
@@ -579,5 +587,24 @@ source_directories:
 archive_name_format: 'bar-{now}'
 ```
 
+Note that if you'd like to interpolate a constant into the beginning of a
+value, you'll need to quote it. For instance, this won't work:
+
+```yaml
+source_directories:
+    - {my_home_directory}/.config   # This will error!
+```
+
+Instead, do this:
+
+```yaml
+source_directories:
+    - "{my_home_directory}/.config"
+```
+
+<span class="minilink minilink-addedin">New in version 1.8.5</span> Constants
+work across includes, meaning you can define a constant and then include a
+separate configuration file that uses that constant.
+
 An alternate to constants is passing in your values via [environment
 variables](https://torsion.org/borgmatic/docs/how-to/provide-your-passwords/).

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

@@ -36,25 +36,24 @@ below for how to configure this.
 
 ### Third-party monitoring services
 
-borgmatic integrates with monitoring services like
-[Healthchecks](https://healthchecks.io/), [Cronitor](https://cronitor.io),
-[Cronhub](https://cronhub.io), [PagerDuty](https://www.pagerduty.com/), and
-[ntfy](https://ntfy.sh/) and pings these services whenever borgmatic runs.
-That way, you'll receive an alert when something goes wrong or (for certain
-hooks) the service doesn't hear from borgmatic for a configured interval. See
-[Healthchecks
-hook](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#healthchecks-hook),
-[Cronitor
-hook](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#cronitor-hook),
-[Cronhub
-hook](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#cronhub-hook),
-[PagerDuty
-hook](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#pagerduty-hook),
-and [ntfy hook](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#ntfy-hook)
-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)
+
+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).
+See the documentation links above for configuration information.
+
+While these services and libraries offer different features, you probably only
+need to use one of them at most.
 
-While these services offer different features, you probably only need to use
-one of them at most.
 
 ### Third-party monitoring software
 
@@ -129,7 +128,7 @@ especially the security information.
 ## Healthchecks hook
 
 [Healthchecks](https://healthchecks.io/) is a service that provides "instant
-alerts when your cron jobs fail silently", and borgmatic has built-in
+alerts when your cron jobs fail silently," and borgmatic has built-in
 integration with it. Once you create a Healthchecks account and project on
 their site, all you need to do is configure borgmatic with the unique "Ping
 URL" for your project. Here's an example:
@@ -143,22 +142,20 @@ healthchecks:
 <span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
 this option in the `hooks:` section of your configuration.
 
-With this hook in place, borgmatic pings your Healthchecks project when a
-backup begins, ends, or errors. Specifically, after the <a
-href="https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/">`before_backup`
-hooks</a> run, borgmatic lets Healthchecks know that it has started if any of
-the `create`, `prune`, `compact`, or `check` actions are run.
+With this configuration, borgmatic pings your Healthchecks project when a
+backup begins, ends, or errors, but only when any of the `create`, `prune`,
+`compact`, or `check` actions are run.
 
 Then, if the actions complete successfully, borgmatic notifies Healthchecks of
-the success after the `after_backup` hooks run and includes borgmatic logs in
-the payload data sent to Healthchecks. This means that borgmatic logs show up
-in the Healthchecks UI, although be aware that Healthchecks currently has a
-10-kilobyte limit for the logs in each ping.
+the success and includes borgmatic logs in the payload data sent to
+Healthchecks. This means that borgmatic logs show up in the Healthchecks UI,
+although be aware that Healthchecks currently has a 10-kilobyte limit for the
+logs in each ping.
 
-If an error occurs during any action or hook, borgmatic notifies Healthchecks
-after the `on_error` hooks run, also tacking on logs including the error
-itself. But the logs are only included for errors that occur when a `create`,
-`prune`, `compact`, or `check` action is run.
+If an error occurs during any action or hook, borgmatic notifies Healthchecks,
+also tacking on logs including the error itself. But the logs are only
+included for errors that occur when a `create`, `prune`, `compact`, or `check`
+action is run.
 
 You can customize the verbosity of the logs that are sent to Healthchecks with
 borgmatic's `--monitoring-verbosity` flag. The `--list` and `--stats` flags
@@ -175,7 +172,7 @@ or it doesn't hear from borgmatic for a certain period of time.
 ## Cronitor hook
 
 [Cronitor](https://cronitor.io/) provides "Cron monitoring and uptime healthchecks
-for websites, services and APIs", and borgmatic has built-in
+for websites, services and APIs," and borgmatic has built-in
 integration with it. Once you create a Cronitor account and cron job monitor on
 their site, all you need to do is configure borgmatic with the unique "Ping
 API URL" for your monitor. Here's an example:
@@ -189,14 +186,10 @@ cronitor:
 <span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
 this option in the `hooks:` section of your configuration.
 
-With this hook in place, borgmatic pings your Cronitor monitor when a backup
-begins, ends, or errors. Specifically, after the <a
-href="https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/">`before_backup`
-hooks</a> run, borgmatic lets Cronitor know that it has started if any of the
-`prune`, `compact`, `create`, or `check` actions are run. Then, if the actions
-complete successfully, borgmatic notifies Cronitor of the success after the
-`after_backup` hooks run. And if an error occurs during any action or hook,
-borgmatic notifies Cronitor after the `on_error` hooks run.
+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
+successfully or errors, borgmatic notifies Cronitor accordingly.
 
 You can configure Cronitor to notify you by a [variety of
 mechanisms](https://cronitor.io/docs/cron-job-notifications) when backups fail
@@ -206,7 +199,7 @@ or it doesn't hear from borgmatic for a certain period of time.
 ## Cronhub hook
 
 [Cronhub](https://cronhub.io/) provides "instant alerts when any of your
-background jobs fail silently or run longer than expected", and borgmatic has
+background jobs fail silently or run longer than expected," and borgmatic has
 built-in integration with it. Once you create a Cronhub account and monitor on
 their site, all you need to do is configure borgmatic with the unique "Ping
 URL" for your monitor. Here's an example:
@@ -220,14 +213,10 @@ cronhub:
 <span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
 this option in the `hooks:` section of your configuration.
 
-With this hook in place, borgmatic pings your Cronhub monitor when a backup
-begins, ends, or errors. Specifically, after the <a
-href="https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/">`before_backup`
-hooks</a> run, borgmatic lets Cronhub know that it has started if any of the
-`prune`, `compact`, `create`, or `check` actions are run. Then, if the actions
-complete successfully, borgmatic notifies Cronhub of the success after the
-`after_backup` hooks run. And if an error occurs during any action or hook,
-borgmatic notifies Cronhub after the `on_error` hooks run.
+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
+successfully or errors, borgmatic notifies Cronhub accordingly.
 
 Note that even though you configure borgmatic with the "start" variant of the
 ping URL, borgmatic substitutes the correct state into the URL when pinging
@@ -265,11 +254,10 @@ pagerduty:
 <span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
 this option in the `hooks:` section of your configuration.
 
-With this hook in place, borgmatic creates a PagerDuty event for your service
-whenever backups fail. Specifically, if an error occurs during a `create`,
-`prune`, `compact`, or `check` action, borgmatic sends an event to PagerDuty
-before the `on_error` hooks run. Note that borgmatic does not contact
-PagerDuty when a backup starts or ends without error.
+With this configuration, borgmatic creates a PagerDuty event for your service
+whenever backups fail, but only when any of the `create`, `prune`, `compact`,
+or `check` actions are run. Note that borgmatic does not contact PagerDuty
+when a backup starts or when it ends without error.
 
 You can configure PagerDuty to notify you by a [variety of
 mechanisms](https://support.pagerduty.com/docs/notifications) when backups
@@ -281,10 +269,12 @@ us](https://torsion.org/borgmatic/#support-and-contributing).
 
 ## ntfy hook
 
-[ntfy](https://ntfy.sh) is a free, simple, service (either hosted or self-hosted)
-which offers simple pub/sub push notifications to multiple platforms including
-[web](https://ntfy.sh/stats), [Android](https://play.google.com/store/apps/details?id=io.heckel.ntfy)
-and [iOS](https://apps.apple.com/us/app/ntfy/id1625396347).
+<span class="minilink minilink-addedin">New in version 1.6.3</span>
+[ntfy](https://ntfy.sh) is a free, simple, service (either hosted or
+self-hosted) which offers simple pub/sub push notifications to multiple
+platforms including [web](https://ntfy.sh/stats),
+[Android](https://play.google.com/store/apps/details?id=io.heckel.ntfy) and
+[iOS](https://apps.apple.com/us/app/ntfy/id1625396347).
 
 Since push notifications for regular events might soon become quite annoying,
 this hook only fires on any errors by default in order to instantly alert you to issues.
@@ -328,6 +318,122 @@ ntfy:
 the `ntfy:` option in the `hooks:` section of your configuration.
 
 
+## Loki hook
+
+<span class="minilink minilink-addedin">New in version 1.8.3</span> [Grafana
+Loki](https://grafana.com/oss/loki/) is a "horizontally scalable, highly
+available, multi-tenant log aggregation system inspired by Prometheus."
+borgmatic has built-in integration with Loki, sending both backup status and
+borgmatic logs.
+
+You can configure borgmatic to use either a [self-hosted Loki
+instance](https://grafana.com/docs/loki/latest/installation/) or [a Grafana
+Cloud account](https://grafana.com/auth/sign-up/create-user). Start by setting
+your Loki API push URL. Here's an example:
+
+```yaml
+loki:
+    url: http://localhost:3100/loki/api/v1/push
+```
+
+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
+the actions complete, borgmatic notifies Loki of success or failure.
+
+This hook supports sending arbitrary labels to Loki. For instance:
+
+```yaml
+loki:
+    url: http://localhost:3100/loki/api/v1/push
+
+    labels:
+        app: borgmatic
+        hostname: example.org
+```
+
+There are also a few placeholders you can optionally use as label values:
+
+ * `__config`: name of the borgmatic configuration file
+ * `__config_path`: full path of the borgmatic configuration file
+ * `__hostname`: the local machine hostname
+
+These placeholders are only substituted for the whole label value, not
+interpolated into a larger string. For instance:
+
+```yaml
+loki:
+    url: http://localhost:3100/loki/api/v1/push
+
+    labels:
+        app: borgmatic
+        config: __config
+        hostname: __hostname
+```
+
+
+## Apprise hook
+
+<span class="minilink minilink-addedin">New in version 1.8.4</span>
+[Apprise](https://github.com/caronc/apprise/wiki) is a local notification library
+that "allows you to send a notification to almost all of the most popular
+[notification services](https://github.com/caronc/apprise/wiki) available to
+us today such as: Telegram, Discord, Slack, Amazon SNS, Gotify, etc."
+
+Depending on how you installed borgmatic, it may not have come with Apprise.
+For instance, if you originally [installed borgmatic with
+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 --editable --force borgmatic[Apprise]
+```
+
+Omit `sudo` if borgmatic is installed as a non-root user.
+
+Once Apprise is installed, configure borgmatic to notify one or more [Apprise
+services](https://github.com/caronc/apprise/wiki). For example:
+
+```yaml
+apprise:
+    services:
+        - url: gotify://hostname/token
+          label: gotify
+        - url: mastodons://access_key@hostname/@user
+          label: mastodon
+```
+
+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.
+
+You can optionally customize the contents of the default messages sent to
+these services:
+
+```yaml
+apprise:
+    services:
+        - url: gotify://hostname/token
+          label: gotify
+    start:
+        title: Ping!
+        body: Starting backup process.
+    finish:
+        title: Ping!
+        body: Backups successfully made.
+    fail:
+        title: Ping!
+        body: Your backups have failed.
+    states:
+        - start
+        - finish
+        - fail
+```
+
+See the [configuration
+reference](https://torsion.org/borgmatic/docs/reference/configuration/) for
+details.
+
+
 ## Scripting borgmatic
 
 To consume the output of borgmatic in other software, you can include an

docs/how-to/provide-your-passwords.md

@@ -5,13 +5,31 @@ eleventyNavigation:
   parent: How-to guides
   order: 2
 ---
-## Environment variable interpolation
+## Providing passwords and secrets to borgmatic
 
 If you want to use a Borg repository passphrase or database passwords with
 borgmatic, you can set them directly in your borgmatic configuration file,
-treating those secrets like any other option value. But if you'd rather store
-them outside of borgmatic, whether for convenience or security reasons, read
-on.
+treating those secrets like any other option value. For instance, you can
+specify your Borg passhprase with:
+
+```yaml
+encryption_passphrase: yourpassphrase
+```
+
+But if you'd rather store them outside of borgmatic, whether for convenience
+or security reasons, read on.
+
+### Delegating to another application
+
+borgmatic supports calling another application such as a password manager to 
+obtain the Borg passphrase to a repository.
+
+For example, to ask the *Pass* password manager to provide the passphrase:
+```yaml
+encryption_passcommand: pass path/to/borg-repokey
+```
+
+### Environment variable interpolation
 
 <span class="minilink minilink-addedin">New in version 1.6.4</span> borgmatic
 supports interpolating arbitrary environment variables directly into option
@@ -20,14 +38,14 @@ pull your repository passphrase, your database passwords, or any other option
 values from environment variables. For instance:
 
 ```yaml
-encryption_passphrase: ${MY_PASSPHRASE}
+encryption_passphrase: ${YOUR_PASSPHRASE}
 ```
 
 <span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
 this option in the `storage:` section of your configuration.
 
-This uses the `MY_PASSPHRASE` environment variable as your encryption
-passphrase. Note that the `{` `}` brackets are required. `$MY_PASSPHRASE` by
+This uses the `YOUR_PASSPHRASE` environment variable as your encryption
+passphrase. Note that the `{` `}` brackets are required. `$YOUR_PASSPHRASE` by
 itself will not work.
 
 In the case of `encryption_passphrase` in particular, an alternate approach
@@ -42,30 +60,31 @@ the same approach applies. For example:
 ```yaml
 postgresql_databases:
     - name: users
-      password: ${MY_DATABASE_PASSWORD}
+      password: ${YOUR_DATABASE_PASSWORD}
 ```
 
 <span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
 this option in the `hooks:` section of your configuration.
 
-This uses the `MY_DATABASE_PASSWORD` environment variable as your database
+This uses the `YOUR_DATABASE_PASSWORD` environment variable as your database
 password.
 
 
-### Interpolation defaults
+#### Interpolation defaults
 
-If you'd like to set a default for your environment variables, you can do so with the following syntax:
+If you'd like to set a default for your environment variables, you can do so
+with the following syntax:
 
 ```yaml
-encryption_passphrase: ${MY_PASSPHRASE:-defaultpass}
+encryption_passphrase: ${YOUR_PASSPHRASE:-defaultpass}
 ```
 
-Here, "`defaultpass`" is the default passphrase if the `MY_PASSPHRASE`
+Here, "`defaultpass`" is the default passphrase if the `YOUR_PASSPHRASE`
 environment variable is not set. Without a default, if the environment
 variable doesn't exist, borgmatic will error.
 
 
-### Disabling interpolation
+#### Disabling interpolation
 
 To disable this environment variable interpolation feature entirely, you can
 pass the `--no-environment-interpolation` flag on the command-line.
@@ -78,7 +97,7 @@ can escape it with a backslash. For instance, if your password is literally
 encryption_passphrase: \${A}@!
 ```
 
-### Related features
+## Related features
 
 Another way to override particular options within a borgmatic configuration
 file is to use a [configuration
@@ -90,3 +109,9 @@ Additionally, borgmatic action hooks support their own [variable
 interpolation](https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/#variable-interpolation),
 although in that case it's for particular borgmatic runtime values rather than
 (only) environment variables.
+
+Lastly, if you do want to specify your passhprase directly within borgmatic
+configuration, but you'd like to keep it in a separate file from your main
+configuration, you can [use a configuration include or a merge
+include](https://torsion.org/borgmatic/docs/how-to/make-per-application-backups/#configuration-includes)
+to pull in an external password.

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

@@ -7,74 +7,70 @@ eleventyNavigation:
 ---
 ## Installation
 
-Many users need to backup system files that require privileged access, so
-these instructions install and run borgmatic as root. If you don't need to
-backup such files, then you are welcome to install and run borgmatic as a
-non-root user.
+### Prerequisites
 
-First, manually [install
+First, [install
 Borg](https://borgbackup.readthedocs.io/en/stable/installation.html), at least
 version 1.1. borgmatic does not install Borg automatically so as to avoid
 conflicts with existing Borg installations.
 
-Then, download and install borgmatic as a [user site
-installation](https://packaging.python.org/tutorials/installing-packages/#installing-to-the-user-site)
-by running the following command:
+Then, [install pipx](https://pypa.github.io/pipx/installation/) as the root
+user (with `sudo`) to make installing borgmatic easy without impacting other
+Python applications on your system. If you have trouble installing pipx with
+pip, then you can install a system package instead. E.g. on Ubuntu or Debian,
+run:
 
 ```bash
-sudo pip3 install --user --upgrade borgmatic
+sudo apt update
+sudo apt install pipx
 ```
 
-This installs borgmatic and its commands at the `/root/.local/bin` path.
+### Root install
 
-Your pip binary may have a different name than "pip3". Make sure you're using
-Python 3.7+, as borgmatic does not support older versions of Python.
-
-The next step is to ensure that borgmatic's commands available are on your
-system `PATH`, so that you can run borgmatic:
+If you want to run borgmatic on a schedule with privileged access to your
+files, then you should install borgmatic as the root user by running the
+following commands:
 
 ```bash
-echo export 'PATH="$PATH:/root/.local/bin"' >> ~/.bashrc
-source ~/.bashrc
+sudo pipx ensurepath
+sudo pipx install borgmatic
 ```
 
-This adds `/root/.local/bin` to your non-root user's system `PATH`.
-
-If you're using a command shell other than Bash, you may need to use different
-commands here.
-
-You can check whether all of this worked with:
+Check whether this worked with:
 
 ```bash
-sudo borgmatic --version
+sudo su -
+borgmatic --version
 ```
 
 If borgmatic is properly installed, that should output your borgmatic version.
-
-As an alternative to adding the path to `~/.bashrc` file, if you're using sudo
-to run borgmatic, you can configure [sudo's
-`secure_path` option](https://man.archlinux.org/man/sudoers.5) to include
-borgmatic's path.
+And if you'd also like `sudo borgmatic` to work, keep reading!
 
 
-### Global install option
+### Non-root install
 
-If you try the user site installation above and have problems making borgmatic
-commands runnable on your system `PATH`, an alternate approach is to install
-borgmatic globally.
-
-The following uninstalls borgmatic and then reinstalls it such that borgmatic
-commands are on the default system `PATH`:
+If you only want to run borgmatic as a non-root user (without privileged file
+access) *or* you want to make `sudo borgmatic` work so borgmatic runs as root,
+then install borgmatic as a non-root user by running the following commands as
+that user:
 
 ```bash
-sudo pip3 uninstall borgmatic
-sudo pip3 install --upgrade borgmatic
+pipx ensurepath
+pipx install borgmatic
 ```
 
-The main downside of a global install is that borgmatic is less cleanly
-separated from the rest of your Python software, and there's the theoretical
-possibility of library conflicts. But if you're okay with that, for instance
-on a relatively dedicated system, then a global install can work out fine.
+This should work even if you've also installed borgmatic as the root user.
+
+Check whether this worked with:
+
+```bash
+borgmatic --version
+```
+
+If borgmatic is properly installed, that should output your borgmatic version.
+You can also try `sudo borgmatic --version` if you intend to run borgmatic
+with `sudo`. If that doesn't work, you may need to update your [sudoers
+`secure_path` option](https://wiki.archlinux.org/title/Sudo).
 
 
 ### Other ways to install
@@ -286,6 +282,21 @@ due to things like file damage. For instance:
 sudo borgmatic --verbosity 1 --list --stats
 ```
 
+### Skipping actions
+
+<span class="minilink minilink-addedin">New in version 1.8.5</span> You can
+configure borgmatic to skip running certain actions (default or otherwise).
+For instance, to always skip the `compact` action when using [Borg's
+append-only
+mode](https://borgbackup.readthedocs.io/en/stable/usage/notes.html#append-only-mode-forbid-compaction),
+set the `skip_actions` option:
+
+```
+skip_actions:
+    - compact
+```
+
+
 ## Autopilot
 
 Running backups manually is good for validating your configuration, but I'm

docs/how-to/upgrade.md

@@ -3,30 +3,42 @@ title: How to upgrade borgmatic and Borg
 eleventyNavigation:
   key: 📦 Upgrade borgmatic/Borg
   parent: How-to guides
-  order: 12
+  order: 13
 ---
 ## Upgrading borgmatic
 
-In general, all you should need to do to upgrade borgmatic is run the
-following:
+In general, all you should need to do to upgrade borgmatic if you've
+[installed it with
+pipx](https://torsion.org/borgmatic/docs/how-to/set-up-backups/#installation)
+is to run the following:
 
 ```bash
-sudo pip3 install --user --upgrade borgmatic
+sudo pipx upgrade borgmatic
 ```
 
-See below about special cases with old versions of borgmatic. Additionally, if
-you installed borgmatic [without using `pip3 install
---user`](https://torsion.org/borgmatic/docs/how-to/set-up-backups/#other-ways-to-install),
-then your upgrade process may be different.
+Omit `sudo` if you installed borgmatic as a non-root user. And if you
+installed borgmatic *both* as root and as a non-root user, you'll need to
+upgrade each installation independently.
+
+If you originally installed borgmatic with `sudo pip3 install --user`, you can
+uninstall it first with `sudo pip3 uninstall borgmatic` and then [install it
+again with
+pipx](https://torsion.org/borgmatic/docs/how-to/set-up-backups/#installation),
+which should better isolate borgmatic from your other Python applications.
+
+But if you [installed borgmatic without pipx or
+pip3](https://torsion.org/borgmatic/docs/how-to/set-up-backups/#other-ways-to-install),
+then your upgrade method may be different.
+
 
 
 ### Upgrading your configuration
 
-The borgmatic configuration file format is almost always backwards-compatible
-from release to release without any changes, but you may still want to update
-your configuration file when you upgrade to take advantage of new
-configuration options. This is completely optional. If you prefer, you can add
-new configuration options manually.
+The borgmatic configuration file format is usually backwards-compatible from
+release to release without any changes, but you may still want to update your
+configuration file when you upgrade to take advantage of new configuration
+options or avoid old configuration from eventually becoming unsupported. If
+you prefer, you can add new configuration options manually.
 
 If you do want to upgrade your configuration file to include new options, use
 the `borgmatic config generate` action with its optional `--source` flag that
@@ -64,45 +76,10 @@ and, if desired, replace your original configuration file with it.
 
 borgmatic changed its configuration file format in version 1.1.0 from
 INI-style to YAML. This better supports validation and has a more natural way
-to express lists of values. To upgrade your existing configuration, first
-upgrade to the last version of borgmatic to support converting configuration:
-borgmatic 1.7.14.
-
-As of version 1.1.0, borgmatic no longer supports Python 2. If you were
-already running borgmatic with Python 3, then you can upgrade borgmatic
-in-place:
-
-```bash
-sudo pip3 install --user --upgrade borgmatic==1.7.14
-```
-
-But if you were running borgmatic with Python 2, uninstall and reinstall instead:
-
-```bash
-sudo pip uninstall borgmatic
-sudo pip3 install --user borgmatic==1.7.14
-```
-
-The pip binary names for different versions of Python can differ, so the above
-commands may need some tweaking to work on your machine.
-
-
-Once borgmatic is upgraded, run:
-
-```bash
-sudo upgrade-borgmatic-config
-```
-
-That will generate a new YAML configuration file at /etc/borgmatic/config.yaml
-(by default) using the values from both your existing configuration and
-excludes files. The new version of borgmatic will consume the YAML
-configuration file instead of the old one.
-
-Now you can upgrade to a newer version of borgmatic:
-
-```bash
-sudo pip3 install --user borgmatic
-```
+to express lists of values. Modern versions of borgmatic no longer include
+support for upgrading configuration files this old, but feel free to [file a
+ticket](https://torsion.org/borgmatic/#issues) for help with upgrading any old
+INI-style configuration files you may have.
 
 
 ## Upgrading Borg

docs/reference/configuration.md

@@ -21,5 +21,3 @@ version](https://torsion.org/borgmatic/docs/how-to/set-up-backups/#configuration
 ```yaml
 {% include borgmatic/config.yaml %}
 ```
-
-Note that you can also [download this configuration

sample/systemd/borgmatic.service

@@ -32,16 +32,16 @@ RestrictSUIDSGID=yes
 SystemCallArchitectures=native
 SystemCallFilter=@system-service
 SystemCallErrorNumber=EPERM
-# To restrict write access further, change "ProtectSystem" to "strict" and uncomment
-# "ReadWritePaths", "ReadOnlyPaths", "ProtectHome", and "BindPaths". Then add any local repository
-# paths to the list of "ReadWritePaths" and local backup source paths to "ReadOnlyPaths". This
-# leaves most of the filesystem read-only to borgmatic.
+# To restrict write access further, change "ProtectSystem" to "strict" and
+# uncomment "ReadWritePaths", "TemporaryFileSystem", "BindPaths" and
+# "BindReadOnlyPaths". Then add any local repository paths to the list of
+# "ReadWritePaths". This leaves most of the filesystem read-only to borgmatic.
 ProtectSystem=full
 # ReadWritePaths=-/mnt/my_backup_drive
-# ReadOnlyPaths=-/var/lib/my_backup_source
 # This will mount a tmpfs on top of /root and pass through needed paths
-# ProtectHome=tmpfs
+# TemporaryFileSystem=/root:ro
 # BindPaths=-/root/.cache/borg -/root/.config/borg -/root/.borgmatic
+# BindReadOnlyPaths=-/root/.ssh
 
 # May interfere with running external programs within borgmatic hooks.
 CapabilityBoundingSet=CAP_DAC_READ_SEARCH CAP_NET_RAW

scripts/run-full-tests

@@ -18,11 +18,11 @@ if [ -z "$TEST_CONTAINER" ]; then
 fi
 
 apk add --no-cache python3 py3-pip borgbackup postgresql-client mariadb-client mongodb-tools \
-    py3-ruamel.yaml py3-ruamel.yaml.clib bash sqlite fish
+    py3-ruamel.yaml py3-ruamel.yaml.clib py3-yaml bash sqlite fish
 # If certain dependencies of black are available in this version of Alpine, install them.
 apk add --no-cache py3-typed-ast py3-regex || true
-python3 -m pip install --no-cache --upgrade pip==22.2.2 setuptools==64.0.1 pymongo==4.4.1
-pip3 install --ignore-installed tox==3.25.1
+python3 -m pip install --no-cache --upgrade pip==22.2.2 setuptools==64.0.1
+pip3 install --ignore-installed tox==4.11.3
 export COVERAGE_FILE=/tmp/.coverage
 
 if [ "$1" != "--end-to-end-only" ]; then

setup.py

@@ -1,6 +1,6 @@
 from setuptools import find_packages, setup
 
-VERSION = '1.8.2'
+VERSION = '1.8.7'
 
 
 setup(
@@ -33,9 +33,10 @@ setup(
         'jsonschema',
         'packaging',
         'requests',
-        'ruamel.yaml>0.15.0,<0.18.0',
+        'ruamel.yaml>0.15.0',
         'setuptools',
     ),
+    extras_require={"Apprise": ["apprise"]},
     include_package_data=True,
-    python_requires='>=3.7',
+    python_requires='>=3.8',
 )

test_requirements.txt

@@ -1,6 +1,8 @@
 appdirs==1.4.4; python_version >= '3.8'
+apprise==1.3.0
 attrs==22.2.0; python_version >= '3.8'
 black==23.3.0; python_version >= '3.8'
+certifi==2023.7.22
 chardet==5.1.0
 click==8.1.3; python_version >= '3.8'
 codespell==2.2.4
@@ -12,22 +14,21 @@ flake8-use-fstring==1.4
 flake8-variables-names==0.0.5
 flexmock==0.11.3
 idna==3.4
-importlib_metadata==6.3.0; python_version < '3.8'
 isort==5.12.0
+jsonschema==4.17.3
+Markdown==3.4.1
 mccabe==0.7.0
 packaging==23.1
+pathspec==0.11.1
 pluggy==1.0.0
-pathspec==0.11.1; python_version >= '3.8'
 py==1.11.0
 pycodestyle==2.10.0
 pyflakes==3.0.1
-jsonschema==4.17.3
 pytest==7.3.0
 pytest-cov==4.0.0
-regex; python_version >= '3.8'
+PyYAML>5.0.0
+regex
 requests==2.31.0
-ruamel.yaml>0.15.0,<0.18.0
-toml==0.10.2; python_version >= '3.8'
-typed-ast; python_version >= '3.8'
-typing-extensions==4.5.0; python_version < '3.8'
-zipp==3.15.0; python_version < '3.8'
+ruamel.yaml>0.15.0
+toml==0.10.2
+typed-ast

tests/end-to-end/test_invalid_flag.py

@@ -0,0 +1,11 @@
+import subprocess
+import sys
+
+
+def test_borgmatic_command_with_invalid_flag_shows_error_but_not_traceback():
+    output = subprocess.run(
+        'borgmatic -v 2 --invalid'.split(' '), stdout=subprocess.PIPE, stderr=subprocess.STDOUT
+    ).stdout.decode(sys.stdout.encoding)
+
+    assert 'Unrecognized argument' in output
+    assert 'Traceback' not in output

tests/integration/borg/test_commands.py

@@ -32,6 +32,9 @@ def assert_command_does_not_duplicate_flags(command, *args, **kwargs):
         flag_name: 1 for flag_name in flag_counts
     }, f"Duplicate flags found in: {' '.join(command)}"
 
+    if '--json' in command:
+        return '{}'
+
 
 def fuzz_argument(arguments, argument_name):
     '''

tests/integration/commands/test_arguments.py

@@ -13,8 +13,9 @@ def test_parse_arguments_with_no_arguments_uses_defaults():
     global_arguments = arguments['global']
     assert global_arguments.config_paths == config_paths
     assert global_arguments.verbosity == 0
-    assert global_arguments.syslog_verbosity == 0
-    assert global_arguments.log_file_verbosity == 0
+    assert global_arguments.syslog_verbosity == -2
+    assert global_arguments.log_file_verbosity == 1
+    assert global_arguments.monitoring_verbosity == 1
 
 
 def test_parse_arguments_with_multiple_config_flags_parses_as_list():
@@ -25,8 +26,9 @@ def test_parse_arguments_with_multiple_config_flags_parses_as_list():
     global_arguments = arguments['global']
     assert global_arguments.config_paths == ['myconfig', 'otherconfig']
     assert global_arguments.verbosity == 0
-    assert global_arguments.syslog_verbosity == 0
-    assert global_arguments.log_file_verbosity == 0
+    assert global_arguments.syslog_verbosity == -2
+    assert global_arguments.log_file_verbosity == 1
+    assert global_arguments.monitoring_verbosity == 1
 
 
 def test_parse_arguments_with_action_after_config_path_omits_action():
@@ -71,8 +73,9 @@ def test_parse_arguments_with_verbosity_overrides_default():
     global_arguments = arguments['global']
     assert global_arguments.config_paths == config_paths
     assert global_arguments.verbosity == 1
-    assert global_arguments.syslog_verbosity == 0
-    assert global_arguments.log_file_verbosity == 0
+    assert global_arguments.syslog_verbosity == -2
+    assert global_arguments.log_file_verbosity == 1
+    assert global_arguments.monitoring_verbosity == 1
 
 
 def test_parse_arguments_with_syslog_verbosity_overrides_default():
@@ -85,6 +88,8 @@ def test_parse_arguments_with_syslog_verbosity_overrides_default():
     assert global_arguments.config_paths == config_paths
     assert global_arguments.verbosity == 0
     assert global_arguments.syslog_verbosity == 2
+    assert global_arguments.log_file_verbosity == 1
+    assert global_arguments.monitoring_verbosity == 1
 
 
 def test_parse_arguments_with_log_file_verbosity_overrides_default():
@@ -96,8 +101,9 @@ def test_parse_arguments_with_log_file_verbosity_overrides_default():
     global_arguments = arguments['global']
     assert global_arguments.config_paths == config_paths
     assert global_arguments.verbosity == 0
-    assert global_arguments.syslog_verbosity == 0
+    assert global_arguments.syslog_verbosity == -2
     assert global_arguments.log_file_verbosity == -1
+    assert global_arguments.monitoring_verbosity == 1
 
 
 def test_parse_arguments_with_single_override_parses():
@@ -616,3 +622,16 @@ def test_parse_arguments_config_with_subaction_and_explicit_config_file_does_not
     module.parse_arguments(
         'config', 'bootstrap', '--repository', 'repo.borg', '--config', 'test.yaml'
     )
+
+
+def test_parse_arguments_with_borg_action_and_dry_run_raises():
+    flexmock(module.collect).should_receive('get_default_config_paths').and_return(['default'])
+
+    with pytest.raises(ValueError):
+        module.parse_arguments('--dry-run', 'borg', 'list')
+
+
+def test_parse_arguments_with_borg_action_and_no_dry_run_does_not_raise():
+    flexmock(module.collect).should_receive('get_default_config_paths').and_return(['default'])
+
+    module.parse_arguments('borg', 'list')

tests/integration/config/test_generate.py

@@ -10,7 +10,7 @@ from borgmatic.config import generate as module
 
 def test_insert_newline_before_comment_does_not_raise():
     field_name = 'foo'
-    config = module.yaml.comments.CommentedMap([(field_name, 33)])
+    config = module.ruamel.yaml.comments.CommentedMap([(field_name, 33)])
     config.yaml_set_comment_before_after_key(key=field_name, before='Comment')
 
     module.insert_newline_before_comment(config, field_name)
@@ -125,14 +125,16 @@ def test_write_configuration_with_already_existing_directory_does_not_raise():
 
 
 def test_add_comments_to_configuration_sequence_of_strings_does_not_raise():
-    config = module.yaml.comments.CommentedSeq(['foo', 'bar'])
+    config = module.ruamel.yaml.comments.CommentedSeq(['foo', 'bar'])
     schema = {'type': 'array', 'items': {'type': 'string'}}
 
     module.add_comments_to_configuration_sequence(config, schema)
 
 
 def test_add_comments_to_configuration_sequence_of_maps_does_not_raise():
-    config = module.yaml.comments.CommentedSeq([module.yaml.comments.CommentedMap([('foo', 'yo')])])
+    config = module.ruamel.yaml.comments.CommentedSeq(
+        [module.ruamel.yaml.comments.CommentedMap([('foo', 'yo')])]
+    )
     schema = {
         'type': 'array',
         'items': {'type': 'object', 'properties': {'foo': {'description': 'yo'}}},
@@ -142,7 +144,9 @@ def test_add_comments_to_configuration_sequence_of_maps_does_not_raise():
 
 
 def test_add_comments_to_configuration_sequence_of_maps_without_description_does_not_raise():
-    config = module.yaml.comments.CommentedSeq([module.yaml.comments.CommentedMap([('foo', 'yo')])])
+    config = module.ruamel.yaml.comments.CommentedSeq(
+        [module.ruamel.yaml.comments.CommentedMap([('foo', 'yo')])]
+    )
     schema = {'type': 'array', 'items': {'type': 'object', 'properties': {'foo': {}}}}
 
     module.add_comments_to_configuration_sequence(config, schema)
@@ -150,7 +154,7 @@ def test_add_comments_to_configuration_sequence_of_maps_without_description_does
 
 def test_add_comments_to_configuration_object_does_not_raise():
     # Ensure that it can deal with fields both in the schema and missing from the schema.
-    config = module.yaml.comments.CommentedMap([('foo', 33), ('bar', 44), ('baz', 55)])
+    config = module.ruamel.yaml.comments.CommentedMap([('foo', 33), ('bar', 44), ('baz', 55)])
     schema = {
         'type': 'object',
         'properties': {'foo': {'description': 'Foo'}, 'bar': {'description': 'Bar'}},
@@ -160,7 +164,7 @@ def test_add_comments_to_configuration_object_does_not_raise():
 
 
 def test_add_comments_to_configuration_object_with_skip_first_does_not_raise():
-    config = module.yaml.comments.CommentedMap([('foo', 33)])
+    config = module.ruamel.yaml.comments.CommentedMap([('foo', 33)])
     schema = {'type': 'object', 'properties': {'foo': {'description': 'Foo'}}}
 
     module.add_comments_to_configuration_object(config, schema, skip_first=True)
@@ -168,7 +172,7 @@ def test_add_comments_to_configuration_object_with_skip_first_does_not_raise():
 
 def test_remove_commented_out_sentinel_keeps_other_comments():
     field_name = 'foo'
-    config = module.yaml.comments.CommentedMap([(field_name, 33)])
+    config = module.ruamel.yaml.comments.CommentedMap([(field_name, 33)])
     config.yaml_set_comment_before_after_key(key=field_name, before='Actual comment.\nCOMMENT_OUT')
 
     module.remove_commented_out_sentinel(config, field_name)
@@ -180,7 +184,7 @@ def test_remove_commented_out_sentinel_keeps_other_comments():
 
 def test_remove_commented_out_sentinel_without_sentinel_keeps_other_comments():
     field_name = 'foo'
-    config = module.yaml.comments.CommentedMap([(field_name, 33)])
+    config = module.ruamel.yaml.comments.CommentedMap([(field_name, 33)])
     config.yaml_set_comment_before_after_key(key=field_name, before='Actual comment.')
 
     module.remove_commented_out_sentinel(config, field_name)
@@ -192,7 +196,7 @@ def test_remove_commented_out_sentinel_without_sentinel_keeps_other_comments():
 
 def test_remove_commented_out_sentinel_on_unknown_field_does_not_raise():
     field_name = 'foo'
-    config = module.yaml.comments.CommentedMap([(field_name, 33)])
+    config = module.ruamel.yaml.comments.CommentedMap([(field_name, 33)])
     config.yaml_set_comment_before_after_key(key=field_name, before='Actual comment.')
 
     module.remove_commented_out_sentinel(config, 'unknown')
@@ -201,7 +205,9 @@ def test_remove_commented_out_sentinel_on_unknown_field_does_not_raise():
 def test_generate_sample_configuration_does_not_raise():
     builtins = flexmock(sys.modules['builtins'])
     builtins.should_receive('open').with_args('schema.yaml').and_return('')
-    flexmock(module.yaml).should_receive('round_trip_load')
+    flexmock(module.ruamel.yaml).should_receive('YAML').and_return(
+        flexmock(load=lambda filename: {})
+    )
     flexmock(module).should_receive('schema_to_sample_configuration')
     flexmock(module).should_receive('merge_source_configuration_into_destination')
     flexmock(module).should_receive('render_configuration')
@@ -214,7 +220,9 @@ def test_generate_sample_configuration_does_not_raise():
 def test_generate_sample_configuration_with_source_filename_does_not_raise():
     builtins = flexmock(sys.modules['builtins'])
     builtins.should_receive('open').with_args('schema.yaml').and_return('')
-    flexmock(module.yaml).should_receive('round_trip_load')
+    flexmock(module.ruamel.yaml).should_receive('YAML').and_return(
+        flexmock(load=lambda filename: {})
+    )
     flexmock(module.load).should_receive('load_configuration')
     flexmock(module.normalize).should_receive('normalize')
     flexmock(module).should_receive('schema_to_sample_configuration')
@@ -229,7 +237,9 @@ def test_generate_sample_configuration_with_source_filename_does_not_raise():
 def test_generate_sample_configuration_with_dry_run_does_not_write_file():
     builtins = flexmock(sys.modules['builtins'])
     builtins.should_receive('open').with_args('schema.yaml').and_return('')
-    flexmock(module.yaml).should_receive('round_trip_load')
+    flexmock(module.ruamel.yaml).should_receive('YAML').and_return(
+        flexmock(load=lambda filename: {})
+    )
     flexmock(module).should_receive('schema_to_sample_configuration')
     flexmock(module).should_receive('merge_source_configuration_into_destination')
     flexmock(module).should_receive('render_configuration')

tests/integration/config/test_load.py

@@ -12,36 +12,10 @@ def test_load_configuration_parses_contents():
     config_file = io.StringIO('key: value')
     config_file.name = 'config.yaml'
     builtins.should_receive('open').with_args('config.yaml').and_return(config_file)
-    assert module.load_configuration('config.yaml') == {'key': 'value'}
+    config_paths = {'other.yaml'}
 
-
-def test_load_configuration_replaces_constants():
-    builtins = flexmock(sys.modules['builtins'])
-    config_file = io.StringIO(
-        '''
-        constants:
-            key: value
-        key: {key}
-        '''
-    )
-    config_file.name = 'config.yaml'
-    builtins.should_receive('open').with_args('config.yaml').and_return(config_file)
-    assert module.load_configuration('config.yaml') == {'key': 'value'}
-
-
-def test_load_configuration_replaces_complex_constants():
-    builtins = flexmock(sys.modules['builtins'])
-    config_file = io.StringIO(
-        '''
-        constants:
-            key:
-                subkey: value
-        key: {key}
-        '''
-    )
-    config_file.name = 'config.yaml'
-    builtins.should_receive('open').with_args('config.yaml').and_return(config_file)
-    assert module.load_configuration('config.yaml') == {'key': {'subkey': 'value'}}
+    assert module.load_configuration('config.yaml', config_paths) == {'key': 'value'}
+    assert config_paths == {'config.yaml', 'other.yaml'}
 
 
 def test_load_configuration_with_only_integer_value_does_not_raise():
@@ -49,7 +23,10 @@ def test_load_configuration_with_only_integer_value_does_not_raise():
     config_file = io.StringIO('33')
     config_file.name = 'config.yaml'
     builtins.should_receive('open').with_args('config.yaml').and_return(config_file)
-    assert module.load_configuration('config.yaml') == 33
+    config_paths = {'other.yaml'}
+
+    assert module.load_configuration('config.yaml', config_paths) == 33
+    assert config_paths == {'config.yaml', 'other.yaml'}
 
 
 def test_load_configuration_inlines_include_relative_to_current_directory():
@@ -63,8 +40,10 @@ def test_load_configuration_inlines_include_relative_to_current_directory():
     config_file = io.StringIO('key: !include include.yaml')
     config_file.name = 'config.yaml'
     builtins.should_receive('open').with_args('config.yaml').and_return(config_file)
+    config_paths = {'other.yaml'}
 
-    assert module.load_configuration('config.yaml') == {'key': 'value'}
+    assert module.load_configuration('config.yaml', config_paths) == {'key': 'value'}
+    assert config_paths == {'config.yaml', '/tmp/include.yaml', 'other.yaml'}
 
 
 def test_load_configuration_inlines_include_relative_to_config_parent_directory():
@@ -85,8 +64,10 @@ def test_load_configuration_inlines_include_relative_to_config_parent_directory(
     config_file = io.StringIO('key: !include include.yaml')
     config_file.name = '/etc/config.yaml'
     builtins.should_receive('open').with_args('/etc/config.yaml').and_return(config_file)
+    config_paths = {'other.yaml'}
 
-    assert module.load_configuration('/etc/config.yaml') == {'key': 'value'}
+    assert module.load_configuration('/etc/config.yaml', config_paths) == {'key': 'value'}
+    assert config_paths == {'/etc/config.yaml', '/etc/include.yaml', 'other.yaml'}
 
 
 def test_load_configuration_raises_if_relative_include_does_not_exist():
@@ -99,9 +80,10 @@ def test_load_configuration_raises_if_relative_include_does_not_exist():
     config_file = io.StringIO('key: !include include.yaml')
     config_file.name = '/etc/config.yaml'
     builtins.should_receive('open').with_args('/etc/config.yaml').and_return(config_file)
+    config_paths = set()
 
     with pytest.raises(FileNotFoundError):
-        module.load_configuration('/etc/config.yaml')
+        module.load_configuration('/etc/config.yaml', config_paths)
 
 
 def test_load_configuration_inlines_absolute_include():
@@ -115,8 +97,10 @@ def test_load_configuration_inlines_absolute_include():
     config_file = io.StringIO('key: !include /root/include.yaml')
     config_file.name = 'config.yaml'
     builtins.should_receive('open').with_args('config.yaml').and_return(config_file)
+    config_paths = {'other.yaml'}
 
-    assert module.load_configuration('config.yaml') == {'key': 'value'}
+    assert module.load_configuration('config.yaml', config_paths) == {'key': 'value'}
+    assert config_paths == {'config.yaml', '/root/include.yaml', 'other.yaml'}
 
 
 def test_load_configuration_raises_if_absolute_include_does_not_exist():
@@ -127,9 +111,10 @@ def test_load_configuration_raises_if_absolute_include_does_not_exist():
     config_file = io.StringIO('key: !include /root/include.yaml')
     config_file.name = 'config.yaml'
     builtins.should_receive('open').with_args('config.yaml').and_return(config_file)
+    config_paths = set()
 
     with pytest.raises(FileNotFoundError):
-        assert module.load_configuration('config.yaml')
+        assert module.load_configuration('config.yaml', config_paths)
 
 
 def test_load_configuration_inlines_multiple_file_include_as_list():
@@ -146,8 +131,15 @@ def test_load_configuration_inlines_multiple_file_include_as_list():
     config_file = io.StringIO('key: !include [/root/include1.yaml, /root/include2.yaml]')
     config_file.name = 'config.yaml'
     builtins.should_receive('open').with_args('config.yaml').and_return(config_file)
+    config_paths = {'other.yaml'}
 
-    assert module.load_configuration('config.yaml') == {'key': ['value2', 'value1']}
+    assert module.load_configuration('config.yaml', config_paths) == {'key': ['value2', 'value1']}
+    assert config_paths == {
+        'config.yaml',
+        '/root/include1.yaml',
+        '/root/include2.yaml',
+        'other.yaml',
+    }
 
 
 def test_load_configuration_include_with_unsupported_filename_type_raises():
@@ -158,9 +150,10 @@ def test_load_configuration_include_with_unsupported_filename_type_raises():
     config_file = io.StringIO('key: !include {path: /root/include.yaml}')
     config_file.name = 'config.yaml'
     builtins.should_receive('open').with_args('config.yaml').and_return(config_file)
+    config_paths = set()
 
     with pytest.raises(ValueError):
-        module.load_configuration('config.yaml')
+        module.load_configuration('config.yaml', config_paths)
 
 
 def test_load_configuration_merges_include():
@@ -184,8 +177,13 @@ def test_load_configuration_merges_include():
     )
     config_file.name = 'config.yaml'
     builtins.should_receive('open').with_args('config.yaml').and_return(config_file)
+    config_paths = {'other.yaml'}
 
-    assert module.load_configuration('config.yaml') == {'foo': 'override', 'baz': 'quux'}
+    assert module.load_configuration('config.yaml', config_paths) == {
+        'foo': 'override',
+        'baz': 'quux',
+    }
+    assert config_paths == {'config.yaml', '/tmp/include.yaml', 'other.yaml'}
 
 
 def test_load_configuration_merges_multiple_file_include():
@@ -217,12 +215,14 @@ def test_load_configuration_merges_multiple_file_include():
     )
     config_file.name = 'config.yaml'
     builtins.should_receive('open').with_args('config.yaml').and_return(config_file)
+    config_paths = {'other.yaml'}
 
-    assert module.load_configuration('config.yaml') == {
+    assert module.load_configuration('config.yaml', config_paths) == {
         'foo': 'override',
         'baz': 'second',
         'original': 'yes',
     }
+    assert config_paths == {'config.yaml', '/tmp/include1.yaml', '/tmp/include2.yaml', 'other.yaml'}
 
 
 def test_load_configuration_with_retain_tag_merges_include_but_keeps_local_values():
@@ -255,11 +255,13 @@ def test_load_configuration_with_retain_tag_merges_include_but_keeps_local_value
     )
     config_file.name = 'config.yaml'
     builtins.should_receive('open').with_args('config.yaml').and_return(config_file)
+    config_paths = {'other.yaml'}
 
-    assert module.load_configuration('config.yaml') == {
+    assert module.load_configuration('config.yaml', config_paths) == {
         'stuff': {'foo': 'override'},
         'other': {'a': 'override', 'c': 'd'},
     }
+    assert config_paths == {'config.yaml', '/tmp/include.yaml', 'other.yaml'}
 
 
 def test_load_configuration_with_retain_tag_but_without_merge_include_raises():
@@ -285,9 +287,10 @@ def test_load_configuration_with_retain_tag_but_without_merge_include_raises():
     )
     config_file.name = 'config.yaml'
     builtins.should_receive('open').with_args('config.yaml').and_return(config_file)
+    config_paths = set()
 
     with pytest.raises(ValueError):
-        module.load_configuration('config.yaml')
+        module.load_configuration('config.yaml', config_paths)
 
 
 def test_load_configuration_with_retain_tag_on_scalar_raises():
@@ -313,9 +316,10 @@ def test_load_configuration_with_retain_tag_on_scalar_raises():
     )
     config_file.name = 'config.yaml'
     builtins.should_receive('open').with_args('config.yaml').and_return(config_file)
+    config_paths = set()
 
     with pytest.raises(ValueError):
-        module.load_configuration('config.yaml')
+        module.load_configuration('config.yaml', config_paths)
 
 
 def test_load_configuration_with_omit_tag_merges_include_and_omits_requested_values():
@@ -344,8 +348,10 @@ def test_load_configuration_with_omit_tag_merges_include_and_omits_requested_val
     )
     config_file.name = 'config.yaml'
     builtins.should_receive('open').with_args('config.yaml').and_return(config_file)
+    config_paths = {'other.yaml'}
 
-    assert module.load_configuration('config.yaml') == {'stuff': ['a', 'c', 'x', 'y']}
+    assert module.load_configuration('config.yaml', config_paths) == {'stuff': ['a', 'c', 'x', 'y']}
+    assert config_paths == {'config.yaml', '/tmp/include.yaml', 'other.yaml'}
 
 
 def test_load_configuration_with_omit_tag_on_unknown_value_merges_include_and_does_not_raise():
@@ -374,8 +380,12 @@ def test_load_configuration_with_omit_tag_on_unknown_value_merges_include_and_do
     )
     config_file.name = 'config.yaml'
     builtins.should_receive('open').with_args('config.yaml').and_return(config_file)
+    config_paths = {'other.yaml'}
 
-    assert module.load_configuration('config.yaml') == {'stuff': ['a', 'b', 'c', 'x', 'y']}
+    assert module.load_configuration('config.yaml', config_paths) == {
+        'stuff': ['a', 'b', 'c', 'x', 'y']
+    }
+    assert config_paths == {'config.yaml', '/tmp/include.yaml', 'other.yaml'}
 
 
 def test_load_configuration_with_omit_tag_on_non_list_item_raises():
@@ -403,9 +413,10 @@ def test_load_configuration_with_omit_tag_on_non_list_item_raises():
     )
     config_file.name = 'config.yaml'
     builtins.should_receive('open').with_args('config.yaml').and_return(config_file)
+    config_paths = set()
 
     with pytest.raises(ValueError):
-        module.load_configuration('config.yaml')
+        module.load_configuration('config.yaml', config_paths)
 
 
 def test_load_configuration_with_omit_tag_on_non_scalar_list_item_raises():
@@ -432,9 +443,10 @@ def test_load_configuration_with_omit_tag_on_non_scalar_list_item_raises():
     )
     config_file.name = 'config.yaml'
     builtins.should_receive('open').with_args('config.yaml').and_return(config_file)
+    config_paths = set()
 
     with pytest.raises(ValueError):
-        module.load_configuration('config.yaml')
+        module.load_configuration('config.yaml', config_paths)
 
 
 def test_load_configuration_with_omit_tag_but_without_merge_raises():
@@ -462,9 +474,10 @@ def test_load_configuration_with_omit_tag_but_without_merge_raises():
     )
     config_file.name = 'config.yaml'
     builtins.should_receive('open').with_args('config.yaml').and_return(config_file)
+    config_paths = set()
 
     with pytest.raises(ValueError):
-        module.load_configuration('config.yaml')
+        module.load_configuration('config.yaml', config_paths)
 
 
 def test_load_configuration_does_not_merge_include_list():
@@ -489,9 +502,10 @@ def test_load_configuration_does_not_merge_include_list():
     )
     config_file.name = 'config.yaml'
     builtins.should_receive('open').with_args('config.yaml').and_return(config_file)
+    config_paths = set()
 
     with pytest.raises(module.ruamel.yaml.error.YAMLError):
-        assert module.load_configuration('config.yaml')
+        assert module.load_configuration('config.yaml', config_paths)
 
 
 @pytest.mark.parametrize(

tests/integration/config/test_override.py

@@ -4,19 +4,24 @@ from borgmatic.config import override as module
 
 
 @pytest.mark.parametrize(
-    'value,expected_result',
+    'value,expected_result,option_type',
     (
-        ('thing', 'thing'),
-        ('33', 33),
-        ('33b', '33b'),
-        ('true', True),
-        ('false', False),
-        ('[foo]', ['foo']),
-        ('[foo, bar]', ['foo', 'bar']),
+        ('thing', 'thing', 'string'),
+        ('33', 33, 'integer'),
+        ('33', '33', 'string'),
+        ('33b', '33b', 'integer'),
+        ('33b', '33b', 'string'),
+        ('true', True, 'boolean'),
+        ('false', False, 'boolean'),
+        ('true', 'true', 'string'),
+        ('[foo]', ['foo'], 'array'),
+        ('[foo]', '[foo]', 'string'),
+        ('[foo, bar]', ['foo', 'bar'], 'array'),
+        ('[foo, bar]', '[foo, bar]', 'string'),
     ),
 )
-def test_convert_value_type_coerces_values(value, expected_result):
-    assert module.convert_value_type(value) == expected_result
+def test_convert_value_type_coerces_values(value, expected_result, option_type):
+    assert module.convert_value_type(value, option_type) == expected_result
 
 
 def test_apply_overrides_updates_config():
@@ -25,16 +30,23 @@ def test_apply_overrides_updates_config():
         'other_section.thing=value2',
         'section.nested.key=value3',
         'new.foo=bar',
+        'new.mylist=[baz]',
+        'new.nonlist=[quux]',
     ]
     config = {
         'section': {'key': 'value', 'other': 'other_value'},
         'other_section': {'thing': 'thing_value'},
     }
+    schema = {
+        'properties': {
+            'new': {'properties': {'mylist': {'type': 'array'}, 'nonlist': {'type': 'string'}}}
+        }
+    }
 
-    module.apply_overrides(config, raw_overrides)
+    module.apply_overrides(config, schema, raw_overrides)
 
     assert config == {
         'section': {'key': 'value1', 'other': 'other_value', 'nested': {'key': 'value3'}},
         'other_section': {'thing': 'value2'},
-        'new': {'foo': 'bar'},
+        'new': {'foo': 'bar', 'mylist': ['baz'], 'nonlist': '[quux]'},
     }

tests/integration/config/test_schema.py

@@ -1,3 +1,9 @@
+import pkgutil
+
+import borgmatic.actions
+import borgmatic.config.load
+import borgmatic.config.validate
+
 MAXIMUM_LINE_LENGTH = 80
 
 
@@ -6,3 +12,23 @@ def test_schema_line_length_stays_under_limit():
 
     for line in schema_file.readlines():
         assert len(line.rstrip('\n')) <= MAXIMUM_LINE_LENGTH
+
+
+ACTIONS_MODULE_NAMES_TO_OMIT = {'arguments', 'export_key', 'json'}
+ACTIONS_MODULE_NAMES_TO_ADD = {'key', 'umount'}
+
+
+def test_schema_skip_actions_correspond_to_supported_actions():
+    '''
+    Ensure that the allowed actions in the schema's "skip_actions" option don't drift from
+    borgmatic's actual supported actions.
+    '''
+    schema = borgmatic.config.load.load_configuration(borgmatic.config.validate.schema_filename())
+    schema_skip_actions = set(schema['properties']['skip_actions']['items']['enum'])
+    supported_actions = {
+        module.name.replace('_', '-')
+        for module in pkgutil.iter_modules(borgmatic.actions.__path__)
+        if module.name not in ACTIONS_MODULE_NAMES_TO_OMIT
+    }.union(ACTIONS_MODULE_NAMES_TO_ADD)
+
+    assert schema_skip_actions == supported_actions

tests/integration/config/test_validate.py

@@ -1,4 +1,5 @@
 import io
+import os
 import string
 import sys
 
@@ -57,7 +58,7 @@ def test_parse_configuration_transforms_file_into_mapping():
         '''
     )
 
-    config, logs = module.parse_configuration('/tmp/config.yaml', '/tmp/schema.yaml')
+    config, config_paths, logs = module.parse_configuration('/tmp/config.yaml', '/tmp/schema.yaml')
 
     assert config == {
         'source_directories': ['/home', '/etc'],
@@ -67,6 +68,7 @@ def test_parse_configuration_transforms_file_into_mapping():
         'keep_minutely': 60,
         'checks': [{'name': 'repository'}, {'name': 'archives'}],
     }
+    assert config_paths == {'/tmp/config.yaml'}
     assert logs == []
 
 
@@ -83,12 +85,13 @@ def test_parse_configuration_passes_through_quoted_punctuation():
         '''
     )
 
-    config, logs = module.parse_configuration('/tmp/config.yaml', '/tmp/schema.yaml')
+    config, config_paths, logs = module.parse_configuration('/tmp/config.yaml', '/tmp/schema.yaml')
 
     assert config == {
         'source_directories': [f'/home/{string.punctuation}'],
         'repositories': [{'path': 'test.borg'}],
     }
+    assert config_paths == {'/tmp/config.yaml'}
     assert logs == []
 
 
@@ -140,7 +143,7 @@ def test_parse_configuration_inlines_include_inside_deprecated_section():
     include_file.name = 'include.yaml'
     builtins.should_receive('open').with_args('/tmp/include.yaml').and_return(include_file)
 
-    config, logs = module.parse_configuration('/tmp/config.yaml', '/tmp/schema.yaml')
+    config, config_paths, logs = module.parse_configuration('/tmp/config.yaml', '/tmp/schema.yaml')
 
     assert config == {
         'source_directories': ['/home'],
@@ -148,6 +151,7 @@ def test_parse_configuration_inlines_include_inside_deprecated_section():
         'keep_daily': 7,
         'keep_hourly': 24,
     }
+    assert config_paths == {'/tmp/include.yaml', '/tmp/config.yaml'}
     assert len(logs) == 1
 
 
@@ -174,7 +178,7 @@ def test_parse_configuration_merges_include():
     include_file.name = 'include.yaml'
     builtins.should_receive('open').with_args('/tmp/include.yaml').and_return(include_file)
 
-    config, logs = module.parse_configuration('/tmp/config.yaml', '/tmp/schema.yaml')
+    config, config_paths, logs = module.parse_configuration('/tmp/config.yaml', '/tmp/schema.yaml')
 
     assert config == {
         'source_directories': ['/home'],
@@ -182,6 +186,7 @@ def test_parse_configuration_merges_include():
         'keep_daily': 1,
         'keep_hourly': 24,
     }
+    assert config_paths == {'/tmp/include.yaml', '/tmp/config.yaml'}
     assert logs == []
 
 
@@ -193,6 +198,9 @@ def test_parse_configuration_raises_for_missing_config_file():
 def test_parse_configuration_raises_for_missing_schema_file():
     mock_config_and_schema('')
     builtins = flexmock(sys.modules['builtins'])
+    builtins.should_receive('open').with_args('/tmp/config.yaml').and_return(
+        io.StringIO('foo: bar')
+    )
     builtins.should_receive('open').with_args('/tmp/schema.yaml').and_raise(FileNotFoundError)
 
     with pytest.raises(FileNotFoundError):
@@ -232,7 +240,7 @@ def test_parse_configuration_applies_overrides():
         '''
     )
 
-    config, logs = module.parse_configuration(
+    config, config_paths, logs = module.parse_configuration(
         '/tmp/config.yaml', '/tmp/schema.yaml', overrides=['location.local_path=borg2']
     )
 
@@ -241,10 +249,11 @@ def test_parse_configuration_applies_overrides():
         'repositories': [{'path': 'hostname.borg'}],
         'local_path': 'borg2',
     }
+    assert config_paths == {'/tmp/config.yaml'}
     assert logs == []
 
 
-def test_parse_configuration_applies_normalization():
+def test_parse_configuration_applies_normalization_after_environment_variable_interpolation():
     mock_config_and_schema(
         '''
         location:
@@ -252,17 +261,19 @@ def test_parse_configuration_applies_normalization():
                 - /home
 
             repositories:
-                - path: hostname.borg
+                - ${NO_EXIST:-user@hostname:repo}
 
             exclude_if_present: .nobackup
         '''
     )
+    flexmock(os).should_receive('getenv').replace_with(lambda variable_name, default: default)
 
-    config, logs = module.parse_configuration('/tmp/config.yaml', '/tmp/schema.yaml')
+    config, config_paths, logs = module.parse_configuration('/tmp/config.yaml', '/tmp/schema.yaml')
 
     assert config == {
         'source_directories': ['/home'],
-        'repositories': [{'path': 'hostname.borg'}],
+        'repositories': [{'path': 'ssh://user@hostname/./repo'}],
         'exclude_if_present': ['.nobackup'],
     }
+    assert config_paths == {'/tmp/config.yaml'}
     assert logs

tests/integration/hooks/test_loki.py

@@ -0,0 +1,89 @@
+import logging
+import platform
+
+from flexmock import flexmock
+
+from borgmatic.hooks import loki as module
+
+
+def test_initialize_monitor_replaces_labels():
+    '''
+    Assert that label placeholders get replaced.
+    '''
+    hook_config = {
+        'url': 'http://localhost:3100/loki/api/v1/push',
+        'labels': {'hostname': '__hostname', 'config': '__config', 'config_full': '__config_path'},
+    }
+    config_filename = '/mock/path/test.yaml'
+    dry_run = True
+    module.initialize_monitor(hook_config, flexmock(), config_filename, flexmock(), dry_run)
+
+    for handler in tuple(logging.getLogger().handlers):
+        if isinstance(handler, module.Loki_log_handler):
+            assert handler.buffer.root['streams'][0]['stream']['hostname'] == platform.node()
+            assert handler.buffer.root['streams'][0]['stream']['config'] == 'test.yaml'
+            assert handler.buffer.root['streams'][0]['stream']['config_full'] == config_filename
+            return
+
+    assert False
+
+
+def test_initialize_monitor_adds_log_handler():
+    '''
+    Assert that calling initialize_monitor adds our logger to the root logger.
+    '''
+    hook_config = {'url': 'http://localhost:3100/loki/api/v1/push', 'labels': {'app': 'borgmatic'}}
+    module.initialize_monitor(
+        hook_config,
+        flexmock(),
+        config_filename='test.yaml',
+        monitoring_log_level=flexmock(),
+        dry_run=True,
+    )
+
+    for handler in tuple(logging.getLogger().handlers):
+        if isinstance(handler, module.Loki_log_handler):
+            return
+
+    assert False
+
+
+def test_ping_monitor_adds_log_message():
+    '''
+    Assert that calling ping_monitor adds a message to our logger.
+    '''
+    hook_config = {'url': 'http://localhost:3100/loki/api/v1/push', 'labels': {'app': 'borgmatic'}}
+    config_filename = 'test.yaml'
+    dry_run = True
+    module.initialize_monitor(hook_config, flexmock(), config_filename, flexmock(), dry_run)
+    module.ping_monitor(
+        hook_config, flexmock(), config_filename, module.monitor.State.FINISH, flexmock(), dry_run
+    )
+
+    for handler in tuple(logging.getLogger().handlers):
+        if isinstance(handler, module.Loki_log_handler):
+            assert any(
+                map(
+                    lambda log: log
+                    == f'{config_filename}: {module.MONITOR_STATE_TO_LOKI[module.monitor.State.FINISH]} backup',
+                    map(lambda x: x[1], handler.buffer.root['streams'][0]['values']),
+                )
+            )
+            return
+
+    assert False
+
+
+def test_destroy_monitor_removes_log_handler():
+    '''
+    Assert that destroy_monitor removes the logger from the root logger.
+    '''
+    hook_config = {'url': 'http://localhost:3100/loki/api/v1/push', 'labels': {'app': 'borgmatic'}}
+    config_filename = 'test.yaml'
+    dry_run = True
+    module.initialize_monitor(hook_config, flexmock(), config_filename, flexmock(), dry_run)
+    module.destroy_monitor(hook_config, flexmock(), config_filename, flexmock(), dry_run)
+
+    for handler in tuple(logging.getLogger().handlers):
+        if isinstance(handler, module.Loki_log_handler):
+            assert False

tests/integration/test_execute.py

@@ -11,7 +11,7 @@ from borgmatic import execute as module
 def test_log_outputs_logs_each_line_separately():
     flexmock(module.logger).should_receive('log').with_args(logging.INFO, 'hi').once()
     flexmock(module.logger).should_receive('log').with_args(logging.INFO, 'there').once()
-    flexmock(module).should_receive('exit_code_indicates_error').and_return(False)
+    flexmock(module).should_receive('interpret_exit_code').and_return(module.Exit_status.SUCCESS)
 
     hi_process = subprocess.Popen(['echo', 'hi'], stdout=subprocess.PIPE)
     flexmock(module).should_receive('output_buffer_for_process').with_args(
@@ -28,13 +28,14 @@ def test_log_outputs_logs_each_line_separately():
         exclude_stdouts=(),
         output_log_level=logging.INFO,
         borg_local_path='borg',
+        borg_exit_codes=None,
     )
 
 
 def test_log_outputs_skips_logs_for_process_with_none_stdout():
     flexmock(module.logger).should_receive('log').with_args(logging.INFO, 'hi').never()
     flexmock(module.logger).should_receive('log').with_args(logging.INFO, 'there').once()
-    flexmock(module).should_receive('exit_code_indicates_error').and_return(False)
+    flexmock(module).should_receive('interpret_exit_code').and_return(module.Exit_status.SUCCESS)
 
     hi_process = subprocess.Popen(['echo', 'hi'], stdout=None)
     flexmock(module).should_receive('output_buffer_for_process').with_args(
@@ -51,12 +52,13 @@ def test_log_outputs_skips_logs_for_process_with_none_stdout():
         exclude_stdouts=(),
         output_log_level=logging.INFO,
         borg_local_path='borg',
+        borg_exit_codes=None,
     )
 
 
 def test_log_outputs_returns_output_without_logging_for_output_log_level_none():
     flexmock(module.logger).should_receive('log').never()
-    flexmock(module).should_receive('exit_code_indicates_error').and_return(False)
+    flexmock(module).should_receive('interpret_exit_code').and_return(module.Exit_status.SUCCESS)
 
     hi_process = subprocess.Popen(['echo', 'hi'], stdout=subprocess.PIPE)
     flexmock(module).should_receive('output_buffer_for_process').with_args(
@@ -73,6 +75,7 @@ def test_log_outputs_returns_output_without_logging_for_output_log_level_none():
         exclude_stdouts=(),
         output_log_level=None,
         borg_local_path='borg',
+        borg_exit_codes=None,
     )
 
     assert captured_outputs == {hi_process: 'hi', there_process: 'there'}
@@ -80,7 +83,7 @@ def test_log_outputs_returns_output_without_logging_for_output_log_level_none():
 
 def test_log_outputs_includes_error_output_in_exception():
     flexmock(module.logger).should_receive('log')
-    flexmock(module).should_receive('exit_code_indicates_error').and_return(True)
+    flexmock(module).should_receive('interpret_exit_code').and_return(module.Exit_status.ERROR)
     flexmock(module).should_receive('command_for_process').and_return('grep')
 
     process = subprocess.Popen(['grep'], stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
@@ -88,7 +91,11 @@ def test_log_outputs_includes_error_output_in_exception():
 
     with pytest.raises(subprocess.CalledProcessError) as error:
         module.log_outputs(
-            (process,), exclude_stdouts=(), output_log_level=logging.INFO, borg_local_path='borg'
+            (process,),
+            exclude_stdouts=(),
+            output_log_level=logging.INFO,
+            borg_local_path='borg',
+            borg_exit_codes=None,
         )
 
     assert error.value.output
@@ -100,7 +107,7 @@ def test_log_outputs_logs_multiline_error_output():
     of a process' traceback.
     '''
     flexmock(module.logger).should_receive('log')
-    flexmock(module).should_receive('exit_code_indicates_error').and_return(True)
+    flexmock(module).should_receive('interpret_exit_code').and_return(module.Exit_status.ERROR)
     flexmock(module).should_receive('command_for_process').and_return('grep')
 
     process = subprocess.Popen(
@@ -111,13 +118,17 @@ def test_log_outputs_logs_multiline_error_output():
 
     with pytest.raises(subprocess.CalledProcessError):
         module.log_outputs(
-            (process,), exclude_stdouts=(), output_log_level=logging.INFO, borg_local_path='borg'
+            (process,),
+            exclude_stdouts=(),
+            output_log_level=logging.INFO,
+            borg_local_path='borg',
+            borg_exit_codes=None,
         )
 
 
 def test_log_outputs_skips_error_output_in_exception_for_process_with_none_stdout():
     flexmock(module.logger).should_receive('log')
-    flexmock(module).should_receive('exit_code_indicates_error').and_return(True)
+    flexmock(module).should_receive('interpret_exit_code').and_return(module.Exit_status.ERROR)
     flexmock(module).should_receive('command_for_process').and_return('grep')
 
     process = subprocess.Popen(['grep'], stdout=None)
@@ -125,30 +136,43 @@ def test_log_outputs_skips_error_output_in_exception_for_process_with_none_stdou
 
     with pytest.raises(subprocess.CalledProcessError) as error:
         module.log_outputs(
-            (process,), exclude_stdouts=(), output_log_level=logging.INFO, borg_local_path='borg'
+            (process,),
+            exclude_stdouts=(),
+            output_log_level=logging.INFO,
+            borg_local_path='borg',
+            borg_exit_codes=None,
         )
 
     assert error.value.returncode == 2
     assert not error.value.output
 
 
-def test_log_outputs_kills_other_processes_when_one_errors():
+def test_log_outputs_kills_other_processes_and_raises_when_one_errors():
     flexmock(module.logger).should_receive('log')
     flexmock(module).should_receive('command_for_process').and_return('grep')
 
     process = subprocess.Popen(['grep'], stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
-    flexmock(module).should_receive('exit_code_indicates_error').with_args(
-        ['grep'], None, 'borg'
-    ).and_return(False)
-    flexmock(module).should_receive('exit_code_indicates_error').with_args(
-        ['grep'], 2, 'borg'
-    ).and_return(True)
+    flexmock(module).should_receive('interpret_exit_code').with_args(
+        ['grep'],
+        None,
+        'borg',
+        None,
+    ).and_return(module.Exit_status.SUCCESS)
+    flexmock(module).should_receive('interpret_exit_code').with_args(
+        ['grep'],
+        2,
+        'borg',
+        None,
+    ).and_return(module.Exit_status.ERROR)
     other_process = subprocess.Popen(
         ['sleep', '2'], stdout=subprocess.PIPE, stderr=subprocess.STDOUT
     )
-    flexmock(module).should_receive('exit_code_indicates_error').with_args(
-        ['sleep', '2'], None, 'borg'
-    ).and_return(False)
+    flexmock(module).should_receive('interpret_exit_code').with_args(
+        ['sleep', '2'],
+        None,
+        'borg',
+        None,
+    ).and_return(module.Exit_status.SUCCESS)
     flexmock(module).should_receive('output_buffer_for_process').with_args(process, ()).and_return(
         process.stdout
     )
@@ -163,12 +187,56 @@ def test_log_outputs_kills_other_processes_when_one_errors():
             exclude_stdouts=(),
             output_log_level=logging.INFO,
             borg_local_path='borg',
+            borg_exit_codes=None,
         )
 
     assert error.value.returncode == 2
     assert error.value.output
 
 
+def test_log_outputs_kills_other_processes_and_returns_when_one_exits_with_warning():
+    flexmock(module.logger).should_receive('log')
+    flexmock(module).should_receive('command_for_process').and_return('grep')
+
+    process = subprocess.Popen(['grep'], stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
+    flexmock(module).should_receive('interpret_exit_code').with_args(
+        ['grep'],
+        None,
+        'borg',
+        None,
+    ).and_return(module.Exit_status.SUCCESS)
+    flexmock(module).should_receive('interpret_exit_code').with_args(
+        ['grep'],
+        2,
+        'borg',
+        None,
+    ).and_return(module.Exit_status.WARNING)
+    other_process = subprocess.Popen(
+        ['sleep', '2'], stdout=subprocess.PIPE, stderr=subprocess.STDOUT
+    )
+    flexmock(module).should_receive('interpret_exit_code').with_args(
+        ['sleep', '2'],
+        None,
+        'borg',
+        None,
+    ).and_return(module.Exit_status.SUCCESS)
+    flexmock(module).should_receive('output_buffer_for_process').with_args(process, ()).and_return(
+        process.stdout
+    )
+    flexmock(module).should_receive('output_buffer_for_process').with_args(
+        other_process, ()
+    ).and_return(other_process.stdout)
+    flexmock(other_process).should_receive('kill').once()
+
+    module.log_outputs(
+        (process, other_process),
+        exclude_stdouts=(),
+        output_log_level=logging.INFO,
+        borg_local_path='borg',
+        borg_exit_codes=None,
+    )
+
+
 def test_log_outputs_vents_other_processes_when_one_exits():
     '''
     Execute a command to generate a longish random string and pipe it into another command that
@@ -204,6 +272,7 @@ def test_log_outputs_vents_other_processes_when_one_exits():
         exclude_stdouts=(process.stdout,),
         output_log_level=logging.INFO,
         borg_local_path='borg',
+        borg_exit_codes=None,
     )
 
 
@@ -235,6 +304,7 @@ def test_log_outputs_does_not_error_when_one_process_exits():
         exclude_stdouts=(process.stdout,),
         output_log_level=logging.INFO,
         borg_local_path='borg',
+        borg_exit_codes=None,
     )
 
 
@@ -243,17 +313,27 @@ def test_log_outputs_truncates_long_error_output():
     flexmock(module).should_receive('command_for_process').and_return('grep')
 
     process = subprocess.Popen(['grep'], stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
-    flexmock(module).should_receive('exit_code_indicates_error').with_args(
-        ['grep'], None, 'borg'
-    ).and_return(False)
-    flexmock(module).should_receive('exit_code_indicates_error').with_args(
-        ['grep'], 2, 'borg'
-    ).and_return(True)
+    flexmock(module).should_receive('interpret_exit_code').with_args(
+        ['grep'],
+        None,
+        'borg',
+        None,
+    ).and_return(module.Exit_status.SUCCESS)
+    flexmock(module).should_receive('interpret_exit_code').with_args(
+        ['grep'],
+        2,
+        'borg',
+        None,
+    ).and_return(module.Exit_status.ERROR)
     flexmock(module).should_receive('output_buffer_for_process').and_return(process.stdout)
 
     with pytest.raises(subprocess.CalledProcessError) as error:
         flexmock(module, ERROR_OUTPUT_MAX_LINE_COUNT=0).log_outputs(
-            (process,), exclude_stdouts=(), output_log_level=logging.INFO, borg_local_path='borg'
+            (process,),
+            exclude_stdouts=(),
+            output_log_level=logging.INFO,
+            borg_local_path='borg',
+            borg_exit_codes=None,
         )
 
     assert error.value.returncode == 2
@@ -262,24 +342,32 @@ def test_log_outputs_truncates_long_error_output():
 
 def test_log_outputs_with_no_output_logs_nothing():
     flexmock(module.logger).should_receive('log').never()
-    flexmock(module).should_receive('exit_code_indicates_error').and_return(False)
+    flexmock(module).should_receive('interpret_exit_code').and_return(module.Exit_status.SUCCESS)
 
     process = subprocess.Popen(['true'], stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
     flexmock(module).should_receive('output_buffer_for_process').and_return(process.stdout)
 
     module.log_outputs(
-        (process,), exclude_stdouts=(), output_log_level=logging.INFO, borg_local_path='borg'
+        (process,),
+        exclude_stdouts=(),
+        output_log_level=logging.INFO,
+        borg_local_path='borg',
+        borg_exit_codes=None,
     )
 
 
 def test_log_outputs_with_unfinished_process_re_polls():
     flexmock(module.logger).should_receive('log').never()
-    flexmock(module).should_receive('exit_code_indicates_error').and_return(False)
+    flexmock(module).should_receive('interpret_exit_code').and_return(module.Exit_status.SUCCESS)
 
     process = subprocess.Popen(['true'], stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
     flexmock(process).should_receive('poll').and_return(None).and_return(0).times(3)
     flexmock(module).should_receive('output_buffer_for_process').and_return(process.stdout)
 
     module.log_outputs(
-        (process,), exclude_stdouts=(), output_log_level=logging.INFO, borg_local_path='borg'
+        (process,),
+        exclude_stdouts=(),
+        output_log_level=logging.INFO,
+        borg_local_path='borg',
+        borg_exit_codes=None,
     )

tests/unit/actions/config/test_bootstrap.py

@@ -9,6 +9,7 @@ def test_get_config_paths_returns_list_of_config_paths():
         borgmatic_source_directory=None,
         repository='repo',
         archive='archive',
+        ssh_command=None,
     )
     global_arguments = flexmock(
         dry_run=False,
@@ -30,11 +31,46 @@ def test_get_config_paths_returns_list_of_config_paths():
     ]
 
 
+def test_get_config_paths_translates_ssh_command_argument_to_config():
+    bootstrap_arguments = flexmock(
+        borgmatic_source_directory=None,
+        repository='repo',
+        archive='archive',
+        ssh_command='ssh -i key',
+    )
+    global_arguments = flexmock(
+        dry_run=False,
+    )
+    local_borg_version = flexmock()
+    extract_process = flexmock(
+        stdout=flexmock(
+            read=lambda: '{"config_paths": ["/borgmatic/config.yaml"]}',
+        ),
+    )
+    flexmock(module.borgmatic.borg.extract).should_receive('extract_archive').with_args(
+        False,
+        'repo',
+        'archive',
+        object,
+        {'ssh_command': 'ssh -i key'},
+        object,
+        object,
+        extract_to_stdout=True,
+    ).and_return(extract_process)
+    flexmock(module.borgmatic.borg.rlist).should_receive('resolve_archive_name').with_args(
+        'repo', 'archive', {'ssh_command': 'ssh -i key'}, object, object
+    ).and_return('archive')
+    assert module.get_config_paths(bootstrap_arguments, global_arguments, local_borg_version) == [
+        '/borgmatic/config.yaml'
+    ]
+
+
 def test_get_config_paths_with_missing_manifest_raises_value_error():
     bootstrap_arguments = flexmock(
         borgmatic_source_directory=None,
         repository='repo',
         archive='archive',
+        ssh_command=None,
     )
     global_arguments = flexmock(
         dry_run=False,
@@ -57,6 +93,7 @@ def test_get_config_paths_with_broken_json_raises_value_error():
         borgmatic_source_directory=None,
         repository='repo',
         archive='archive',
+        ssh_command=None,
     )
     global_arguments = flexmock(
         dry_run=False,
@@ -81,6 +118,7 @@ def test_get_config_paths_with_json_missing_key_raises_value_error():
         borgmatic_source_directory=None,
         repository='repo',
         archive='archive',
+        ssh_command=None,
     )
     global_arguments = flexmock(
         dry_run=False,
@@ -101,6 +139,7 @@ def test_get_config_paths_with_json_missing_key_raises_value_error():
 
 
 def test_run_bootstrap_does_not_raise():
+    flexmock(module).should_receive('get_config_paths').and_return(['/borgmatic/config.yaml'])
     bootstrap_arguments = flexmock(
         repository='repo',
         archive='archive',
@@ -108,6 +147,7 @@ def test_run_bootstrap_does_not_raise():
         strip_components=1,
         progress=False,
         borgmatic_source_directory='/borgmatic',
+        ssh_command=None,
     )
     global_arguments = flexmock(
         dry_run=False,
@@ -115,14 +155,54 @@ def test_run_bootstrap_does_not_raise():
     local_borg_version = flexmock()
     extract_process = flexmock(
         stdout=flexmock(
-            read=lambda: '{"config_paths": ["/borgmatic/config.yaml"]}',
+            read=lambda: '{"config_paths": ["borgmatic/config.yaml"]}',
         ),
     )
     flexmock(module.borgmatic.borg.extract).should_receive('extract_archive').and_return(
         extract_process
-    ).twice()
+    ).once()
     flexmock(module.borgmatic.borg.rlist).should_receive('resolve_archive_name').and_return(
         'archive'
     )
 
     module.run_bootstrap(bootstrap_arguments, global_arguments, local_borg_version)
+
+
+def test_run_bootstrap_translates_ssh_command_argument_to_config():
+    flexmock(module).should_receive('get_config_paths').and_return(['/borgmatic/config.yaml'])
+    bootstrap_arguments = flexmock(
+        repository='repo',
+        archive='archive',
+        destination='dest',
+        strip_components=1,
+        progress=False,
+        borgmatic_source_directory='/borgmatic',
+        ssh_command='ssh -i key',
+    )
+    global_arguments = flexmock(
+        dry_run=False,
+    )
+    local_borg_version = flexmock()
+    extract_process = flexmock(
+        stdout=flexmock(
+            read=lambda: '{"config_paths": ["borgmatic/config.yaml"]}',
+        ),
+    )
+    flexmock(module.borgmatic.borg.extract).should_receive('extract_archive').with_args(
+        False,
+        'repo',
+        'archive',
+        object,
+        {'ssh_command': 'ssh -i key'},
+        object,
+        object,
+        extract_to_stdout=False,
+        destination_path='dest',
+        strip_components=1,
+        progress=False,
+    ).and_return(extract_process).once()
+    flexmock(module.borgmatic.borg.rlist).should_receive('resolve_archive_name').with_args(
+        'repo', 'archive', {'ssh_command': 'ssh -i key'}, object, object
+    ).and_return('archive')
+
+    module.run_bootstrap(bootstrap_arguments, global_arguments, local_borg_version)

tests/unit/actions/test_create.py

@@ -19,16 +19,17 @@ def test_run_create_executes_and_calls_hooks_for_configured_repository():
         repository=None,
         progress=flexmock(),
         stats=flexmock(),
-        json=flexmock(),
+        json=False,
         list_files=flexmock(),
     )
-    global_arguments = flexmock(monitoring_verbosity=1, dry_run=False, used_config_paths=[])
+    global_arguments = flexmock(monitoring_verbosity=1, dry_run=False)
 
     list(
         module.run_create(
             config_filename='test.yaml',
             repository={'path': 'repo'},
             config={},
+            config_paths=['/tmp/test.yaml'],
             hook_context={},
             local_borg_version=None,
             create_arguments=create_arguments,
@@ -54,16 +55,17 @@ def test_run_create_with_store_config_files_false_does_not_create_borgmatic_mani
         repository=None,
         progress=flexmock(),
         stats=flexmock(),
-        json=flexmock(),
+        json=False,
         list_files=flexmock(),
     )
-    global_arguments = flexmock(monitoring_verbosity=1, dry_run=False, used_config_paths=[])
+    global_arguments = flexmock(monitoring_verbosity=1, dry_run=False)
 
     list(
         module.run_create(
             config_filename='test.yaml',
             repository={'path': 'repo'},
             config={'store_config_files': False},
+            config_paths=['/tmp/test.yaml'],
             hook_context={},
             local_borg_version=None,
             create_arguments=create_arguments,
@@ -91,16 +93,17 @@ def test_run_create_runs_with_selected_repository():
         repository=flexmock(),
         progress=flexmock(),
         stats=flexmock(),
-        json=flexmock(),
+        json=False,
         list_files=flexmock(),
     )
-    global_arguments = flexmock(monitoring_verbosity=1, dry_run=False, used_config_paths=[])
+    global_arguments = flexmock(monitoring_verbosity=1, dry_run=False)
 
     list(
         module.run_create(
             config_filename='test.yaml',
             repository={'path': 'repo'},
             config={},
+            config_paths=['/tmp/test.yaml'],
             hook_context={},
             local_borg_version=None,
             create_arguments=create_arguments,
@@ -123,16 +126,17 @@ def test_run_create_bails_if_repository_does_not_match():
         repository=flexmock(),
         progress=flexmock(),
         stats=flexmock(),
-        json=flexmock(),
+        json=False,
         list_files=flexmock(),
     )
-    global_arguments = flexmock(monitoring_verbosity=1, dry_run=False, used_config_paths=[])
+    global_arguments = flexmock(monitoring_verbosity=1, dry_run=False)
 
     list(
         module.run_create(
             config_filename='test.yaml',
             repository='repo',
             config={},
+            config_paths=['/tmp/test.yaml'],
             hook_context={},
             local_borg_version=None,
             create_arguments=create_arguments,
@@ -144,6 +148,48 @@ def test_run_create_bails_if_repository_does_not_match():
     )
 
 
+def test_run_create_produces_json():
+    flexmock(module.logger).answer = lambda message: None
+    flexmock(module.borgmatic.config.validate).should_receive(
+        'repositories_match'
+    ).once().and_return(True)
+    flexmock(module.borgmatic.borg.create).should_receive('create_archive').once().and_return(
+        flexmock()
+    )
+    parsed_json = flexmock()
+    flexmock(module.borgmatic.actions.json).should_receive('parse_json').and_return(parsed_json)
+    flexmock(module).should_receive('create_borgmatic_manifest').once()
+    flexmock(module.borgmatic.hooks.command).should_receive('execute_hook').times(2)
+    flexmock(module.borgmatic.hooks.dispatch).should_receive('call_hooks').and_return({})
+    flexmock(module.borgmatic.hooks.dispatch).should_receive(
+        'call_hooks_even_if_unconfigured'
+    ).and_return({})
+    create_arguments = flexmock(
+        repository=flexmock(),
+        progress=flexmock(),
+        stats=flexmock(),
+        json=True,
+        list_files=flexmock(),
+    )
+    global_arguments = flexmock(monitoring_verbosity=1, dry_run=False)
+
+    assert list(
+        module.run_create(
+            config_filename='test.yaml',
+            repository={'path': 'repo'},
+            config={},
+            config_paths=['/tmp/test.yaml'],
+            hook_context={},
+            local_borg_version=None,
+            create_arguments=create_arguments,
+            global_arguments=global_arguments,
+            dry_run_label='',
+            local_path=None,
+            remote_path=None,
+        )
+    ) == [parsed_json]
+
+
 def test_create_borgmatic_manifest_creates_manifest_file():
     flexmock(module.os.path).should_receive('join').with_args(
         module.borgmatic.borg.state.DEFAULT_BORGMATIC_SOURCE_DIRECTORY, 'bootstrap', 'manifest.json'
@@ -151,7 +197,7 @@ def test_create_borgmatic_manifest_creates_manifest_file():
     flexmock(module.os.path).should_receive('exists').and_return(False)
     flexmock(module.os).should_receive('makedirs').and_return(True)
 
-    flexmock(module.importlib_metadata).should_receive('version').and_return('1.0.0')
+    flexmock(module.importlib.metadata).should_receive('version').and_return('1.0.0')
     flexmock(sys.modules['builtins']).should_receive('open').with_args(
         '/home/user/.borgmatic/bootstrap/manifest.json', 'w'
     ).and_return(
@@ -172,7 +218,7 @@ def test_create_borgmatic_manifest_creates_manifest_file_with_custom_borgmatic_s
     flexmock(module.os.path).should_receive('exists').and_return(False)
     flexmock(module.os).should_receive('makedirs').and_return(True)
 
-    flexmock(module.importlib_metadata).should_receive('version').and_return('1.0.0')
+    flexmock(module.importlib.metadata).should_receive('version').and_return('1.0.0')
     flexmock(sys.modules['builtins']).should_receive('open').with_args(
         '/borgmatic/bootstrap/manifest.json', 'w'
     ).and_return(

tests/unit/actions/test_info.py

@@ -13,7 +13,7 @@ def test_run_info_does_not_raise():
         flexmock()
     )
     flexmock(module.borgmatic.borg.info).should_receive('display_archives_info')
-    info_arguments = flexmock(repository=flexmock(), archive=flexmock(), json=flexmock())
+    info_arguments = flexmock(repository=flexmock(), archive=flexmock(), json=False)
 
     list(
         module.run_info(
@@ -26,3 +26,32 @@ def test_run_info_does_not_raise():
             remote_path=None,
         )
     )
+
+
+def test_run_info_produces_json():
+    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').and_return(
+        flexmock()
+    )
+    flexmock(module.borgmatic.actions.arguments).should_receive('update_arguments').and_return(
+        flexmock()
+    )
+    flexmock(module.borgmatic.borg.info).should_receive('display_archives_info').and_return(
+        flexmock()
+    )
+    parsed_json = flexmock()
+    flexmock(module.borgmatic.actions.json).should_receive('parse_json').and_return(parsed_json)
+    info_arguments = flexmock(repository=flexmock(), archive=flexmock(), json=True)
+
+    assert list(
+        module.run_info(
+            repository={'path': 'repo'},
+            config={},
+            local_borg_version=None,
+            info_arguments=info_arguments,
+            global_arguments=flexmock(log_json=False),
+            local_path=None,
+            remote_path=None,
+        )
+    ) == [parsed_json]

tests/unit/actions/test_json.py

@@ -0,0 +1,25 @@
+from flexmock import flexmock
+
+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'}})
+
+    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_list.py

@@ -13,7 +13,9 @@ def test_run_list_does_not_raise():
         flexmock()
     )
     flexmock(module.borgmatic.borg.list).should_receive('list_archive')
-    list_arguments = flexmock(repository=flexmock(), archive=flexmock(), json=flexmock())
+    list_arguments = flexmock(
+        repository=flexmock(), archive=flexmock(), json=False, find_paths=None
+    )
 
     list(
         module.run_list(
@@ -26,3 +28,30 @@ def test_run_list_does_not_raise():
             remote_path=None,
         )
     )
+
+
+def test_run_list_produces_json():
+    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').and_return(
+        flexmock()
+    )
+    flexmock(module.borgmatic.actions.arguments).should_receive('update_arguments').and_return(
+        flexmock()
+    )
+    flexmock(module.borgmatic.borg.list).should_receive('list_archive').and_return(flexmock())
+    parsed_json = flexmock()
+    flexmock(module.borgmatic.actions.json).should_receive('parse_json').and_return(parsed_json)
+    list_arguments = flexmock(repository=flexmock(), archive=flexmock(), json=True)
+
+    assert list(
+        module.run_list(
+            repository={'path': 'repo'},
+            config={},
+            local_borg_version=None,
+            list_arguments=list_arguments,
+            global_arguments=flexmock(log_json=False),
+            local_path=None,
+            remote_path=None,
+        )
+    ) == [parsed_json]

tests/unit/actions/test_restore.py

@@ -4,69 +4,71 @@ from flexmock import flexmock
 import borgmatic.actions.restore as module
 
 
-def test_get_configured_database_matches_database_by_name():
-    assert module.get_configured_database(
+def test_get_configured_data_source_matches_data_source_by_name():
+    assert module.get_configured_data_source(
         config={
             'other_databases': [{'name': 'other'}],
             'postgresql_databases': [{'name': 'foo'}, {'name': 'bar'}],
         },
-        archive_database_names={'postgresql_databases': ['other', 'foo', 'bar']},
+        archive_data_source_names={'postgresql_databases': ['other', 'foo', 'bar']},
         hook_name='postgresql_databases',
-        database_name='bar',
+        data_source_name='bar',
     ) == ('postgresql_databases', {'name': 'bar'})
 
 
-def test_get_configured_database_matches_nothing_when_nothing_configured():
-    assert module.get_configured_database(
+def test_get_configured_data_source_matches_nothing_when_nothing_configured():
+    assert module.get_configured_data_source(
         config={},
-        archive_database_names={'postgresql_databases': ['foo']},
+        archive_data_source_names={'postgresql_databases': ['foo']},
         hook_name='postgresql_databases',
-        database_name='quux',
+        data_source_name='quux',
     ) == (None, None)
 
 
-def test_get_configured_database_matches_nothing_when_database_name_not_configured():
-    assert module.get_configured_database(
+def test_get_configured_data_source_matches_nothing_when_data_source_name_not_configured():
+    assert module.get_configured_data_source(
         config={'postgresql_databases': [{'name': 'foo'}, {'name': 'bar'}]},
-        archive_database_names={'postgresql_databases': ['foo']},
+        archive_data_source_names={'postgresql_databases': ['foo']},
         hook_name='postgresql_databases',
-        database_name='quux',
+        data_source_name='quux',
     ) == (None, None)
 
 
-def test_get_configured_database_matches_nothing_when_database_name_not_in_archive():
-    assert module.get_configured_database(
+def test_get_configured_data_source_matches_nothing_when_data_source_name_not_in_archive():
+    assert module.get_configured_data_source(
         config={'postgresql_databases': [{'name': 'foo'}, {'name': 'bar'}]},
-        archive_database_names={'postgresql_databases': ['bar']},
+        archive_data_source_names={'postgresql_databases': ['bar']},
         hook_name='postgresql_databases',
-        database_name='foo',
+        data_source_name='foo',
     ) == (None, None)
 
 
-def test_get_configured_database_matches_database_by_configuration_database_name():
-    assert module.get_configured_database(
+def test_get_configured_data_source_matches_data_source_by_configuration_data_source_name():
+    assert module.get_configured_data_source(
         config={'postgresql_databases': [{'name': 'all'}, {'name': 'bar'}]},
-        archive_database_names={'postgresql_databases': ['foo']},
+        archive_data_source_names={'postgresql_databases': ['foo']},
         hook_name='postgresql_databases',
-        database_name='foo',
-        configuration_database_name='all',
+        data_source_name='foo',
+        configuration_data_source_name='all',
     ) == ('postgresql_databases', {'name': 'all'})
 
 
-def test_get_configured_database_with_unspecified_hook_matches_database_by_name():
-    assert module.get_configured_database(
+def test_get_configured_data_source_with_unspecified_hook_matches_data_source_by_name():
+    assert module.get_configured_data_source(
         config={
             'other_databases': [{'name': 'other'}],
             'postgresql_databases': [{'name': 'foo'}, {'name': 'bar'}],
         },
-        archive_database_names={'postgresql_databases': ['other', 'foo', 'bar']},
+        archive_data_source_names={'postgresql_databases': ['other', 'foo', 'bar']},
         hook_name=module.UNSPECIFIED_HOOK,
-        database_name='bar',
+        data_source_name='bar',
     ) == ('postgresql_databases', {'name': 'bar'})
 
 
-def test_collect_archive_database_names_parses_archive_paths():
-    flexmock(module.borgmatic.hooks.dump).should_receive('make_database_dump_path').and_return('')
+def test_collect_archive_data_source_names_parses_archive_paths():
+    flexmock(module.borgmatic.hooks.dump).should_receive('make_data_source_dump_path').and_return(
+        ''
+    )
     flexmock(module.borgmatic.borg.list).should_receive('capture_archive_listing').and_return(
         [
             '.borgmatic/postgresql_databases/localhost/foo',
@@ -75,7 +77,7 @@ def test_collect_archive_database_names_parses_archive_paths():
         ]
     )
 
-    archive_database_names = module.collect_archive_database_names(
+    archive_data_source_names = module.collect_archive_data_source_names(
         repository={'path': 'repo'},
         archive='archive',
         config={'borgmatic_source_directory': '.borgmatic'},
@@ -85,14 +87,16 @@ def test_collect_archive_database_names_parses_archive_paths():
         remote_path=flexmock(),
     )
 
-    assert archive_database_names == {
+    assert archive_data_source_names == {
         'postgresql_databases': ['foo', 'bar'],
         'mysql_databases': ['quux'],
     }
 
 
-def test_collect_archive_database_names_parses_directory_format_archive_paths():
-    flexmock(module.borgmatic.hooks.dump).should_receive('make_database_dump_path').and_return('')
+def test_collect_archive_data_source_names_parses_directory_format_archive_paths():
+    flexmock(module.borgmatic.hooks.dump).should_receive('make_data_source_dump_path').and_return(
+        ''
+    )
     flexmock(module.borgmatic.borg.list).should_receive('capture_archive_listing').and_return(
         [
             '.borgmatic/postgresql_databases/localhost/foo/table1',
@@ -100,7 +104,7 @@ def test_collect_archive_database_names_parses_directory_format_archive_paths():
         ]
     )
 
-    archive_database_names = module.collect_archive_database_names(
+    archive_data_source_names = module.collect_archive_data_source_names(
         repository={'path': 'repo'},
         archive='archive',
         config={'borgmatic_source_directory': '.borgmatic'},
@@ -110,18 +114,20 @@ def test_collect_archive_database_names_parses_directory_format_archive_paths():
         remote_path=flexmock(),
     )
 
-    assert archive_database_names == {
+    assert archive_data_source_names == {
         'postgresql_databases': ['foo'],
     }
 
 
-def test_collect_archive_database_names_skips_bad_archive_paths():
-    flexmock(module.borgmatic.hooks.dump).should_receive('make_database_dump_path').and_return('')
+def test_collect_archive_data_source_names_skips_bad_archive_paths():
+    flexmock(module.borgmatic.hooks.dump).should_receive('make_data_source_dump_path').and_return(
+        ''
+    )
     flexmock(module.borgmatic.borg.list).should_receive('capture_archive_listing').and_return(
         ['.borgmatic/postgresql_databases/localhost/foo', '.borgmatic/invalid', 'invalid/as/well']
     )
 
-    archive_database_names = module.collect_archive_database_names(
+    archive_data_source_names = module.collect_archive_data_source_names(
         repository={'path': 'repo'},
         archive='archive',
         config={'borgmatic_source_directory': '.borgmatic'},
@@ -131,96 +137,96 @@ def test_collect_archive_database_names_skips_bad_archive_paths():
         remote_path=flexmock(),
     )
 
-    assert archive_database_names == {
+    assert archive_data_source_names == {
         'postgresql_databases': ['foo'],
     }
 
 
-def test_find_databases_to_restore_passes_through_requested_names_found_in_archive():
-    restore_names = module.find_databases_to_restore(
-        requested_database_names=['foo', 'bar'],
-        archive_database_names={'postresql_databases': ['foo', 'bar', 'baz']},
+def test_find_data_sources_to_restore_passes_through_requested_names_found_in_archive():
+    restore_names = module.find_data_sources_to_restore(
+        requested_data_source_names=['foo', 'bar'],
+        archive_data_source_names={'postresql_databases': ['foo', 'bar', 'baz']},
     )
 
     assert restore_names == {module.UNSPECIFIED_HOOK: ['foo', 'bar']}
 
 
-def test_find_databases_to_restore_raises_for_requested_names_missing_from_archive():
+def test_find_data_sources_to_restore_raises_for_requested_names_missing_from_archive():
     with pytest.raises(ValueError):
-        module.find_databases_to_restore(
-            requested_database_names=['foo', 'bar'],
-            archive_database_names={'postresql_databases': ['foo']},
+        module.find_data_sources_to_restore(
+            requested_data_source_names=['foo', 'bar'],
+            archive_data_source_names={'postresql_databases': ['foo']},
         )
 
 
-def test_find_databases_to_restore_without_requested_names_finds_all_archive_databases():
-    archive_database_names = {'postresql_databases': ['foo', 'bar']}
+def test_find_data_sources_to_restore_without_requested_names_finds_all_archive_data_sources():
+    archive_data_source_names = {'postresql_databases': ['foo', 'bar']}
 
-    restore_names = module.find_databases_to_restore(
-        requested_database_names=[],
-        archive_database_names=archive_database_names,
+    restore_names = module.find_data_sources_to_restore(
+        requested_data_source_names=[],
+        archive_data_source_names=archive_data_source_names,
     )
 
-    assert restore_names == archive_database_names
+    assert restore_names == archive_data_source_names
 
 
-def test_find_databases_to_restore_with_all_in_requested_names_finds_all_archive_databases():
-    archive_database_names = {'postresql_databases': ['foo', 'bar']}
+def test_find_data_sources_to_restore_with_all_in_requested_names_finds_all_archive_data_sources():
+    archive_data_source_names = {'postresql_databases': ['foo', 'bar']}
 
-    restore_names = module.find_databases_to_restore(
-        requested_database_names=['all'],
-        archive_database_names=archive_database_names,
+    restore_names = module.find_data_sources_to_restore(
+        requested_data_source_names=['all'],
+        archive_data_source_names=archive_data_source_names,
     )
 
-    assert restore_names == archive_database_names
+    assert restore_names == archive_data_source_names
 
 
-def test_find_databases_to_restore_with_all_in_requested_names_plus_additional_requested_names_omits_duplicates():
-    archive_database_names = {'postresql_databases': ['foo', 'bar']}
+def test_find_data_sources_to_restore_with_all_in_requested_names_plus_additional_requested_names_omits_duplicates():
+    archive_data_source_names = {'postresql_databases': ['foo', 'bar']}
 
-    restore_names = module.find_databases_to_restore(
-        requested_database_names=['all', 'foo', 'bar'],
-        archive_database_names=archive_database_names,
+    restore_names = module.find_data_sources_to_restore(
+        requested_data_source_names=['all', 'foo', 'bar'],
+        archive_data_source_names=archive_data_source_names,
     )
 
-    assert restore_names == archive_database_names
+    assert restore_names == archive_data_source_names
 
 
-def test_find_databases_to_restore_raises_for_all_in_requested_names_and_requested_named_missing_from_archives():
+def test_find_data_sources_to_restore_raises_for_all_in_requested_names_and_requested_named_missing_from_archives():
     with pytest.raises(ValueError):
-        module.find_databases_to_restore(
-            requested_database_names=['all', 'foo', 'bar'],
-            archive_database_names={'postresql_databases': ['foo']},
+        module.find_data_sources_to_restore(
+            requested_data_source_names=['all', 'foo', 'bar'],
+            archive_data_source_names={'postresql_databases': ['foo']},
         )
 
 
-def test_ensure_databases_found_with_all_databases_found_does_not_raise():
-    module.ensure_databases_found(
+def test_ensure_data_sources_found_with_all_data_sources_found_does_not_raise():
+    module.ensure_data_sources_found(
         restore_names={'postgresql_databases': ['foo']},
         remaining_restore_names={'postgresql_databases': ['bar']},
         found_names=['foo', 'bar'],
     )
 
 
-def test_ensure_databases_found_with_no_databases_raises():
+def test_ensure_data_sources_found_with_no_data_sources_raises():
     with pytest.raises(ValueError):
-        module.ensure_databases_found(
+        module.ensure_data_sources_found(
             restore_names={'postgresql_databases': []},
             remaining_restore_names={},
             found_names=[],
         )
 
 
-def test_ensure_databases_found_with_missing_databases_raises():
+def test_ensure_data_sources_found_with_missing_data_sources_raises():
     with pytest.raises(ValueError):
-        module.ensure_databases_found(
+        module.ensure_data_sources_found(
             restore_names={'postgresql_databases': ['foo']},
             remaining_restore_names={'postgresql_databases': ['bar']},
             found_names=['foo'],
         )
 
 
-def test_run_restore_restores_each_database():
+def test_run_restore_restores_each_data_source():
     restore_names = {
         'postgresql_databases': ['foo', 'bar'],
     }
@@ -230,12 +236,12 @@ def test_run_restore_restores_each_database():
     flexmock(module.borgmatic.borg.rlist).should_receive('resolve_archive_name').and_return(
         flexmock()
     )
-    flexmock(module).should_receive('collect_archive_database_names').and_return(flexmock())
-    flexmock(module).should_receive('find_databases_to_restore').and_return(restore_names)
-    flexmock(module).should_receive('get_configured_database').and_return(
+    flexmock(module).should_receive('collect_archive_data_source_names').and_return(flexmock())
+    flexmock(module).should_receive('find_data_sources_to_restore').and_return(restore_names)
+    flexmock(module).should_receive('get_configured_data_source').and_return(
         ('postgresql_databases', {'name': 'foo'})
     ).and_return(('postgresql_databases', {'name': 'bar'}))
-    flexmock(module).should_receive('restore_single_database').with_args(
+    flexmock(module).should_receive('restore_single_data_source').with_args(
         repository=object,
         config=object,
         local_borg_version=object,
@@ -244,10 +250,10 @@ def test_run_restore_restores_each_database():
         remote_path=object,
         archive_name=object,
         hook_name='postgresql_databases',
-        database={'name': 'foo', 'schemas': None},
+        data_source={'name': 'foo', 'schemas': None},
         connection_params=object,
     ).once()
-    flexmock(module).should_receive('restore_single_database').with_args(
+    flexmock(module).should_receive('restore_single_data_source').with_args(
         repository=object,
         config=object,
         local_borg_version=object,
@@ -256,10 +262,10 @@ def test_run_restore_restores_each_database():
         remote_path=object,
         archive_name=object,
         hook_name='postgresql_databases',
-        database={'name': 'bar', 'schemas': None},
+        data_source={'name': 'bar', 'schemas': None},
         connection_params=object,
     ).once()
-    flexmock(module).should_receive('ensure_databases_found')
+    flexmock(module).should_receive('ensure_data_sources_found')
 
     module.run_restore(
         repository={'path': 'repo'},
@@ -268,7 +274,7 @@ def test_run_restore_restores_each_database():
         restore_arguments=flexmock(
             repository='repo',
             archive='archive',
-            databases=flexmock(),
+            data_sources=flexmock(),
             schemas=None,
             hostname=None,
             port=None,
@@ -289,20 +295,20 @@ def test_run_restore_bails_for_non_matching_repository():
     flexmock(module.borgmatic.hooks.dispatch).should_receive(
         'call_hooks_even_if_unconfigured'
     ).never()
-    flexmock(module).should_receive('restore_single_database').never()
+    flexmock(module).should_receive('restore_single_data_source').never()
 
     module.run_restore(
         repository={'path': 'repo'},
         config=flexmock(),
         local_borg_version=flexmock(),
-        restore_arguments=flexmock(repository='repo', archive='archive', databases=flexmock()),
+        restore_arguments=flexmock(repository='repo', archive='archive', data_sources=flexmock()),
         global_arguments=flexmock(dry_run=False),
         local_path=flexmock(),
         remote_path=flexmock(),
     )
 
 
-def test_run_restore_restores_database_configured_with_all_name():
+def test_run_restore_restores_data_source_configured_with_all_name():
     restore_names = {
         'postgresql_databases': ['foo', 'bar'],
     }
@@ -312,28 +318,28 @@ def test_run_restore_restores_database_configured_with_all_name():
     flexmock(module.borgmatic.borg.rlist).should_receive('resolve_archive_name').and_return(
         flexmock()
     )
-    flexmock(module).should_receive('collect_archive_database_names').and_return(flexmock())
-    flexmock(module).should_receive('find_databases_to_restore').and_return(restore_names)
-    flexmock(module).should_receive('get_configured_database').with_args(
+    flexmock(module).should_receive('collect_archive_data_source_names').and_return(flexmock())
+    flexmock(module).should_receive('find_data_sources_to_restore').and_return(restore_names)
+    flexmock(module).should_receive('get_configured_data_source').with_args(
         config=object,
-        archive_database_names=object,
+        archive_data_source_names=object,
         hook_name='postgresql_databases',
-        database_name='foo',
+        data_source_name='foo',
     ).and_return(('postgresql_databases', {'name': 'foo'}))
-    flexmock(module).should_receive('get_configured_database').with_args(
+    flexmock(module).should_receive('get_configured_data_source').with_args(
         config=object,
-        archive_database_names=object,
+        archive_data_source_names=object,
         hook_name='postgresql_databases',
-        database_name='bar',
+        data_source_name='bar',
     ).and_return((None, None))
-    flexmock(module).should_receive('get_configured_database').with_args(
+    flexmock(module).should_receive('get_configured_data_source').with_args(
         config=object,
-        archive_database_names=object,
+        archive_data_source_names=object,
         hook_name='postgresql_databases',
-        database_name='bar',
-        configuration_database_name='all',
+        data_source_name='bar',
+        configuration_data_source_name='all',
     ).and_return(('postgresql_databases', {'name': 'bar'}))
-    flexmock(module).should_receive('restore_single_database').with_args(
+    flexmock(module).should_receive('restore_single_data_source').with_args(
         repository=object,
         config=object,
         local_borg_version=object,
@@ -342,10 +348,10 @@ def test_run_restore_restores_database_configured_with_all_name():
         remote_path=object,
         archive_name=object,
         hook_name='postgresql_databases',
-        database={'name': 'foo', 'schemas': None},
+        data_source={'name': 'foo', 'schemas': None},
         connection_params=object,
     ).once()
-    flexmock(module).should_receive('restore_single_database').with_args(
+    flexmock(module).should_receive('restore_single_data_source').with_args(
         repository=object,
         config=object,
         local_borg_version=object,
@@ -354,10 +360,10 @@ def test_run_restore_restores_database_configured_with_all_name():
         remote_path=object,
         archive_name=object,
         hook_name='postgresql_databases',
-        database={'name': 'bar', 'schemas': None},
+        data_source={'name': 'bar', 'schemas': None},
         connection_params=object,
     ).once()
-    flexmock(module).should_receive('ensure_databases_found')
+    flexmock(module).should_receive('ensure_data_sources_found')
 
     module.run_restore(
         repository={'path': 'repo'},
@@ -366,7 +372,7 @@ def test_run_restore_restores_database_configured_with_all_name():
         restore_arguments=flexmock(
             repository='repo',
             archive='archive',
-            databases=flexmock(),
+            data_sources=flexmock(),
             schemas=None,
             hostname=None,
             port=None,
@@ -380,7 +386,7 @@ def test_run_restore_restores_database_configured_with_all_name():
     )
 
 
-def test_run_restore_skips_missing_database():
+def test_run_restore_skips_missing_data_source():
     restore_names = {
         'postgresql_databases': ['foo', 'bar'],
     }
@@ -390,28 +396,28 @@ def test_run_restore_skips_missing_database():
     flexmock(module.borgmatic.borg.rlist).should_receive('resolve_archive_name').and_return(
         flexmock()
     )
-    flexmock(module).should_receive('collect_archive_database_names').and_return(flexmock())
-    flexmock(module).should_receive('find_databases_to_restore').and_return(restore_names)
-    flexmock(module).should_receive('get_configured_database').with_args(
+    flexmock(module).should_receive('collect_archive_data_source_names').and_return(flexmock())
+    flexmock(module).should_receive('find_data_sources_to_restore').and_return(restore_names)
+    flexmock(module).should_receive('get_configured_data_source').with_args(
         config=object,
-        archive_database_names=object,
+        archive_data_source_names=object,
         hook_name='postgresql_databases',
-        database_name='foo',
+        data_source_name='foo',
     ).and_return(('postgresql_databases', {'name': 'foo'}))
-    flexmock(module).should_receive('get_configured_database').with_args(
+    flexmock(module).should_receive('get_configured_data_source').with_args(
         config=object,
-        archive_database_names=object,
+        archive_data_source_names=object,
         hook_name='postgresql_databases',
-        database_name='bar',
+        data_source_name='bar',
     ).and_return((None, None))
-    flexmock(module).should_receive('get_configured_database').with_args(
+    flexmock(module).should_receive('get_configured_data_source').with_args(
         config=object,
-        archive_database_names=object,
+        archive_data_source_names=object,
         hook_name='postgresql_databases',
-        database_name='bar',
-        configuration_database_name='all',
+        data_source_name='bar',
+        configuration_data_source_name='all',
     ).and_return((None, None))
-    flexmock(module).should_receive('restore_single_database').with_args(
+    flexmock(module).should_receive('restore_single_data_source').with_args(
         repository=object,
         config=object,
         local_borg_version=object,
@@ -420,10 +426,10 @@ def test_run_restore_skips_missing_database():
         remote_path=object,
         archive_name=object,
         hook_name='postgresql_databases',
-        database={'name': 'foo', 'schemas': None},
+        data_source={'name': 'foo', 'schemas': None},
         connection_params=object,
     ).once()
-    flexmock(module).should_receive('restore_single_database').with_args(
+    flexmock(module).should_receive('restore_single_data_source').with_args(
         repository=object,
         config=object,
         local_borg_version=object,
@@ -432,10 +438,10 @@ def test_run_restore_skips_missing_database():
         remote_path=object,
         archive_name=object,
         hook_name='postgresql_databases',
-        database={'name': 'bar', 'schemas': None},
+        data_source={'name': 'bar', 'schemas': None},
         connection_params=object,
     ).never()
-    flexmock(module).should_receive('ensure_databases_found')
+    flexmock(module).should_receive('ensure_data_sources_found')
 
     module.run_restore(
         repository={'path': 'repo'},
@@ -444,7 +450,7 @@ def test_run_restore_skips_missing_database():
         restore_arguments=flexmock(
             repository='repo',
             archive='archive',
-            databases=flexmock(),
+            data_sources=flexmock(),
             schemas=None,
             hostname=None,
             port=None,
@@ -458,7 +464,7 @@ def test_run_restore_skips_missing_database():
     )
 
 
-def test_run_restore_restores_databases_from_different_hooks():
+def test_run_restore_restores_data_sources_from_different_hooks():
     restore_names = {
         'postgresql_databases': ['foo'],
         'mysql_databases': ['bar'],
@@ -469,21 +475,21 @@ def test_run_restore_restores_databases_from_different_hooks():
     flexmock(module.borgmatic.borg.rlist).should_receive('resolve_archive_name').and_return(
         flexmock()
     )
-    flexmock(module).should_receive('collect_archive_database_names').and_return(flexmock())
-    flexmock(module).should_receive('find_databases_to_restore').and_return(restore_names)
-    flexmock(module).should_receive('get_configured_database').with_args(
+    flexmock(module).should_receive('collect_archive_data_source_names').and_return(flexmock())
+    flexmock(module).should_receive('find_data_sources_to_restore').and_return(restore_names)
+    flexmock(module).should_receive('get_configured_data_source').with_args(
         config=object,
-        archive_database_names=object,
+        archive_data_source_names=object,
         hook_name='postgresql_databases',
-        database_name='foo',
+        data_source_name='foo',
     ).and_return(('postgresql_databases', {'name': 'foo'}))
-    flexmock(module).should_receive('get_configured_database').with_args(
+    flexmock(module).should_receive('get_configured_data_source').with_args(
         config=object,
-        archive_database_names=object,
+        archive_data_source_names=object,
         hook_name='mysql_databases',
-        database_name='bar',
+        data_source_name='bar',
     ).and_return(('mysql_databases', {'name': 'bar'}))
-    flexmock(module).should_receive('restore_single_database').with_args(
+    flexmock(module).should_receive('restore_single_data_source').with_args(
         repository=object,
         config=object,
         local_borg_version=object,
@@ -492,10 +498,10 @@ def test_run_restore_restores_databases_from_different_hooks():
         remote_path=object,
         archive_name=object,
         hook_name='postgresql_databases',
-        database={'name': 'foo', 'schemas': None},
+        data_source={'name': 'foo', 'schemas': None},
         connection_params=object,
     ).once()
-    flexmock(module).should_receive('restore_single_database').with_args(
+    flexmock(module).should_receive('restore_single_data_source').with_args(
         repository=object,
         config=object,
         local_borg_version=object,
@@ -504,10 +510,10 @@ def test_run_restore_restores_databases_from_different_hooks():
         remote_path=object,
         archive_name=object,
         hook_name='mysql_databases',
-        database={'name': 'bar', 'schemas': None},
+        data_source={'name': 'bar', 'schemas': None},
         connection_params=object,
     ).once()
-    flexmock(module).should_receive('ensure_databases_found')
+    flexmock(module).should_receive('ensure_data_sources_found')
 
     module.run_restore(
         repository={'path': 'repo'},
@@ -516,7 +522,7 @@ def test_run_restore_restores_databases_from_different_hooks():
         restore_arguments=flexmock(
             repository='repo',
             archive='archive',
-            databases=flexmock(),
+            data_sources=flexmock(),
             schemas=None,
             hostname=None,
             port=None,

tests/unit/actions/test_rinfo.py

@@ -7,7 +7,7 @@ def test_run_rinfo_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.rinfo).should_receive('display_repository_info')
-    rinfo_arguments = flexmock(repository=flexmock(), json=flexmock())
+    rinfo_arguments = flexmock(repository=flexmock(), json=False)
 
     list(
         module.run_rinfo(
@@ -20,3 +20,26 @@ def test_run_rinfo_does_not_raise():
             remote_path=None,
         )
     )
+
+
+def test_run_rinfo_parses_json():
+    flexmock(module.logger).answer = lambda message: None
+    flexmock(module.borgmatic.config.validate).should_receive('repositories_match').and_return(True)
+    flexmock(module.borgmatic.borg.rinfo).should_receive('display_repository_info').and_return(
+        flexmock()
+    )
+    parsed_json = flexmock()
+    flexmock(module.borgmatic.actions.json).should_receive('parse_json').and_return(parsed_json)
+    rinfo_arguments = flexmock(repository=flexmock(), json=True)
+
+    list(
+        module.run_rinfo(
+            repository={'path': 'repo'},
+            config={},
+            local_borg_version=None,
+            rinfo_arguments=rinfo_arguments,
+            global_arguments=flexmock(log_json=False),
+            local_path=None,
+            remote_path=None,
+        )
+    ) == [parsed_json]

tests/unit/actions/test_rlist.py

@@ -7,7 +7,7 @@ def test_run_rlist_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('list_repository')
-    rlist_arguments = flexmock(repository=flexmock(), json=flexmock())
+    rlist_arguments = flexmock(repository=flexmock(), json=False)
 
     list(
         module.run_rlist(
@@ -20,3 +20,24 @@ def test_run_rlist_does_not_raise():
             remote_path=None,
         )
     )
+
+
+def test_run_rlist_produces_json():
+    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('list_repository').and_return(flexmock())
+    parsed_json = flexmock()
+    flexmock(module.borgmatic.actions.json).should_receive('parse_json').and_return(parsed_json)
+    rlist_arguments = flexmock(repository=flexmock(), json=True)
+
+    assert list(
+        module.run_rlist(
+            repository={'path': 'repo'},
+            config={},
+            local_borg_version=None,
+            rlist_arguments=rlist_arguments,
+            global_arguments=flexmock(),
+            local_path=None,
+            remote_path=None,
+        )
+    ) == [parsed_json]

tests/unit/borg/test_borg.py

@@ -16,6 +16,7 @@ def test_run_arbitrary_borg_calls_borg_with_flags():
         ('borg', 'break-lock', '::'),
         output_file=module.borgmatic.execute.DO_NOT_CAPTURE,
         borg_local_path='borg',
+        borg_exit_codes=None,
         shell=True,
         extra_environment={'BORG_REPO': 'repo', 'ARCHIVE': ''},
     )
@@ -37,6 +38,7 @@ def test_run_arbitrary_borg_with_log_info_calls_borg_with_info_flag():
         ('borg', 'break-lock', '--info', '::'),
         output_file=module.borgmatic.execute.DO_NOT_CAPTURE,
         borg_local_path='borg',
+        borg_exit_codes=None,
         shell=True,
         extra_environment={'BORG_REPO': 'repo', 'ARCHIVE': ''},
     )
@@ -59,6 +61,7 @@ def test_run_arbitrary_borg_with_log_debug_calls_borg_with_debug_flag():
         ('borg', 'break-lock', '--debug', '--show-rc', '::'),
         output_file=module.borgmatic.execute.DO_NOT_CAPTURE,
         borg_local_path='borg',
+        borg_exit_codes=None,
         shell=True,
         extra_environment={'BORG_REPO': 'repo', 'ARCHIVE': ''},
     )
@@ -84,6 +87,7 @@ def test_run_arbitrary_borg_with_lock_wait_calls_borg_with_lock_wait_flags():
         ('borg', 'break-lock', '--lock-wait', '5', '::'),
         output_file=module.borgmatic.execute.DO_NOT_CAPTURE,
         borg_local_path='borg',
+        borg_exit_codes=None,
         shell=True,
         extra_environment={'BORG_REPO': 'repo', 'ARCHIVE': ''},
     )
@@ -102,9 +106,10 @@ def test_run_arbitrary_borg_with_archive_calls_borg_with_archive_flag():
     flexmock(module.flags).should_receive('make_flags').and_return(())
     flexmock(module.environment).should_receive('make_environment')
     flexmock(module).should_receive('execute_command').with_args(
-        ('borg', 'break-lock', '::$ARCHIVE'),
+        ('borg', 'break-lock', "'::$ARCHIVE'"),
         output_file=module.borgmatic.execute.DO_NOT_CAPTURE,
         borg_local_path='borg',
+        borg_exit_codes=None,
         shell=True,
         extra_environment={'BORG_REPO': 'repo', 'ARCHIVE': 'archive'},
     )
@@ -127,6 +132,7 @@ def test_run_arbitrary_borg_with_local_path_calls_borg_via_local_path():
         ('borg1', 'break-lock', '::'),
         output_file=module.borgmatic.execute.DO_NOT_CAPTURE,
         borg_local_path='borg1',
+        borg_exit_codes=None,
         shell=True,
         extra_environment={'BORG_REPO': 'repo', 'ARCHIVE': ''},
     )
@@ -140,6 +146,29 @@ def test_run_arbitrary_borg_with_local_path_calls_borg_via_local_path():
     )
 
 
+def test_run_arbitrary_borg_with_exit_codes_calls_borg_using_them():
+    flexmock(module.borgmatic.logger).should_receive('add_custom_log_levels')
+    flexmock(module.logging).ANSWER = module.borgmatic.logger.ANSWER
+    flexmock(module.flags).should_receive('make_flags').and_return(())
+    flexmock(module.environment).should_receive('make_environment')
+    borg_exit_codes = flexmock()
+    flexmock(module).should_receive('execute_command').with_args(
+        ('borg', 'break-lock', '::'),
+        output_file=module.borgmatic.execute.DO_NOT_CAPTURE,
+        borg_local_path='borg',
+        borg_exit_codes=borg_exit_codes,
+        shell=True,
+        extra_environment={'BORG_REPO': 'repo', 'ARCHIVE': ''},
+    )
+
+    module.run_arbitrary_borg(
+        repository_path='repo',
+        config={'borg_exit_codes': borg_exit_codes},
+        local_borg_version='1.2.3',
+        options=['break-lock', '::'],
+    )
+
+
 def test_run_arbitrary_borg_with_remote_path_calls_borg_with_remote_path_flags():
     flexmock(module.borgmatic.logger).should_receive('add_custom_log_levels')
     flexmock(module.logging).ANSWER = module.borgmatic.logger.ANSWER
@@ -151,6 +180,32 @@ def test_run_arbitrary_borg_with_remote_path_calls_borg_with_remote_path_flags()
         ('borg', 'break-lock', '--remote-path', 'borg1', '::'),
         output_file=module.borgmatic.execute.DO_NOT_CAPTURE,
         borg_local_path='borg',
+        borg_exit_codes=None,
+        shell=True,
+        extra_environment={'BORG_REPO': 'repo', 'ARCHIVE': ''},
+    )
+
+    module.run_arbitrary_borg(
+        repository_path='repo',
+        config={},
+        local_borg_version='1.2.3',
+        options=['break-lock', '::'],
+        remote_path='borg1',
+    )
+
+
+def test_run_arbitrary_borg_with_remote_path_injection_attack_gets_escaped():
+    flexmock(module.borgmatic.logger).should_receive('add_custom_log_levels')
+    flexmock(module.logging).ANSWER = module.borgmatic.logger.ANSWER
+    flexmock(module.flags).should_receive('make_flags').and_return(
+        ('--remote-path', 'borg1; naughty-command')
+    ).and_return(())
+    flexmock(module.environment).should_receive('make_environment')
+    flexmock(module).should_receive('execute_command').with_args(
+        ('borg', 'break-lock', '--remote-path', "'borg1; naughty-command'", '::'),
+        output_file=module.borgmatic.execute.DO_NOT_CAPTURE,
+        borg_local_path='borg',
+        borg_exit_codes=None,
         shell=True,
         extra_environment={'BORG_REPO': 'repo', 'ARCHIVE': ''},
     )
@@ -173,6 +228,7 @@ def test_run_arbitrary_borg_passes_borg_specific_flags_to_borg():
         ('borg', 'list', '--progress', '::'),
         output_file=module.borgmatic.execute.DO_NOT_CAPTURE,
         borg_local_path='borg',
+        borg_exit_codes=None,
         shell=True,
         extra_environment={'BORG_REPO': 'repo', 'ARCHIVE': ''},
     )
@@ -194,6 +250,7 @@ def test_run_arbitrary_borg_omits_dash_dash_in_flags_passed_to_borg():
         ('borg', 'break-lock', '::'),
         output_file=module.borgmatic.execute.DO_NOT_CAPTURE,
         borg_local_path='borg',
+        borg_exit_codes=None,
         shell=True,
         extra_environment={'BORG_REPO': 'repo', 'ARCHIVE': ''},
     )
@@ -215,6 +272,7 @@ def test_run_arbitrary_borg_without_borg_specific_flags_does_not_raise():
         ('borg',),
         output_file=module.borgmatic.execute.DO_NOT_CAPTURE,
         borg_local_path='borg',
+        borg_exit_codes=None,
         shell=True,
         extra_environment={'BORG_REPO': 'repo', 'ARCHIVE': ''},
     )
@@ -236,6 +294,7 @@ def test_run_arbitrary_borg_passes_key_sub_command_to_borg_before_injected_flags
         ('borg', 'key', 'export', '--info', '::'),
         output_file=module.borgmatic.execute.DO_NOT_CAPTURE,
         borg_local_path='borg',
+        borg_exit_codes=None,
         shell=True,
         extra_environment={'BORG_REPO': 'repo', 'ARCHIVE': ''},
     )
@@ -258,6 +317,7 @@ def test_run_arbitrary_borg_passes_debug_sub_command_to_borg_before_injected_fla
         ('borg', 'debug', 'dump-manifest', '--info', '::', 'path'),
         output_file=module.borgmatic.execute.DO_NOT_CAPTURE,
         borg_local_path='borg',
+        borg_exit_codes=None,
         shell=True,
         extra_environment={'BORG_REPO': 'repo', 'ARCHIVE': ''},
     )

tests/unit/borg/test_break_lock.py

@@ -7,11 +7,12 @@ from borgmatic.borg import break_lock as module
 from ..test_verbosity import insert_logging_mock
 
 
-def insert_execute_command_mock(command):
+def insert_execute_command_mock(command, borg_exit_codes=None):
     flexmock(module.environment).should_receive('make_environment')
     flexmock(module).should_receive('execute_command').with_args(
         command,
-        borg_local_path='borg',
+        borg_local_path=command[0],
+        borg_exit_codes=borg_exit_codes,
         extra_environment=None,
     ).once()
 
@@ -28,6 +29,32 @@ def test_break_lock_calls_borg_with_required_flags():
     )
 
 
+def test_break_lock_calls_borg_with_local_path():
+    flexmock(module.flags).should_receive('make_repository_flags').and_return(('repo',))
+    insert_execute_command_mock(('borg1', 'break-lock', 'repo'))
+
+    module.break_lock(
+        repository_path='repo',
+        config={},
+        local_borg_version='1.2.3',
+        global_arguments=flexmock(log_json=False),
+        local_path='borg1',
+    )
+
+
+def test_break_lock_calls_borg_using_exit_codes():
+    flexmock(module.flags).should_receive('make_repository_flags').and_return(('repo',))
+    insert_execute_command_mock(('borg1', 'break-lock', 'repo'))
+
+    module.break_lock(
+        repository_path='repo',
+        config={},
+        local_borg_version='1.2.3',
+        global_arguments=flexmock(log_json=False),
+        local_path='borg1',
+    )
+
+
 def test_break_lock_calls_borg_with_remote_path_flags():
     flexmock(module.flags).should_receive('make_repository_flags').and_return(('repo',))
     insert_execute_command_mock(('borg', 'break-lock', '--remote-path', 'borg1', 'repo'))

tests/unit/borg/test_check.py

@@ -8,10 +8,13 @@ from borgmatic.borg import check as module
 from ..test_verbosity import insert_logging_mock
 
 
-def insert_execute_command_mock(command):
+def insert_execute_command_mock(command, borg_exit_codes=None):
     flexmock(module.environment).should_receive('make_environment')
     flexmock(module).should_receive('execute_command').with_args(
-        command, extra_environment=None
+        command,
+        extra_environment=None,
+        borg_local_path=command[0],
+        borg_exit_codes=borg_exit_codes,
     ).once()
 
 
@@ -193,6 +196,19 @@ def test_filter_checks_on_frequency_restains_check_with_unelapsed_frequency_and_
     ) == ('archives',)
 
 
+def test_filter_checks_on_frequency_passes_through_empty_checks():
+    assert (
+        module.filter_checks_on_frequency(
+            config={'checks': [{'name': 'archives', 'frequency': '1 hour'}]},
+            borg_repository_id='repo',
+            checks=(),
+            force=False,
+            archives_check_id='1234',
+        )
+        == ()
+    )
+
+
 def test_make_archive_filter_flags_with_default_checks_and_prefix_returns_default_flags():
     flexmock(module.feature).should_receive('available').and_return(True)
     flexmock(module.flags).should_receive('make_match_archives_flags').and_return(())
@@ -201,6 +217,7 @@ def test_make_archive_filter_flags_with_default_checks_and_prefix_returns_defaul
         '1.2.3',
         {},
         ('repository', 'archives'),
+        check_arguments=flexmock(match_archives=None),
         prefix='foo',
     )
 
@@ -215,6 +232,7 @@ def test_make_archive_filter_flags_with_all_checks_and_prefix_returns_default_fl
         '1.2.3',
         {},
         ('repository', 'archives', 'extract'),
+        check_arguments=flexmock(match_archives=None),
         prefix='foo',
     )
 
@@ -229,6 +247,7 @@ def test_make_archive_filter_flags_with_all_checks_and_prefix_without_borg_featu
         '1.2.3',
         {},
         ('repository', 'archives', 'extract'),
+        check_arguments=flexmock(match_archives=None),
         prefix='foo',
     )
 
@@ -239,7 +258,9 @@ def test_make_archive_filter_flags_with_archives_check_and_last_includes_last_fl
     flexmock(module.feature).should_receive('available').and_return(True)
     flexmock(module.flags).should_receive('make_match_archives_flags').and_return(())
 
-    flags = module.make_archive_filter_flags('1.2.3', {}, ('archives',), check_last=3)
+    flags = module.make_archive_filter_flags(
+        '1.2.3', {}, ('archives',), check_arguments=flexmock(match_archives=None), check_last=3
+    )
 
     assert flags == ('--last', '3')
 
@@ -248,7 +269,9 @@ def test_make_archive_filter_flags_with_data_check_and_last_includes_last_flag()
     flexmock(module.feature).should_receive('available').and_return(True)
     flexmock(module.flags).should_receive('make_match_archives_flags').and_return(())
 
-    flags = module.make_archive_filter_flags('1.2.3', {}, ('data',), check_last=3)
+    flags = module.make_archive_filter_flags(
+        '1.2.3', {}, ('data',), check_arguments=flexmock(match_archives=None), check_last=3
+    )
 
     assert flags == ('--last', '3')
 
@@ -257,7 +280,9 @@ def test_make_archive_filter_flags_with_repository_check_and_last_omits_last_fla
     flexmock(module.feature).should_receive('available').and_return(True)
     flexmock(module.flags).should_receive('make_match_archives_flags').and_return(())
 
-    flags = module.make_archive_filter_flags('1.2.3', {}, ('repository',), check_last=3)
+    flags = module.make_archive_filter_flags(
+        '1.2.3', {}, ('repository',), check_arguments=flexmock(match_archives=None), check_last=3
+    )
 
     assert flags == ()
 
@@ -266,7 +291,13 @@ def test_make_archive_filter_flags_with_default_checks_and_last_includes_last_fl
     flexmock(module.feature).should_receive('available').and_return(True)
     flexmock(module.flags).should_receive('make_match_archives_flags').and_return(())
 
-    flags = module.make_archive_filter_flags('1.2.3', {}, ('repository', 'archives'), check_last=3)
+    flags = module.make_archive_filter_flags(
+        '1.2.3',
+        {},
+        ('repository', 'archives'),
+        check_arguments=flexmock(match_archives=None),
+        check_last=3,
+    )
 
     assert flags == ('--last', '3')
 
@@ -275,7 +306,9 @@ def test_make_archive_filter_flags_with_archives_check_and_prefix_includes_match
     flexmock(module.feature).should_receive('available').and_return(True)
     flexmock(module.flags).should_receive('make_match_archives_flags').and_return(())
 
-    flags = module.make_archive_filter_flags('1.2.3', {}, ('archives',), prefix='foo-')
+    flags = module.make_archive_filter_flags(
+        '1.2.3', {}, ('archives',), check_arguments=flexmock(match_archives=None), prefix='foo-'
+    )
 
     assert flags == ('--match-archives', 'sh:foo-*')
 
@@ -284,11 +317,30 @@ def test_make_archive_filter_flags_with_data_check_and_prefix_includes_match_arc
     flexmock(module.feature).should_receive('available').and_return(True)
     flexmock(module.flags).should_receive('make_match_archives_flags').and_return(())
 
-    flags = module.make_archive_filter_flags('1.2.3', {}, ('data',), prefix='foo-')
+    flags = module.make_archive_filter_flags(
+        '1.2.3', {}, ('data',), check_arguments=flexmock(match_archives=None), prefix='foo-'
+    )
 
     assert flags == ('--match-archives', 'sh:foo-*')
 
 
+def test_make_archive_filter_flags_prefers_check_arguments_match_archives_to_config_match_archives():
+    flexmock(module.feature).should_receive('available').and_return(True)
+    flexmock(module.flags).should_receive('make_match_archives_flags').with_args(
+        'baz-*', None, '1.2.3'
+    ).and_return(('--match-archives', 'sh:baz-*'))
+
+    flags = module.make_archive_filter_flags(
+        '1.2.3',
+        {'match_archives': 'bar-{now}'},  # noqa: FS003
+        ('archives',),
+        check_arguments=flexmock(match_archives='baz-*'),
+        prefix='',
+    )
+
+    assert flags == ('--match-archives', 'sh:baz-*')
+
+
 def test_make_archive_filter_flags_with_archives_check_and_empty_prefix_uses_archive_name_format_instead():
     flexmock(module.feature).should_receive('available').and_return(True)
     flexmock(module.flags).should_receive('make_match_archives_flags').with_args(
@@ -296,7 +348,11 @@ def test_make_archive_filter_flags_with_archives_check_and_empty_prefix_uses_arc
     ).and_return(('--match-archives', 'sh:bar-*'))
 
     flags = module.make_archive_filter_flags(
-        '1.2.3', {'archive_name_format': 'bar-{now}'}, ('archives',), prefix=''  # noqa: FS003
+        '1.2.3',
+        {'archive_name_format': 'bar-{now}'},  # noqa: FS003
+        ('archives',),
+        check_arguments=flexmock(match_archives=None),
+        prefix='',
     )
 
     assert flags == ('--match-archives', 'sh:bar-*')
@@ -306,7 +362,9 @@ def test_make_archive_filter_flags_with_archives_check_and_none_prefix_omits_mat
     flexmock(module.feature).should_receive('available').and_return(True)
     flexmock(module.flags).should_receive('make_match_archives_flags').and_return(())
 
-    flags = module.make_archive_filter_flags('1.2.3', {}, ('archives',), prefix=None)
+    flags = module.make_archive_filter_flags(
+        '1.2.3', {}, ('archives',), check_arguments=flexmock(match_archives=None), prefix=None
+    )
 
     assert flags == ()
 
@@ -315,7 +373,9 @@ def test_make_archive_filter_flags_with_repository_check_and_prefix_omits_match_
     flexmock(module.feature).should_receive('available').and_return(True)
     flexmock(module.flags).should_receive('make_match_archives_flags').and_return(())
 
-    flags = module.make_archive_filter_flags('1.2.3', {}, ('repository',), prefix='foo-')
+    flags = module.make_archive_filter_flags(
+        '1.2.3', {}, ('repository',), check_arguments=flexmock(match_archives=None), prefix='foo-'
+    )
 
     assert flags == ()
 
@@ -324,7 +384,13 @@ def test_make_archive_filter_flags_with_default_checks_and_prefix_includes_match
     flexmock(module.feature).should_receive('available').and_return(True)
     flexmock(module.flags).should_receive('make_match_archives_flags').and_return(())
 
-    flags = module.make_archive_filter_flags('1.2.3', {}, ('repository', 'archives'), prefix='foo-')
+    flags = module.make_archive_filter_flags(
+        '1.2.3',
+        {},
+        ('repository', 'archives'),
+        check_arguments=flexmock(match_archives=None),
+        prefix='foo-',
+    )
 
     assert flags == ('--match-archives', 'sh:foo-*')
 
@@ -607,7 +673,7 @@ def test_upgrade_check_times_renames_stale_temporary_check_path():
     module.upgrade_check_times(flexmock(), flexmock())
 
 
-def test_check_archives_with_progress_calls_borg_with_progress_parameter():
+def test_check_archives_with_progress_passes_through_to_borg():
     checks = ('repository',)
     config = {'check_last': None}
     flexmock(module.rinfo).should_receive('display_repository_info').and_return(
@@ -626,6 +692,8 @@ def test_check_archives_with_progress_calls_borg_with_progress_parameter():
         ('borg', 'check', '--progress', 'repo'),
         output_file=module.DO_NOT_CAPTURE,
         extra_environment=None,
+        borg_local_path='borg',
+        borg_exit_codes=None,
     ).once()
     flexmock(module).should_receive('make_check_time_path')
     flexmock(module).should_receive('write_check_time')
@@ -634,12 +702,14 @@ def test_check_archives_with_progress_calls_borg_with_progress_parameter():
         repository_path='repo',
         config=config,
         local_borg_version='1.2.3',
+        check_arguments=flexmock(
+            progress=True, repair=None, only_checks=None, force=None, match_archives=None
+        ),
         global_arguments=flexmock(log_json=False),
-        progress=True,
     )
 
 
-def test_check_archives_with_repair_calls_borg_with_repair_parameter():
+def test_check_archives_with_repair_passes_through_to_borg():
     checks = ('repository',)
     config = {'check_last': None}
     flexmock(module.rinfo).should_receive('display_repository_info').and_return(
@@ -658,6 +728,8 @@ def test_check_archives_with_repair_calls_borg_with_repair_parameter():
         ('borg', 'check', '--repair', 'repo'),
         output_file=module.DO_NOT_CAPTURE,
         extra_environment=None,
+        borg_local_path='borg',
+        borg_exit_codes=None,
     ).once()
     flexmock(module).should_receive('make_check_time_path')
     flexmock(module).should_receive('write_check_time')
@@ -666,8 +738,10 @@ def test_check_archives_with_repair_calls_borg_with_repair_parameter():
         repository_path='repo',
         config=config,
         local_borg_version='1.2.3',
+        check_arguments=flexmock(
+            progress=None, repair=True, only_checks=None, force=None, match_archives=None
+        ),
         global_arguments=flexmock(log_json=False),
-        repair=True,
     )
 
 
@@ -701,6 +775,9 @@ def test_check_archives_calls_borg_with_parameters(checks):
         repository_path='repo',
         config=config,
         local_borg_version='1.2.3',
+        check_arguments=flexmock(
+            progress=None, repair=None, only_checks=None, force=None, match_archives=None
+        ),
         global_arguments=flexmock(log_json=False),
     )
 
@@ -723,6 +800,9 @@ def test_check_archives_with_json_error_raises():
             repository_path='repo',
             config=config,
             local_borg_version='1.2.3',
+            check_arguments=flexmock(
+                progress=None, repair=None, only_checks=None, force=None, match_archives=None
+            ),
             global_arguments=flexmock(log_json=False),
         )
 
@@ -743,6 +823,9 @@ def test_check_archives_with_missing_json_keys_raises():
             repository_path='repo',
             config=config,
             local_borg_version='1.2.3',
+            check_arguments=flexmock(
+                progress=None, repair=None, only_checks=None, force=None, match_archives=None
+            ),
             global_arguments=flexmock(log_json=False),
         )
 
@@ -769,11 +852,14 @@ def test_check_archives_with_extract_check_calls_extract_only():
         repository_path='repo',
         config=config,
         local_borg_version='1.2.3',
+        check_arguments=flexmock(
+            progress=None, repair=None, only_checks=None, force=None, match_archives=None
+        ),
         global_arguments=flexmock(log_json=False),
     )
 
 
-def test_check_archives_with_log_info_calls_borg_with_info_parameter():
+def test_check_archives_with_log_info_passes_through_to_borg():
     checks = ('repository',)
     config = {'check_last': None}
     flexmock(module.rinfo).should_receive('display_repository_info').and_return(
@@ -795,11 +881,14 @@ def test_check_archives_with_log_info_calls_borg_with_info_parameter():
         repository_path='repo',
         config=config,
         local_borg_version='1.2.3',
+        check_arguments=flexmock(
+            progress=None, repair=None, only_checks=None, force=None, match_archives=None
+        ),
         global_arguments=flexmock(log_json=False),
     )
 
 
-def test_check_archives_with_log_debug_calls_borg_with_debug_parameter():
+def test_check_archives_with_log_debug_passes_through_to_borg():
     checks = ('repository',)
     config = {'check_last': None}
     flexmock(module.rinfo).should_receive('display_repository_info').and_return(
@@ -821,6 +910,9 @@ def test_check_archives_with_log_debug_calls_borg_with_debug_parameter():
         repository_path='repo',
         config=config,
         local_borg_version='1.2.3',
+        check_arguments=flexmock(
+            progress=None, repair=None, only_checks=None, force=None, match_archives=None
+        ),
         global_arguments=flexmock(log_json=False),
     )
 
@@ -841,6 +933,9 @@ def test_check_archives_without_any_checks_bails():
         repository_path='repo',
         config=config,
         local_borg_version='1.2.3',
+        check_arguments=flexmock(
+            progress=None, repair=None, only_checks=None, force=None, match_archives=None
+        ),
         global_arguments=flexmock(log_json=False),
     )
 
@@ -867,12 +962,45 @@ def test_check_archives_with_local_path_calls_borg_via_local_path():
         repository_path='repo',
         config=config,
         local_borg_version='1.2.3',
+        check_arguments=flexmock(
+            progress=None, repair=None, only_checks=None, force=None, match_archives=None
+        ),
         global_arguments=flexmock(log_json=False),
         local_path='borg1',
     )
 
 
-def test_check_archives_with_remote_path_calls_borg_with_remote_path_parameters():
+def test_check_archives_with_exit_codes_calls_borg_using_them():
+    checks = ('repository',)
+    check_last = flexmock()
+    borg_exit_codes = flexmock()
+    config = {'check_last': check_last, 'borg_exit_codes': borg_exit_codes}
+    flexmock(module.rinfo).should_receive('display_repository_info').and_return(
+        '{"repository": {"id": "repo"}}'
+    )
+    flexmock(module).should_receive('upgrade_check_times')
+    flexmock(module).should_receive('parse_checks')
+    flexmock(module).should_receive('make_archive_filter_flags').and_return(())
+    flexmock(module).should_receive('make_archives_check_id').and_return(None)
+    flexmock(module).should_receive('filter_checks_on_frequency').and_return(checks)
+    flexmock(module).should_receive('make_check_flags').with_args(checks, ()).and_return(())
+    flexmock(module.flags).should_receive('make_repository_flags').and_return(('repo',))
+    insert_execute_command_mock(('borg', 'check', 'repo'), borg_exit_codes=borg_exit_codes)
+    flexmock(module).should_receive('make_check_time_path')
+    flexmock(module).should_receive('write_check_time')
+
+    module.check_archives(
+        repository_path='repo',
+        config=config,
+        local_borg_version='1.2.3',
+        check_arguments=flexmock(
+            progress=None, repair=None, only_checks=None, force=None, match_archives=None
+        ),
+        global_arguments=flexmock(log_json=False),
+    )
+
+
+def test_check_archives_with_remote_path_passes_through_to_borg():
     checks = ('repository',)
     check_last = flexmock()
     config = {'check_last': check_last}
@@ -894,12 +1022,15 @@ def test_check_archives_with_remote_path_calls_borg_with_remote_path_parameters(
         repository_path='repo',
         config=config,
         local_borg_version='1.2.3',
+        check_arguments=flexmock(
+            progress=None, repair=None, only_checks=None, force=None, match_archives=None
+        ),
         global_arguments=flexmock(log_json=False),
         remote_path='borg1',
     )
 
 
-def test_check_archives_with_log_json_calls_borg_with_log_json_parameters():
+def test_check_archives_with_log_json_passes_through_to_borg():
     checks = ('repository',)
     check_last = flexmock()
     config = {'check_last': check_last}
@@ -921,11 +1052,14 @@ def test_check_archives_with_log_json_calls_borg_with_log_json_parameters():
         repository_path='repo',
         config=config,
         local_borg_version='1.2.3',
+        check_arguments=flexmock(
+            progress=None, repair=None, only_checks=None, force=None, match_archives=None
+        ),
         global_arguments=flexmock(log_json=True),
     )
 
 
-def test_check_archives_with_lock_wait_calls_borg_with_lock_wait_parameters():
+def test_check_archives_with_lock_wait_passes_through_to_borg():
     checks = ('repository',)
     check_last = flexmock()
     config = {'lock_wait': 5, 'check_last': check_last}
@@ -947,6 +1081,9 @@ def test_check_archives_with_lock_wait_calls_borg_with_lock_wait_parameters():
         repository_path='repo',
         config=config,
         local_borg_version='1.2.3',
+        check_arguments=flexmock(
+            progress=None, repair=None, only_checks=None, force=None, match_archives=None
+        ),
         global_arguments=flexmock(log_json=False),
     )
 
@@ -974,11 +1111,14 @@ def test_check_archives_with_retention_prefix():
         repository_path='repo',
         config=config,
         local_borg_version='1.2.3',
+        check_arguments=flexmock(
+            progress=None, repair=None, only_checks=None, force=None, match_archives=None
+        ),
         global_arguments=flexmock(log_json=False),
     )
 
 
-def test_check_archives_with_extra_borg_options_calls_borg_with_extra_options():
+def test_check_archives_with_extra_borg_options_passes_through_to_borg():
     checks = ('repository',)
     config = {'check_last': None, 'extra_borg_options': {'check': '--extra --options'}}
     flexmock(module.rinfo).should_receive('display_repository_info').and_return(
@@ -999,5 +1139,44 @@ def test_check_archives_with_extra_borg_options_calls_borg_with_extra_options():
         repository_path='repo',
         config=config,
         local_borg_version='1.2.3',
+        check_arguments=flexmock(
+            progress=None, repair=None, only_checks=None, force=None, match_archives=None
+        ),
+        global_arguments=flexmock(log_json=False),
+    )
+
+
+def test_check_archives_with_match_archives_passes_through_to_borg():
+    checks = ('archives',)
+    config = {'check_last': None}
+    flexmock(module.rinfo).should_receive('display_repository_info').and_return(
+        '{"repository": {"id": "repo"}}'
+    )
+    flexmock(module).should_receive('upgrade_check_times')
+    flexmock(module).should_receive('parse_checks')
+    flexmock(module).should_receive('make_archive_filter_flags').and_return(
+        ('--match-archives', 'foo-*')
+    )
+    flexmock(module).should_receive('make_archives_check_id').and_return(None)
+    flexmock(module).should_receive('filter_checks_on_frequency').and_return(checks)
+    flexmock(module).should_receive('make_check_flags').and_return(('--match-archives', 'foo-*'))
+    flexmock(module.flags).should_receive('make_repository_flags').and_return(('repo',))
+    flexmock(module.environment).should_receive('make_environment')
+    flexmock(module).should_receive('execute_command').with_args(
+        ('borg', 'check', '--match-archives', 'foo-*', 'repo'),
+        extra_environment=None,
+        borg_local_path='borg',
+        borg_exit_codes=None,
+    ).once()
+    flexmock(module).should_receive('make_check_time_path')
+    flexmock(module).should_receive('write_check_time')
+
+    module.check_archives(
+        repository_path='repo',
+        config=config,
+        local_borg_version='1.2.3',
+        check_arguments=flexmock(
+            progress=None, repair=None, only_checks=None, force=None, match_archives='foo-*'
+        ),
         global_arguments=flexmock(log_json=False),
     )

tests/unit/borg/test_compact.py

@@ -7,12 +7,13 @@ from borgmatic.borg import compact as module
 from ..test_verbosity import insert_logging_mock
 
 
-def insert_execute_command_mock(compact_command, output_log_level):
+def insert_execute_command_mock(compact_command, output_log_level, borg_exit_codes=None):
     flexmock(module.environment).should_receive('make_environment')
     flexmock(module).should_receive('execute_command').with_args(
         compact_command,
         output_log_level=output_log_level,
         borg_local_path=compact_command[0],
+        borg_exit_codes=borg_exit_codes,
         extra_environment=None,
     ).once()
 
@@ -87,6 +88,22 @@ def test_compact_segments_with_local_path_calls_borg_via_local_path():
     )
 
 
+def test_compact_segments_with_exit_codes_calls_borg_using_them():
+    flexmock(module.flags).should_receive('make_repository_flags').and_return(('repo',))
+    borg_exit_codes = flexmock()
+    insert_execute_command_mock(
+        COMPACT_COMMAND + ('repo',), logging.INFO, borg_exit_codes=borg_exit_codes
+    )
+
+    module.compact_segments(
+        dry_run=False,
+        repository_path='repo',
+        config={'borg_exit_codes': borg_exit_codes},
+        local_borg_version='1.2.3',
+        global_arguments=flexmock(log_json=False),
+    )
+
+
 def test_compact_segments_with_remote_path_calls_borg_with_remote_path_parameters():
     flexmock(module.flags).should_receive('make_repository_flags').and_return(('repo',))
     insert_execute_command_mock(COMPACT_COMMAND + ('--remote-path', 'borg1', 'repo'), logging.INFO)