Bump version for release.

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

NEWS

@@ -1,3 +1,61 @@
+1.6.1
+ * #294: Add Healthchecks monitoring hook "ping_body_limit" option to configure how many bytes of
+   logs to send to the Healthchecks server.
+ * #402: Remove the error when "archive_name_format" is specified but a retention prefix isn't. 
+ * #420: Warn when an unsupported variable is used in a hook command.
+ * #439: Change connection failures for monitoring hooks (Healthchecks, Cronitor, PagerDuty, and
+   Cronhub) to be warnings instead of errors. This way, the monitoring system failing does not block
+   backups.
+ * #460: Add Healthchecks monitoring hook "send_logs" option to enable/disable sending borgmatic
+   logs to the Healthchecks server.
+ * #525: Add Healthchecks monitoring hook "states" option to only enable pinging for particular
+   monitoring states (start, finish, fail).
+ * #528: Improve the error message when a configuration override contains an invalid value.
+ * #531: BREAKING: When deep merging common configuration, merge colliding list values by appending
+   them. Previously, one list replaced the other.
+ * #532: When a configuration include is a relative path, load it from either the current working
+   directory or from the directory containing the file doing the including. Previously, only the
+   working directory was used.
+ * Add a randomized delay to the sample systemd timer to spread out the load on a server.
+ * Change the configuration format for borgmatic monitoring hooks (Healthchecks, Cronitor,
+   PagerDuty, and Cronhub) to specify the ping URL / integration key as a named option. The intent
+   is to support additional options (some in this release). This change is backwards-compatible.
+ * Add emojis to documentation table of contents to make it easier to find particular how-to and
+   reference guides at a glance.
+
+1.6.0
+ * #381: BREAKING: Greatly simplify configuration file reuse by deep merging when including common
+   configuration. See the documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/make-per-application-backups/#include-merging
+ * #473: BREAKING: Instead of executing "before" command hooks before all borgmatic actions run (and
+   "after" hooks after), execute these hooks right before/after the corresponding action. E.g.,
+   "before_check" now runs immediately before the "check" action. This better supports running
+   timing-sensitive tasks like pausing containers. Side effect: before/after command hooks now run
+   once for each configured repository instead of once per configuration file. Additionally, the
+   "repositories" interpolated variable has been changed to "repository", containing the path to the
+   current repository for the hook. See the documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/
+ * #513: Add mention of sudo's "secure_path" option to borgmatic installation documentation.
+ * #515: Fix "borgmatic borg key ..." to pass parameters to Borg in the correct order.
+ * #516: Fix handling of TERM signal to exit borgmatic, not just forward the signal to Borg.
+ * #517: Fix borgmatic exit code (so it's zero) when initial Borg calls fail but later retries
+   succeed.
+ * Change Healthchecks logs truncation size from 10k bytes to 100k bytes, corresponding to that
+   same change on Healthchecks.io.
+
+1.5.24
+ * #431: Add "working_directory" option to support source directories with relative paths.
+ * #444: When loading a configuration file that is unreadable due to file permissions, warn instead
+   of erroring. This supports running borgmatic as a non-root user with configuration in ~/.config
+   even if there is an unreadable global configuration file in /etc.
+ * #469: Add "repositories" context to "before_*" and "after_*" command action hooks. See the
+   documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/
+ * #486: Fix handling of "patterns_from" and "exclude_from" options to error instead of warning when
+   referencing unreadable files and "create" action is run.
+ * #507: Fix Borg usage error in the "compact" action when running "borgmatic --dry-run". Now, skip
+   "compact" entirely during a dry run.
+
 1.5.23
  * #394: Compact repository segments and free space with new "borgmatic compact" action. Borg 1.2+
    only. Also run "compact" by default when no actions are specified, as "prune" in Borg 1.2 no

borgmatic/borg/borg.py

@@ -21,17 +21,20 @@ def run_arbitrary_borg(
 
     try:
         options = options[1:] if options[0] == '--' else options
-        borg_command = options[0]
-        command_options = tuple(options[1:])
+
+        # Borg's "key" command has a sub-command ("export", etc.) that must follow it.
+        command_options_start_index = 2 if options[0] == 'key' else 1
+        borg_command = tuple(options[:command_options_start_index])
+        command_options = tuple(options[command_options_start_index:])
     except IndexError:
-        borg_command = None
+        borg_command = ()
         command_options = ()
 
     repository_archive = '::'.join((repository, archive)) if repository and archive else repository
 
     full_command = (
         (local_path,)
-        + ((borg_command,) if borg_command else ())
+        + borg_command
         + ((repository_archive,) if borg_command and repository_archive else ())
         + command_options
         + (('--info',) if logger.getEffectiveLevel() == logging.INFO else ())

borgmatic/borg/compact.py

@@ -33,9 +33,9 @@ def compact_segments(
         + (('--threshold', str(threshold)) if threshold else ())
         + (('--info',) if logger.getEffectiveLevel() == logging.INFO else ())
         + (('--debug', '--show-rc') if logger.isEnabledFor(logging.DEBUG) else ())
-        + (('--dry-run',) if dry_run else ())
         + (tuple(extra_borg_options.split(' ')) if extra_borg_options else ())
         + (repository,)
     )
 
-    execute_command(full_command, output_log_level=logging.INFO, borg_local_path=local_path)
+    if not dry_run:
+        execute_command(full_command, output_log_level=logging.INFO, borg_local_path=local_path)

borgmatic/borg/create.py

@@ -11,7 +11,7 @@ from borgmatic.execute import DO_NOT_CAPTURE, execute_command, execute_command_w
 logger = logging.getLogger(__name__)
 
 
-def _expand_directory(directory):
+def expand_directory(directory):
     '''
     Given a directory path, expand any tilde (representing a user's home directory) and any globs
     therein. Return a list of one or more resulting paths.
@@ -21,7 +21,7 @@ def _expand_directory(directory):
     return glob.glob(expanded_directory) or [expanded_directory]
 
 
-def _expand_directories(directories):
+def expand_directories(directories):
     '''
     Given a sequence of directory paths, expand tildes and globs in each one. Return all the
     resulting directories as a single flattened tuple.
@@ -30,11 +30,11 @@ def _expand_directories(directories):
         return ()
 
     return tuple(
-        itertools.chain.from_iterable(_expand_directory(directory) for directory in directories)
+        itertools.chain.from_iterable(expand_directory(directory) for directory in directories)
     )
 
 
-def _expand_home_directories(directories):
+def expand_home_directories(directories):
     '''
     Given a sequence of directory paths, expand tildes in each one. Do not perform any globbing.
     Return the results as a tuple.
@@ -98,7 +98,7 @@ def deduplicate_directories(directory_devices):
     return tuple(sorted(deduplicated))
 
 
-def _write_pattern_file(patterns=None):
+def write_pattern_file(patterns=None):
     '''
     Given a sequence of patterns, write them to a named temporary file and return it. Return None
     if no patterns are provided.
@@ -113,7 +113,19 @@ def _write_pattern_file(patterns=None):
     return pattern_file
 
 
-def _make_pattern_flags(location_config, pattern_filename=None):
+def ensure_files_readable(*filename_lists):
+    '''
+    Given a sequence of filename sequences, ensure that each filename is openable. This prevents
+    unreadable files from being passed to Borg, which in certain situations only warns instead of
+    erroring.
+    '''
+    for file_object in itertools.chain.from_iterable(
+        filename_list for filename_list in filename_lists if filename_list
+    ):
+        open(file_object).close()
+
+
+def make_pattern_flags(location_config, pattern_filename=None):
     '''
     Given a location config dict with a potential patterns_from option, and a filename containing
     any additional patterns, return the corresponding Borg flags for those files as a tuple.
@@ -129,7 +141,7 @@ def _make_pattern_flags(location_config, pattern_filename=None):
     )
 
 
-def _make_exclude_flags(location_config, exclude_filename=None):
+def make_exclude_flags(location_config, exclude_filename=None):
     '''
     Given a location config dict with various exclude options, and a filename containing any exclude
     patterns, return the corresponding Borg flags as a tuple.
@@ -206,16 +218,20 @@ def create_archive(
     '''
     sources = deduplicate_directories(
         map_directories_to_devices(
-            _expand_directories(
+            expand_directories(
                 location_config['source_directories']
                 + borgmatic_source_directories(location_config.get('borgmatic_source_directory'))
             )
         )
     )
 
-    pattern_file = _write_pattern_file(location_config.get('patterns'))
-    exclude_file = _write_pattern_file(
-        _expand_home_directories(location_config.get('exclude_patterns'))
+    try:
+        working_directory = os.path.expanduser(location_config.get('working_directory'))
+    except TypeError:
+        working_directory = None
+    pattern_file = write_pattern_file(location_config.get('patterns'))
+    exclude_file = write_pattern_file(
+        expand_home_directories(location_config.get('exclude_patterns'))
     )
     checkpoint_interval = storage_config.get('checkpoint_interval', None)
     chunker_params = storage_config.get('chunker_params', None)
@@ -251,11 +267,13 @@ def create_archive(
             ('--remote-ratelimit', str(remote_rate_limit)) if remote_rate_limit else ()
         )
 
+    ensure_files_readable(location_config.get('patterns_from'), location_config.get('exclude_from'))
+
     full_command = (
         tuple(local_path.split(' '))
         + ('create',)
-        + _make_pattern_flags(location_config, pattern_file.name if pattern_file else None)
-        + _make_exclude_flags(location_config, exclude_file.name if exclude_file else None)
+        + make_pattern_flags(location_config, pattern_file.name if pattern_file else None)
+        + make_exclude_flags(location_config, exclude_file.name if exclude_file else None)
         + (('--checkpoint-interval', str(checkpoint_interval)) if checkpoint_interval else ())
         + (('--chunker-params', chunker_params) if chunker_params else ())
         + (('--compression', compression) if compression else ())
@@ -309,6 +327,13 @@ def create_archive(
             output_log_level,
             output_file,
             borg_local_path=local_path,
+            working_directory=working_directory,
         )
 
-    return execute_command(full_command, output_log_level, output_file, borg_local_path=local_path)
+    return execute_command(
+        full_command,
+        output_log_level,
+        output_file,
+        borg_local_path=local_path,
+        working_directory=working_directory,
+    )

borgmatic/commands/borgmatic.py

@@ -68,7 +68,7 @@ def run_configuration(config_filename, config, arguments):
     try:
         local_borg_version = borg_version.local_borg_version(local_path)
     except (OSError, CalledProcessError, ValueError) as error:
-        yield from make_error_log_records(
+        yield from log_error_records(
             '{}: Error getting local Borg version'.format(config_filename), error
         )
         return
@@ -83,46 +83,6 @@ def run_configuration(config_filename, config, arguments):
                 monitoring_log_level,
                 global_arguments.dry_run,
             )
-        if 'prune' in arguments:
-            command.execute_hook(
-                hooks.get('before_prune'),
-                hooks.get('umask'),
-                config_filename,
-                'pre-prune',
-                global_arguments.dry_run,
-            )
-        if 'compact' in arguments:
-            command.execute_hook(
-                hooks.get('before_compact'),
-                hooks.get('umask'),
-                config_filename,
-                'pre-compact',
-                global_arguments.dry_run,
-            )
-        if 'create' in arguments:
-            command.execute_hook(
-                hooks.get('before_backup'),
-                hooks.get('umask'),
-                config_filename,
-                'pre-backup',
-                global_arguments.dry_run,
-            )
-        if 'check' in arguments:
-            command.execute_hook(
-                hooks.get('before_check'),
-                hooks.get('umask'),
-                config_filename,
-                'pre-check',
-                global_arguments.dry_run,
-            )
-        if 'extract' in arguments:
-            command.execute_hook(
-                hooks.get('before_extract'),
-                hooks.get('umask'),
-                config_filename,
-                'pre-extract',
-                global_arguments.dry_run,
-            )
         if using_primary_action:
             dispatch.call_hooks(
                 'ping_monitor',
@@ -138,9 +98,7 @@ def run_configuration(config_filename, config, arguments):
             return
 
         encountered_error = error
-        yield from make_error_log_records(
-            '{}: Error running pre hook'.format(config_filename), error
-        )
+        yield from log_error_records('{}: Error pinging monitor'.format(config_filename), error)
 
     if not encountered_error:
         repo_queue = Queue()
@@ -156,6 +114,7 @@ def run_configuration(config_filename, config, arguments):
             try:
                 yield from run_actions(
                     arguments=arguments,
+                    config_filename=config_filename,
                     location=location,
                     storage=storage,
                     retention=retention,
@@ -167,68 +126,32 @@ def run_configuration(config_filename, config, arguments):
                     repository_path=repository_path,
                 )
             except (OSError, CalledProcessError, ValueError) as error:
-                yield from make_error_log_records(
-                    '{}: Error running actions for repository'.format(repository_path), error
-                )
                 if retry_num < retries:
                     repo_queue.put((repository_path, retry_num + 1),)
+                    tuple(  # Consume the generator so as to trigger logging.
+                        log_error_records(
+                            '{}: Error running actions for repository'.format(repository_path),
+                            error,
+                            levelno=logging.WARNING,
+                            log_command_error_output=True,
+                        )
+                    )
                     logger.warning(
                         f'{config_filename}: Retrying... attempt {retry_num + 1}/{retries}'
                     )
                     continue
+
+                if command.considered_soft_failure(config_filename, error):
+                    return
+
+                yield from log_error_records(
+                    '{}: Error running actions for repository'.format(repository_path), error
+                )
                 encountered_error = error
                 error_repository = repository_path
 
     if not encountered_error:
         try:
-            if 'prune' in arguments:
-                command.execute_hook(
-                    hooks.get('after_prune'),
-                    hooks.get('umask'),
-                    config_filename,
-                    'post-prune',
-                    global_arguments.dry_run,
-                )
-            if 'compact' in arguments:
-                command.execute_hook(
-                    hooks.get('after_compact'),
-                    hooks.get('umask'),
-                    config_filename,
-                    'post-compact',
-                    global_arguments.dry_run,
-                )
-            if 'create' in arguments:
-                dispatch.call_hooks(
-                    'remove_database_dumps',
-                    hooks,
-                    config_filename,
-                    dump.DATABASE_HOOK_NAMES,
-                    location,
-                    global_arguments.dry_run,
-                )
-                command.execute_hook(
-                    hooks.get('after_backup'),
-                    hooks.get('umask'),
-                    config_filename,
-                    'post-backup',
-                    global_arguments.dry_run,
-                )
-            if 'check' in arguments:
-                command.execute_hook(
-                    hooks.get('after_check'),
-                    hooks.get('umask'),
-                    config_filename,
-                    'post-check',
-                    global_arguments.dry_run,
-                )
-            if 'extract' in arguments:
-                command.execute_hook(
-                    hooks.get('after_extract'),
-                    hooks.get('umask'),
-                    config_filename,
-                    'post-extract',
-                    global_arguments.dry_run,
-                )
             if using_primary_action:
                 dispatch.call_hooks(
                     'ping_monitor',
@@ -252,9 +175,7 @@ def run_configuration(config_filename, config, arguments):
                 return
 
             encountered_error = error
-            yield from make_error_log_records(
-                '{}: Error running post hook'.format(config_filename), error
-            )
+            yield from log_error_records('{}: Error pinging monitor'.format(config_filename), error)
 
     if encountered_error and using_primary_action:
         try:
@@ -289,7 +210,7 @@ def run_configuration(config_filename, config, arguments):
             if command.considered_soft_failure(config_filename, error):
                 return
 
-            yield from make_error_log_records(
+            yield from log_error_records(
                 '{}: Error running on-error hook'.format(config_filename), error
             )
 
@@ -297,6 +218,7 @@ def run_configuration(config_filename, config, arguments):
 def run_actions(
     *,
     arguments,
+    config_filename,
     location,
     storage,
     retention,
@@ -306,20 +228,28 @@ def run_actions(
     remote_path,
     local_borg_version,
     repository_path,
-):  # pragma: no cover
+):
     '''
-    Given parsed command-line arguments as an argparse.ArgumentParser instance, 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.
+    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.
 
     Yield JSON output strings from executing any actions that produce JSON.
 
     Raise OSError or subprocess.CalledProcessError if an error occurs running a command for an
-    action. Raise ValueError if the arguments or configuration passed to action are invalid.
+    action or a hook. Raise ValueError if the arguments or configuration passed to action are
+    invalid.
     '''
     repository = os.path.expanduser(repository_path)
     global_arguments = arguments['global']
     dry_run_label = ' (dry run; not making any changes)' if global_arguments.dry_run else ''
+    hook_context = {
+        'repository': repository_path,
+        # Deprecated: For backwards compatibility with borgmatic < 1.6.0.
+        'repositories': ','.join(location['repositories']),
+    }
+
     if 'init' in arguments:
         logger.info('{}: Initializing repository'.format(repository))
         borg_init.initialize_repository(
@@ -332,6 +262,14 @@ def run_actions(
             remote_path=remote_path,
         )
     if 'prune' in arguments:
+        command.execute_hook(
+            hooks.get('before_prune'),
+            hooks.get('umask'),
+            config_filename,
+            'pre-prune',
+            global_arguments.dry_run,
+            **hook_context,
+        )
         logger.info('{}: Pruning archives{}'.format(repository, dry_run_label))
         borg_prune.prune_archives(
             global_arguments.dry_run,
@@ -343,7 +281,22 @@ def run_actions(
             stats=arguments['prune'].stats,
             files=arguments['prune'].files,
         )
+        command.execute_hook(
+            hooks.get('after_prune'),
+            hooks.get('umask'),
+            config_filename,
+            'post-prune',
+            global_arguments.dry_run,
+            **hook_context,
+        )
     if 'compact' in arguments:
+        command.execute_hook(
+            hooks.get('before_compact'),
+            hooks.get('umask'),
+            config_filename,
+            'pre-compact',
+            global_arguments.dry_run,
+        )
         if borg_feature.available(borg_feature.Feature.COMPACT, local_borg_version):
             logger.info('{}: Compacting segments{}'.format(repository, dry_run_label))
             borg_compact.compact_segments(
@@ -356,11 +309,26 @@ def run_actions(
                 cleanup_commits=arguments['compact'].cleanup_commits,
                 threshold=arguments['compact'].threshold,
             )
-        else:
+        else:  # pragma: nocover
             logger.info(
                 '{}: Skipping compact (only available/needed in Borg 1.2+)'.format(repository)
             )
+        command.execute_hook(
+            hooks.get('after_compact'),
+            hooks.get('umask'),
+            config_filename,
+            'post-compact',
+            global_arguments.dry_run,
+        )
     if 'create' in arguments:
+        command.execute_hook(
+            hooks.get('before_backup'),
+            hooks.get('umask'),
+            config_filename,
+            'pre-backup',
+            global_arguments.dry_run,
+            **hook_context,
+        )
         logger.info('{}: Creating archive{}'.format(repository, dry_run_label))
         dispatch.call_hooks(
             'remove_database_dumps',
@@ -394,10 +362,35 @@ def run_actions(
             files=arguments['create'].files,
             stream_processes=stream_processes,
         )
-        if json_output:
+        if json_output:  # pragma: nocover
             yield json.loads(json_output)
 
+        dispatch.call_hooks(
+            'remove_database_dumps',
+            hooks,
+            config_filename,
+            dump.DATABASE_HOOK_NAMES,
+            location,
+            global_arguments.dry_run,
+        )
+        command.execute_hook(
+            hooks.get('after_backup'),
+            hooks.get('umask'),
+            config_filename,
+            'post-backup',
+            global_arguments.dry_run,
+            **hook_context,
+        )
+
     if 'check' in arguments and checks.repository_enabled_for_checks(repository, consistency):
+        command.execute_hook(
+            hooks.get('before_check'),
+            hooks.get('umask'),
+            config_filename,
+            'pre-check',
+            global_arguments.dry_run,
+            **hook_context,
+        )
         logger.info('{}: Running consistency checks'.format(repository))
         borg_check.check_archives(
             repository,
@@ -409,7 +402,23 @@ def run_actions(
             repair=arguments['check'].repair,
             only_checks=arguments['check'].only,
         )
+        command.execute_hook(
+            hooks.get('after_check'),
+            hooks.get('umask'),
+            config_filename,
+            'post-check',
+            global_arguments.dry_run,
+            **hook_context,
+        )
     if 'extract' in arguments:
+        command.execute_hook(
+            hooks.get('before_extract'),
+            hooks.get('umask'),
+            config_filename,
+            'pre-extract',
+            global_arguments.dry_run,
+            **hook_context,
+        )
         if arguments['extract'].repository is None or validate.repositories_match(
             repository, arguments['extract'].repository
         ):
@@ -432,6 +441,14 @@ def run_actions(
                 strip_components=arguments['extract'].strip_components,
                 progress=arguments['extract'].progress,
             )
+        command.execute_hook(
+            hooks.get('after_extract'),
+            hooks.get('umask'),
+            config_filename,
+            'post-extract',
+            global_arguments.dry_run,
+            **hook_context,
+        )
     if 'export-tar' in arguments:
         if arguments['export-tar'].repository is None or validate.repositories_match(
             repository, arguments['export-tar'].repository
@@ -464,7 +481,7 @@ def run_actions(
                 logger.info(
                     '{}: Mounting archive {}'.format(repository, arguments['mount'].archive)
                 )
-            else:
+            else:  # pragma: nocover
                 logger.info('{}: Mounting repository'.format(repository))
 
             borg_mount.mount_archive(
@@ -480,7 +497,7 @@ def run_actions(
                 local_path=local_path,
                 remote_path=remote_path,
             )
-    if 'restore' in arguments:
+    if 'restore' in arguments:  # pragma: nocover
         if arguments['restore'].repository is None or validate.repositories_match(
             repository, arguments['restore'].repository
         ):
@@ -579,7 +596,7 @@ def run_actions(
             repository, arguments['list'].repository
         ):
             list_arguments = copy.copy(arguments['list'])
-            if not list_arguments.json:
+            if not list_arguments.json:  # pragma: nocover
                 logger.warning('{}: Listing archives'.format(repository))
             list_arguments.archive = borg_list.resolve_archive_name(
                 repository, list_arguments.archive, storage, local_path, remote_path
@@ -591,14 +608,14 @@ def run_actions(
                 local_path=local_path,
                 remote_path=remote_path,
             )
-            if json_output:
+            if json_output:  # pragma: nocover
                 yield json.loads(json_output)
     if 'info' in arguments:
         if arguments['info'].repository is None or validate.repositories_match(
             repository, arguments['info'].repository
         ):
             info_arguments = copy.copy(arguments['info'])
-            if not info_arguments.json:
+            if not info_arguments.json:  # pragma: nocover
                 logger.warning('{}: Displaying summary info for archives'.format(repository))
             info_arguments.archive = borg_list.resolve_archive_name(
                 repository, info_arguments.archive, storage, local_path, remote_path
@@ -610,7 +627,7 @@ def run_actions(
                 local_path=local_path,
                 remote_path=remote_path,
             )
-            if json_output:
+            if json_output:  # pragma: nocover
                 yield json.loads(json_output)
     if 'borg' in arguments:
         if arguments['borg'].repository is None or validate.repositories_match(
@@ -646,6 +663,20 @@ def load_configurations(config_filenames, overrides=None):
             configs[config_filename] = validate.parse_configuration(
                 config_filename, validate.schema_filename(), overrides
             )
+        except PermissionError:
+            logs.extend(
+                [
+                    logging.makeLogRecord(
+                        dict(
+                            levelno=logging.WARNING,
+                            levelname='WARNING',
+                            msg='{}: Insufficient permissions to read configuration file'.format(
+                                config_filename
+                            ),
+                        )
+                    ),
+                ]
+            )
         except (ValueError, OSError, validate.Validation_error) as error:
             logs.extend(
                 [
@@ -678,28 +709,39 @@ def log_record(suppress_log=False, **kwargs):
     return record
 
 
-def make_error_log_records(message, error=None):
+def log_error_records(
+    message, error=None, levelno=logging.CRITICAL, log_command_error_output=False
+):
     '''
-    Given error message text and an optional exception object, yield a series of logging.LogRecord
-    instances with error summary information. As a side effect, log each record.
+    Given error message text, an optional exception object, an optional log level, and whether to
+    log the error output of a CalledProcessError (if any), log error summary information and also
+    yield it as a series of logging.LogRecord instances.
+
+    Note that because the logs are yielded as a generator, logs won't get logged unless you consume
+    the generator output.
     '''
+    level_name = logging._levelToName[levelno]
+
     if not error:
-        yield log_record(levelno=logging.CRITICAL, levelname='CRITICAL', msg=message)
+        yield log_record(levelno=levelno, levelname=level_name, msg=message)
         return
 
     try:
         raise error
     except CalledProcessError as error:
-        yield log_record(levelno=logging.CRITICAL, levelname='CRITICAL', msg=message)
+        yield log_record(levelno=levelno, levelname=level_name, msg=message)
         if error.output:
             # Suppress these logs for now and save full error output for the log summary at the end.
             yield log_record(
-                levelno=logging.CRITICAL, levelname='CRITICAL', msg=error.output, suppress_log=True
+                levelno=levelno,
+                levelname=level_name,
+                msg=error.output,
+                suppress_log=not log_command_error_output,
             )
-        yield log_record(levelno=logging.CRITICAL, levelname='CRITICAL', msg=error)
+        yield log_record(levelno=levelno, levelname=level_name, msg=error)
     except (ValueError, OSError) as error:
-        yield log_record(levelno=logging.CRITICAL, levelname='CRITICAL', msg=message)
-        yield log_record(levelno=logging.CRITICAL, levelname='CRITICAL', msg=error)
+        yield log_record(levelno=levelno, levelname=level_name, msg=message)
+        yield log_record(levelno=levelno, levelname=level_name, msg=error)
     except:  # noqa: E722
         # Raising above only as a means of determining the error type. Swallow the exception here
         # because we don't want the exception to propagate out of this function.
@@ -738,11 +780,11 @@ def collect_configuration_run_summary_logs(configs, arguments):
         try:
             validate.guard_configuration_contains_repository(repository, configs)
         except ValueError as error:
-            yield from make_error_log_records(str(error))
+            yield from log_error_records(str(error))
             return
 
     if not configs:
-        yield from make_error_log_records(
+        yield from log_error_records(
             '{}: No valid configuration files found'.format(
                 ' '.join(arguments['global'].config_paths)
             )
@@ -761,7 +803,7 @@ def collect_configuration_run_summary_logs(configs, arguments):
                     arguments['global'].dry_run,
                 )
         except (CalledProcessError, ValueError, OSError) as error:
-            yield from make_error_log_records('Error running pre-everything hook', error)
+            yield from log_error_records('Error running pre-everything hook', error)
             return
 
     # Execute the actions corresponding to each configuration file.
@@ -771,7 +813,7 @@ def collect_configuration_run_summary_logs(configs, arguments):
         error_logs = tuple(result for result in results if isinstance(result, logging.LogRecord))
 
         if error_logs:
-            yield from make_error_log_records(
+            yield from log_error_records(
                 '{}: Error running configuration file'.format(config_filename)
             )
             yield from error_logs
@@ -793,7 +835,7 @@ def collect_configuration_run_summary_logs(configs, arguments):
                 mount_point=arguments['umount'].mount_point, local_path=get_local_path(configs)
             )
         except (CalledProcessError, OSError) as error:
-            yield from make_error_log_records('Error unmounting mount point', error)
+            yield from log_error_records('Error unmounting mount point', error)
 
     if json_results:
         sys.stdout.write(json.dumps(json_results))
@@ -810,7 +852,7 @@ def collect_configuration_run_summary_logs(configs, arguments):
                     arguments['global'].dry_run,
                 )
         except (CalledProcessError, ValueError, OSError) as error:
-            yield from make_error_log_records('Error running post-everything hook', error)
+            yield from log_error_records('Error running post-everything hook', error)
 
 
 def exit_with_help_link():  # pragma: no cover

borgmatic/config/load.py

@@ -6,6 +6,19 @@ import ruamel.yaml
 logger = logging.getLogger(__name__)
 
 
+class Yaml_with_loader_stream(ruamel.yaml.YAML):
+    '''
+    A derived class of ruamel.yaml.YAML that simply tacks the loaded stream (file object) onto the
+    loader class so that it's available anywhere that's passed a loader (in this case,
+    include_configuration() below).
+    '''
+
+    def get_constructor_parser(self, stream):
+        constructor, parser = super(Yaml_with_loader_stream, self).get_constructor_parser(stream)
+        constructor.loader.stream = stream
+        return constructor, parser
+
+
 def load_configuration(filename):
     '''
     Load the given configuration file and return its contents as a data structure of nested dicts
@@ -14,7 +27,7 @@ def load_configuration(filename):
     Raise ruamel.yaml.error.YAMLError if something goes wrong parsing the YAML, or RecursionError
     if there are too many recursive includes.
     '''
-    yaml = ruamel.yaml.YAML(typ='safe')
+    yaml = Yaml_with_loader_stream(typ='safe')
     yaml.Constructor = Include_constructor
 
     return yaml.load(open(filename))
@@ -22,10 +35,146 @@ def load_configuration(filename):
 
 def include_configuration(loader, filename_node):
     '''
-    Load the given YAML filename (ignoring the given loader so we can use our own), and return its
-    contents as a data structure of nested dicts and lists.
+    Load the given YAML filename (ignoring the given loader so we can use our own) and return its
+    contents as a data structure of nested dicts and lists. If the filename is relative, probe for
+    it within 1. the current working directory and 2. the directory containing the YAML file doing
+    the including.
+
+    Raise FileNotFoundError if an included file was not found.
     '''
-    return load_configuration(os.path.expanduser(filename_node.value))
+    include_directories = [os.getcwd(), os.path.abspath(os.path.dirname(loader.stream.name))]
+    include_filename = os.path.expanduser(filename_node.value)
+
+    if not os.path.isabs(include_filename):
+        candidate_filenames = [
+            os.path.join(directory, include_filename) for directory in include_directories
+        ]
+
+        for candidate_filename in candidate_filenames:
+            if os.path.exists(candidate_filename):
+                include_filename = candidate_filename
+                break
+        else:
+            raise FileNotFoundError(
+                f'Could not find include {filename_node.value} at {" or ".join(candidate_filenames)}'
+            )
+
+    return load_configuration(include_filename)
+
+
+DELETED_NODE = object()
+
+
+def deep_merge_nodes(nodes):
+    '''
+    Given a nested borgmatic configuration data structure as a list of tuples in the form of:
+
+        (
+            ruamel.yaml.nodes.ScalarNode as a key,
+            ruamel.yaml.nodes.MappingNode or other Node as a value,
+        ),
+
+    ... deep merge any node values corresponding to duplicate keys and return the result. If
+    there are colliding keys with non-MappingNode values (e.g., integers or strings), the last
+    of the values wins.
+
+    For instance, given node values of:
+
+        [
+            (
+                ScalarNode(tag='tag:yaml.org,2002:str', value='retention'),
+                MappingNode(tag='tag:yaml.org,2002:map', value=[
+                    (
+                        ScalarNode(tag='tag:yaml.org,2002:str', value='keep_hourly'),
+                        ScalarNode(tag='tag:yaml.org,2002:int', value='24')
+                    ),
+                    (
+                        ScalarNode(tag='tag:yaml.org,2002:str', value='keep_daily'),
+                        ScalarNode(tag='tag:yaml.org,2002:int', value='7')
+                    ),
+                ]),
+            ),
+            (
+                ScalarNode(tag='tag:yaml.org,2002:str', value='retention'),
+                MappingNode(tag='tag:yaml.org,2002:map', value=[
+                    (
+                        ScalarNode(tag='tag:yaml.org,2002:str', value='keep_daily'),
+                        ScalarNode(tag='tag:yaml.org,2002:int', value='5')
+                    ),
+                ]),
+            ),
+        ]
+
+    ... the returned result would be:
+
+        [
+            (
+                ScalarNode(tag='tag:yaml.org,2002:str', value='retention'),
+                MappingNode(tag='tag:yaml.org,2002:map', value=[
+                    (
+                        ScalarNode(tag='tag:yaml.org,2002:str', value='keep_hourly'),
+                        ScalarNode(tag='tag:yaml.org,2002:int', value='24')
+                    ),
+                    (
+                        ScalarNode(tag='tag:yaml.org,2002:str', value='keep_daily'),
+                        ScalarNode(tag='tag:yaml.org,2002:int', value='5')
+                    ),
+                ]),
+            ),
+        ]
+
+    The purpose of deep merging like this is to support, for instance, merging one borgmatic
+    configuration file into another for reuse, such that a configuration section ("retention",
+    etc.) does not completely replace the corresponding section in a merged file.
+    '''
+    # Map from original node key/value to the replacement merged node. DELETED_NODE as a replacement
+    # node indications deletion.
+    replaced_nodes = {}
+
+    # To find nodes that require merging, compare each node with each other node.
+    for a_key, a_value in nodes:
+        for b_key, b_value in nodes:
+            # If we've already considered one of the nodes for merging, skip it.
+            if (a_key, a_value) in replaced_nodes or (b_key, b_value) in replaced_nodes:
+                continue
+
+            # If the keys match and the values are different, we need to merge these two A and B nodes.
+            if a_key.tag == b_key.tag and a_key.value == b_key.value and a_value != b_value:
+                # Since we're merging into the B node, consider the A node a duplicate and remove it.
+                replaced_nodes[(a_key, a_value)] = DELETED_NODE
+
+                # If we're dealing with MappingNodes, recurse and merge its values as well.
+                if isinstance(b_value, ruamel.yaml.nodes.MappingNode):
+                    replaced_nodes[(b_key, b_value)] = (
+                        b_key,
+                        ruamel.yaml.nodes.MappingNode(
+                            tag=b_value.tag,
+                            value=deep_merge_nodes(a_value.value + b_value.value),
+                            start_mark=b_value.start_mark,
+                            end_mark=b_value.end_mark,
+                            flow_style=b_value.flow_style,
+                            comment=b_value.comment,
+                            anchor=b_value.anchor,
+                        ),
+                    )
+                # If we're dealing with SequenceNodes, merge by appending one sequence to the other.
+                elif isinstance(b_value, ruamel.yaml.nodes.SequenceNode):
+                    replaced_nodes[(b_key, b_value)] = (
+                        b_key,
+                        ruamel.yaml.nodes.SequenceNode(
+                            tag=b_value.tag,
+                            value=a_value.value + b_value.value,
+                            start_mark=b_value.start_mark,
+                            end_mark=b_value.end_mark,
+                            flow_style=b_value.flow_style,
+                            comment=b_value.comment,
+                            anchor=b_value.anchor,
+                        ),
+                    )
+
+    return [
+        replaced_nodes.get(node, node) for node in nodes if replaced_nodes.get(node) != DELETED_NODE
+    ]
 
 
 class Include_constructor(ruamel.yaml.SafeConstructor):
@@ -40,14 +189,19 @@ class Include_constructor(ruamel.yaml.SafeConstructor):
 
     def flatten_mapping(self, node):
         '''
-        Support the special case of shallow merging included configuration into an existing mapping
+        Support the special case of deep merging included configuration into an existing mapping
         using the YAML '<<' merge key. Example syntax:
 
         ```
         retention:
             keep_daily: 1
-            <<: !include common.yaml
+
+        <<: !include common.yaml
         ```
+
+        These includes are deep merged into the current configuration file. For instance, in this
+        example, any "retention" options in common.yaml will get merged into the "retention" section
+        in the example configuration file.
         '''
         representer = ruamel.yaml.representer.SafeRepresenter()
 
@@ -57,3 +211,5 @@ class Include_constructor(ruamel.yaml.SafeConstructor):
                 node.value[index] = (key_node, included_value)
 
         super(Include_constructor, self).flatten_mapping(node)
+
+        node.value = deep_merge_nodes(node.value)

borgmatic/config/normalize.py

@@ -3,8 +3,24 @@ def normalize(config):
     Given a configuration dict, apply particular hard-coded rules to normalize its contents to
     adhere to the configuration schema.
     '''
+    # Upgrade exclude_if_present from a string to a list.
     exclude_if_present = config.get('location', {}).get('exclude_if_present')
-
-    # "Upgrade" exclude_if_present from a string to a list.
     if isinstance(exclude_if_present, str):
         config['location']['exclude_if_present'] = [exclude_if_present]
+
+    # Upgrade various monitoring hooks from a string to a dict.
+    healthchecks = config.get('hooks', {}).get('healthchecks')
+    if isinstance(healthchecks, str):
+        config['hooks']['healthchecks'] = {'ping_url': healthchecks}
+
+    cronitor = config.get('hooks', {}).get('cronitor')
+    if isinstance(cronitor, str):
+        config['hooks']['cronitor'] = {'ping_url': cronitor}
+
+    pagerduty = config.get('hooks', {}).get('pagerduty')
+    if isinstance(pagerduty, str):
+        config['hooks']['pagerduty'] = {'integration_key': pagerduty}
+
+    cronhub = config.get('hooks', {}).get('cronhub')
+    if isinstance(cronhub, str):
+        config['hooks']['cronhub'] = {'ping_url': cronhub}

borgmatic/config/override.py

@@ -52,16 +52,20 @@ def parse_overrides(raw_overrides):
     if not raw_overrides:
         return ()
 
-    try:
-        return tuple(
-            (tuple(raw_keys.split('.')), convert_value_type(value))
-            for raw_override in raw_overrides
-            for raw_keys, value in (raw_override.split('=', 1),)
-        )
-    except ValueError:
-        raise ValueError('Invalid override. Make sure you use the form: SECTION.OPTION=VALUE')
-    except ruamel.yaml.error.YAMLError as error:
-        raise ValueError(f'Invalid override value: {error}')
+    parsed_overrides = []
+
+    for raw_override in raw_overrides:
+        try:
+            raw_keys, value = raw_override.split('=', 1)
+            parsed_overrides.append((tuple(raw_keys.split('.')), convert_value_type(value),))
+        except ValueError:
+            raise ValueError(
+                f"Invalid override '{raw_override}'. Make sure you use the form: SECTION.OPTION=VALUE"
+            )
+        except ruamel.yaml.error.YAMLError as error:
+            raise ValueError(f"Invalid override '{raw_override}': {error.problem}")
+
+    return tuple(parsed_overrides)
 
 
 def apply_overrides(config, raw_overrides):

borgmatic/config/schema.yaml

@@ -42,13 +42,21 @@ properties:
                 example:
                     - user@backupserver:sourcehostname.borg
                     - "user@backupserver:{fqdn}"
+            working_directory:
+                type: string
+                description: |
+                    Working directory for the "borg create" command. Tildes are
+                    expanded. Useful for backing up using relative paths. See
+                    http://borgbackup.readthedocs.io/en/stable/usage/create.html
+                    for details. Defaults to not set.
+                example: /path/to/working/directory
             one_file_system:
                 type: boolean
                 description: |
-                    Stay in same file system (do not cross mount points).
-                    Defaults to false. But when a database hook is used, the
-                    setting here is ignored and one_file_system is considered
-                    true.
+                    Stay in same file system: do not cross mount points beyond
+                    the given source directories. Defaults to false. But when a
+                    database hook is used, the setting here is ignored and
+                    one_file_system is considered true.
                 example: true
             numeric_owner:
                 type: boolean
@@ -324,10 +332,10 @@ properties:
                     Name of the archive. Borg placeholders can be used. See the
                     output of "borg help placeholders" for details. Defaults to
                     "{hostname}-{now:%Y-%m-%dT%H:%M:%S.%f}". If you specify this
-                    option, you must also specify a prefix in the retention
-                    section to avoid accidental pruning of archives with a
-                    different archive name format. And you should also specify a
-                    prefix in the consistency section as well.
+                    option, consider also specifying a prefix in the retention
+                    and consistency sections to avoid accidental
+                    pruning/checking of archives with different archive name
+                    formats.
                 example: "{hostname}-documents-{now}"
             relocated_repo_access_is_ok:
                 type: boolean
@@ -874,41 +882,99 @@ properties:
                     https://docs.mongodb.com/database-tools/mongorestore/ for
                     details.
             healthchecks:
-                type: string
+                type: object
+                required: ['ping_url']
+                additionalProperties: false
+                properties:
+                    ping_url:
+                        type: string
+                        description: |
+                            Healthchecks ping URL or UUID to notify when a
+                            backup begins, ends, or errors.
+                        example: https://hc-ping.com/your-uuid-here
+                    send_logs:
+                        type: boolean
+                        description: |
+                            Send borgmatic logs to Healthchecks as part the
+                            "finish" state. Defaults to true.
+                        example: false
+                    ping_body_limit:
+                        type: integer
+                        description: |
+                            Number of bytes of borgmatic logs to send to
+                            Healthchecks, ideally the same as PING_BODY_LIMIT
+                            configured on the Healthchecks server. Set to 0 to
+                            send all logs and disable this truncation. Defaults
+                            to 100000.
+                        example: 200000
+                    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 all states.
+                        example:
+                            - finish
                 description: |
-                    Healthchecks ping URL or UUID to notify when a backup
-                    begins, ends, or errors. Create an account at
-                    https://healthchecks.io if you'd like to use this service.
-                    See borgmatic monitoring documentation for details.
-                example:
-                    https://hc-ping.com/your-uuid-here
-            cronitor:
-                type: string
-                description: |
-                    Cronitor ping URL to notify when a backup begins, ends, or
-                    errors. Create an account at https://cronitor.io if you'd
-                    like to use this service. See borgmatic monitoring
-                    documentation for details.
-                example:
-                    https://cronitor.link/d3x0c1
-            pagerduty:
-                type: string
-                description: |
-                    PagerDuty integration key used to notify PagerDuty when a
-                    backup errors. Create an account at
-                    https://www.pagerduty.com/ if you'd like to use this
+                    Configuration for a monitoring integration with
+                    Healthchecks. Create an account at https://healthchecks.io
+                    (or self-host Healthchecks) if you'd like to use this
                     service. See borgmatic monitoring documentation for details.
-                example:
-                    a177cad45bd374409f78906a810a3074
-            cronhub:
-                type: string
+            cronitor:
+                type: object
+                required: ['ping_url']
+                additionalProperties: false
+                properties:
+                    ping_url:
+                        type: string
+                        description: |
+                            Cronitor ping URL to notify when a backup begins,
+                            ends, or errors.
+                        example: https://cronitor.link/d3x0c1
                 description: |
-                    Cronhub ping URL to notify when a backup begins, ends, or
-                    errors. Create an account at https://cronhub.io if you'd
+                    Configuration for a monitoring integration with Cronitor.
+                    Create an account at https://cronitor.io if you'd
                     like to use this service. See borgmatic monitoring
                     documentation for details.
-                example:
-                    https://cronhub.io/start/1f5e3410-254c-11e8-b61d-55875966d01
+            pagerduty:
+                type: object
+                required: ['integration_key']
+                additionalProperties: false
+                properties:
+                    integration_key:
+                        type: string
+                        description: |
+                            PagerDuty integration key used to notify PagerDuty
+                            when a backup errors.
+                        example: a177cad45bd374409f78906a810a3074
+                description: |
+                    Configuration for a monitoring integration with PagerDuty.
+                    Create an account at https://www.pagerduty.com/ if you'd
+                    like to use this service. See borgmatic monitoring
+                    documentation for details.
+            cronhub:
+                type: object
+                required: ['ping_url']
+                additionalProperties: false
+                properties:
+                    ping_url:
+                        type: string
+                        description: |
+                            Cronhub ping URL to notify when a backup begins,
+                            ends, or errors.
+                        example: https://cronhub.io/ping/1f5e3410-254c-5587
+                description: |
+                    Configuration for a monitoring integration with Crunhub.
+                    Create an account at https://cronhub.io if you'd like to
+                    use this service. See borgmatic monitoring documentation
+                    for details.
             umask:
                 type: integer
                 description: |

borgmatic/config/validate.py

@@ -65,15 +65,6 @@ def apply_logical_validation(config_filename, parsed_configuration):
     below), run through any additional logical validation checks. If there are any such validation
     problems, raise a Validation_error.
     '''
-    archive_name_format = parsed_configuration.get('storage', {}).get('archive_name_format')
-    prefix = parsed_configuration.get('retention', {}).get('prefix')
-
-    if archive_name_format and not prefix:
-        raise Validation_error(
-            config_filename,
-            ('If you provide an archive_name_format, you must also specify a retention prefix.',),
-        )
-
     location_repositories = parsed_configuration.get('location', {}).get('repositories')
     check_repositories = parsed_configuration.get('consistency', {}).get('check_repositories', [])
     for repository in check_repositories:

borgmatic/hooks/command.py

@@ -1,5 +1,6 @@
 import logging
 import os
+import re
 
 from borgmatic import execute
 
@@ -9,14 +10,19 @@ logger = logging.getLogger(__name__)
 SOFT_FAIL_EXIT_CODE = 75
 
 
-def interpolate_context(command, context):
+def interpolate_context(config_filename, hook_description, command, context):
     '''
-    Given a single hook command and a dict of context names/values, interpolate the values by
-    "{name}" into the command and return the result.
+    Given a config filename, a hook description, a single hook command, and a dict of context
+    names/values, interpolate the values by "{name}" into the command and return the result.
     '''
     for name, value in context.items():
         command = command.replace('{%s}' % name, str(value))
 
+    for unsupported_variable in re.findall(r'{\w+}', command):
+        logger.warning(
+            f"{config_filename}: Variable '{unsupported_variable}' is not supported in {hook_description} hook"
+        )
+
     return command
 
 
@@ -26,8 +32,7 @@ def execute_hook(commands, umask, config_filename, description, dry_run, **conte
     a hook description, and whether this is a dry run, run the given commands. Or, don't run them
     if this is a dry run.
 
-    The context contains optional values interpolated by name into the hook commands. Currently,
-    this only applies to the on_error hook.
+    The context contains optional values interpolated by name into the hook commands.
 
     Raise ValueError if the umask cannot be parsed.
     Raise subprocesses.CalledProcessError if an error occurs in a hook.
@@ -39,7 +44,9 @@ def execute_hook(commands, umask, config_filename, description, dry_run, **conte
     dry_run_label = ' (dry run; not actually running hooks)' if dry_run else ''
 
     context['configuration_filename'] = config_filename
-    commands = [interpolate_context(command, context) for command in commands]
+    commands = [
+        interpolate_context(config_filename, description, command, context) for command in commands
+    ]
 
     if len(commands) == 1:
         logger.info(

borgmatic/hooks/cronhub.py

@@ -22,14 +22,18 @@ def initialize_monitor(
     pass
 
 
-def ping_monitor(ping_url, config_filename, state, monitoring_log_level, dry_run):
+def ping_monitor(hook_config, config_filename, state, monitoring_log_level, dry_run):
     '''
-    Ping the given Cronhub URL, modified with the monitor.State. Use the given configuration
+    Ping the configured Cronhub URL, modified with the monitor.State. Use the given configuration
     filename in any log entries. If this is a dry run, then don't actually ping anything.
     '''
     dry_run_label = ' (dry run; not actually pinging)' if dry_run else ''
     formatted_state = '/{}/'.format(MONITOR_STATE_TO_CRONHUB[state])
-    ping_url = ping_url.replace('/start/', formatted_state).replace('/ping/', formatted_state)
+    ping_url = (
+        hook_config['ping_url']
+        .replace('/start/', formatted_state)
+        .replace('/ping/', formatted_state)
+    )
 
     logger.info(
         '{}: Pinging Cronhub {}{}'.format(config_filename, state.name.lower(), dry_run_label)
@@ -38,7 +42,10 @@ def ping_monitor(ping_url, config_filename, state, monitoring_log_level, dry_run
 
     if not dry_run:
         logging.getLogger('urllib3').setLevel(logging.ERROR)
-        requests.get(ping_url)
+        try:
+            requests.get(ping_url)
+        except requests.exceptions.RequestException as error:
+            logger.warning(f'{config_filename}: Cronhub error: {error}')
 
 
 def destroy_monitor(

borgmatic/hooks/cronitor.py

@@ -22,13 +22,13 @@ def initialize_monitor(
     pass
 
 
-def ping_monitor(ping_url, config_filename, state, monitoring_log_level, dry_run):
+def ping_monitor(hook_config, config_filename, state, monitoring_log_level, dry_run):
     '''
-    Ping the given Cronitor URL, modified with the monitor.State. Use the given configuration
+    Ping the configured Cronitor URL, modified with the monitor.State. Use the given configuration
     filename in any log entries. If this is a dry run, then don't actually ping anything.
     '''
     dry_run_label = ' (dry run; not actually pinging)' if dry_run else ''
-    ping_url = '{}/{}'.format(ping_url, MONITOR_STATE_TO_CRONITOR[state])
+    ping_url = '{}/{}'.format(hook_config['ping_url'], MONITOR_STATE_TO_CRONITOR[state])
 
     logger.info(
         '{}: Pinging Cronitor {}{}'.format(config_filename, state.name.lower(), dry_run_label)
@@ -37,7 +37,10 @@ def ping_monitor(ping_url, config_filename, state, monitoring_log_level, dry_run
 
     if not dry_run:
         logging.getLogger('urllib3').setLevel(logging.ERROR)
-        requests.get(ping_url)
+        try:
+            requests.get(ping_url)
+        except requests.exceptions.RequestException as error:
+            logger.warning(f'{config_filename}: Cronitor error: {error}')
 
 
 def destroy_monitor(

borgmatic/hooks/healthchecks.py

@@ -13,13 +13,14 @@ MONITOR_STATE_TO_HEALTHCHECKS = {
 }
 
 PAYLOAD_TRUNCATION_INDICATOR = '...\n'
-PAYLOAD_LIMIT_BYTES = 10 * 1024 - len(PAYLOAD_TRUNCATION_INDICATOR)
+DEFAULT_PING_BODY_LIMIT_BYTES = 100000
 
 
 class Forgetful_buffering_handler(logging.Handler):
     '''
     A buffering log handler that stores log messages in memory, and throws away messages (oldest
-    first) once a particular capacity in bytes is reached.
+    first) once a particular capacity in bytes is reached. But if the given byte capacity is zero,
+    don't throw away any messages.
     '''
 
     def __init__(self, byte_capacity, log_level):
@@ -36,6 +37,9 @@ class Forgetful_buffering_handler(logging.Handler):
         self.byte_count += len(message)
         self.buffer.append(message)
 
+        if not self.byte_capacity:
+            return
+
         while self.byte_count > self.byte_capacity and self.buffer:
             self.byte_count -= len(self.buffer[0])
             self.buffer.pop(0)
@@ -65,31 +69,45 @@ def format_buffered_logs_for_payload():
     return payload
 
 
-def initialize_monitor(
-    ping_url_or_uuid, config_filename, monitoring_log_level, dry_run
-):  # pragma: no cover
+def initialize_monitor(hook_config, config_filename, monitoring_log_level, dry_run):
     '''
-    Add a handler to the root logger that stores in memory the most recent logs emitted. That
-    way, we can send them all to Healthchecks upon a finish or failure state.
+    Add a handler to the root logger that stores in memory the most recent logs emitted. That way,
+    we can send them all to Healthchecks upon a finish or failure state. But skip this if the
+    "send_logs" option is false.
     '''
+    if hook_config.get('send_logs') is False:
+        return
+
+    ping_body_limit = max(
+        hook_config.get('ping_body_limit', DEFAULT_PING_BODY_LIMIT_BYTES)
+        - len(PAYLOAD_TRUNCATION_INDICATOR),
+        0,
+    )
+
     logging.getLogger().addHandler(
-        Forgetful_buffering_handler(PAYLOAD_LIMIT_BYTES, monitoring_log_level)
+        Forgetful_buffering_handler(ping_body_limit, monitoring_log_level)
     )
 
 
-def ping_monitor(ping_url_or_uuid, config_filename, state, monitoring_log_level, dry_run):
+def ping_monitor(hook_config, config_filename, state, monitoring_log_level, dry_run):
     '''
-    Ping the given Healthchecks URL or UUID, modified with the monitor.State. Use the given
+    Ping the configured Healthchecks URL or UUID, modified with the monitor.State. Use the given
     configuration filename in any log entries, and log to Healthchecks with the giving log level.
     If this is a dry run, then don't actually ping anything.
     '''
     ping_url = (
-        ping_url_or_uuid
-        if ping_url_or_uuid.startswith('http')
-        else 'https://hc-ping.com/{}'.format(ping_url_or_uuid)
+        hook_config['ping_url']
+        if hook_config['ping_url'].startswith('http')
+        else 'https://hc-ping.com/{}'.format(hook_config['ping_url'])
     )
     dry_run_label = ' (dry run; not actually pinging)' if dry_run else ''
 
+    if 'states' in hook_config and state.name.lower() not in hook_config['states']:
+        logger.info(
+            f'{config_filename}: Skipping Healthchecks {state.name.lower()} ping due to configured states'
+        )
+        return
+
     healthchecks_state = MONITOR_STATE_TO_HEALTHCHECKS.get(state)
     if healthchecks_state:
         ping_url = '{}/{}'.format(ping_url, healthchecks_state)
@@ -106,10 +124,13 @@ def ping_monitor(ping_url_or_uuid, config_filename, state, monitoring_log_level,
 
     if not dry_run:
         logging.getLogger('urllib3').setLevel(logging.ERROR)
-        requests.post(ping_url, data=payload.encode('utf-8'))
+        try:
+            requests.post(ping_url, data=payload.encode('utf-8'))
+        except requests.exceptions.RequestException as error:
+            logger.warning(f'{config_filename}: Healthchecks error: {error}')
 
 
-def destroy_monitor(ping_url_or_uuid, config_filename, monitoring_log_level, dry_run):
+def destroy_monitor(hook_config, config_filename, monitoring_log_level, dry_run):
     '''
     Remove the monitor handler that was added to the root logger. This prevents the handler from
     getting reused by other instances of this monitor.

borgmatic/hooks/pagerduty.py

@@ -21,10 +21,10 @@ def initialize_monitor(
     pass
 
 
-def ping_monitor(integration_key, config_filename, state, monitoring_log_level, dry_run):
+def ping_monitor(hook_config, config_filename, state, monitoring_log_level, dry_run):
     '''
-    If this is an error state, create a PagerDuty event with the given integration key. Use the
-    given configuration filename in any log entries. If this is a dry run, then don't actually
+    If this is an error state, create a PagerDuty event with the configured integration key. Use
+    the given configuration filename in any log entries. If this is a dry run, then don't actually
     create an event.
     '''
     if state != monitor.State.FAIL:
@@ -47,7 +47,7 @@ def ping_monitor(integration_key, config_filename, state, monitoring_log_level,
     )
     payload = json.dumps(
         {
-            'routing_key': integration_key,
+            'routing_key': hook_config['integration_key'],
             'event_action': 'trigger',
             'payload': {
                 'summary': 'backup failed on {}'.format(hostname),
@@ -68,7 +68,10 @@ def ping_monitor(integration_key, config_filename, state, monitoring_log_level,
     logger.debug('{}: Using PagerDuty payload: {}'.format(config_filename, payload))
 
     logging.getLogger('urllib3').setLevel(logging.ERROR)
-    requests.post(EVENTS_API_URL, data=payload.encode('utf-8'))
+    try:
+        requests.post(EVENTS_API_URL, data=payload.encode('utf-8'))
+    except requests.exceptions.RequestException as error:
+        logger.warning(f'{config_filename}: PagerDuty error: {error}')
 
 
 def destroy_monitor(

borgmatic/signals.py

@@ -1,23 +1,34 @@
+import logging
 import os
 import signal
+import sys
+
+logger = logging.getLogger(__name__)
 
 
-def _handle_signal(signal_number, frame):  # pragma: no cover
+EXIT_CODE_FROM_SIGNAL = 128
+
+
+def handle_signal(signal_number, frame):
     '''
     Send the signal to all processes in borgmatic's process group, which includes child processes.
     '''
     # Prevent infinite signal handler recursion. If the parent frame is this very same handler
     # function, we know we're recursing.
-    if frame.f_back.f_code.co_name == _handle_signal.__name__:
+    if frame.f_back.f_code.co_name == handle_signal.__name__:
         return
 
     os.killpg(os.getpgrp(), signal_number)
 
+    if signal_number == signal.SIGTERM:
+        logger.critical('Exiting due to TERM signal')
+        sys.exit(EXIT_CODE_FROM_SIGNAL + signal.SIGTERM)
 
-def configure_signals():  # pragma: no cover
+
+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.
     '''
     for signal_number in (signal.SIGHUP, signal.SIGTERM, signal.SIGUSR1, signal.SIGUSR2):
-        signal.signal(signal_number, _handle_signal)
+        signal.signal(signal_number, handle_signal)

docs/_includes/index.css

@@ -258,6 +258,7 @@ footer.elv-layout {
 /* Header */
 .elv-header {
 	position: relative;
+        text-align: center;
 }
 .elv-header-default {
 	display: flex;

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

@@ -1,17 +1,18 @@
 ---
 title: How to add preparation and cleanup steps to backups
 eleventyNavigation:
-  key: Add preparation and cleanup steps
+  key: 🧹 Add preparation and cleanup steps
   parent: How-to guides
   order: 8
 ---
 ## Preparation and cleanup hooks
 
-If you find yourself performing prepraration tasks before your backup runs, or
+If you find yourself performing preparation tasks before your backup runs, or
 cleanup work afterwards, borgmatic hooks may be of interest. Hooks are shell
-commands that borgmatic executes for you at various points, and they're
-configured in the `hooks` section of your configuration file. But if you're
-looking to backup a database, it's probably easier to use the [database backup
+commands that borgmatic executes for you at various points as it runs, and
+they're configured in the `hooks` section of your configuration file. But if
+you're looking to backup a database, it's probably easier to use the [database
+backup
 feature](https://torsion.org/borgmatic/docs/how-to/backup-your-databases/)
 instead.
 
@@ -27,15 +28,40 @@ hooks:
         - umount /some/filesystem
 ```
 
-The `before_backup` and `after_backup` hooks each run once per configuration
-file. `before_backup` hooks run prior to backups of all repositories in a
-configuration file, right before the `create` action. `after_backup` hooks run
-afterwards, but not if an error occurs in a previous hook or in the backups
-themselves.
+The `before_backup` and `after_backup` hooks each run once per repository in a
+configuration file. `before_backup` hooks runs right before the `create`
+action for a particular repository, and `after_backup` hooks run afterwards,
+but not if an error occurs in a previous hook or in the backups themselves.
+(Prior to borgmatic 1.6.0, these hooks instead ran once per configuration file
+rather than once per repository.)
 
 There are additional hooks that run before/after other actions as well. For
-instance, `before_prune` runs before a `prune` action, while `after_prune`
-runs after it.
+instance, `before_prune` runs before a `prune` action for a repository, while
+`after_prune` runs after it.
+
+## Variable interpolation
+
+The before and after action hooks support interpolating particular runtime
+variables into the hook command. Here's an example that assumes you provide a
+separate shell script:
+
+```yaml
+hooks:
+    after_prune:
+        - record-prune.sh "{configuration_filename}" "{repository}"
+```
+
+In this example, when the hook is triggered, borgmatic interpolates runtime
+values into the hook command: the borgmatic configuration filename and the
+paths of the current Borg repository. Here's the full set of supported
+variables you can use here:
+
+ * `configuration_filename`: borgmatic configuration filename in which the
+   hook was defined
+ * `repository`: path of the current repository as configured in the current
+   borgmatic configuration file
+
+## Global hooks
 
 You can also use `before_everything` and `after_everything` hooks to perform
 global setup or cleanup:
@@ -58,6 +84,8 @@ but only if there is a `create` action. It runs even if an error occurs during
 a backup or a backup hook, but not if an error occurs during a
 `before_everything` hook.
 
+## Error hooks
+
 borgmatic also runs `on_error` hooks if an error occurs, either when creating
 a backup or running a backup hook. See the [monitoring and alerting
 documentation](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/)

docs/how-to/backup-to-a-removable-drive-or-an-intermittent-server.md

@@ -1,7 +1,7 @@
 ---
 title: How to backup to a removable drive or an intermittent server
 eleventyNavigation:
-  key: Backup to a removable drive or server
+  key: 💾 Backup to a removable drive/server
   parent: How-to guides
   order: 9
 ---

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

@@ -1,7 +1,7 @@
 ---
 title: How to backup your databases
 eleventyNavigation:
-  key: Backup your databases
+  key: 🗄️ Backup your databases
   parent: How-to guides
   order: 7
 ---
@@ -33,7 +33,8 @@ As part of each backup, borgmatic streams a database dump for each configured
 database directly to Borg, so it's included in the backup without consuming
 additional disk space. (The exceptions are the PostgreSQL/MongoDB "directory"
 dump formats, which can't stream and therefore do consume temporary disk
-space.)
+space. Additionally, prior to borgmatic 1.5.3, all database dumps consumed
+temporary disk space.)
 
 To support this, borgmatic creates temporary named pipes in `~/.borgmatic` by
 default. To customize this path, set the `borgmatic_source_directory` option
@@ -199,19 +200,26 @@ backups to avoid getting caught without a way to restore a database.
 databases that share the exact same name on different hosts.
 4. Because database hooks implicitly enable the `read_special` configuration
 setting to support dump and restore streaming, you'll need to ensure that any
-special files are excluded from backups (named pipes, block devices, and
-character devices) to prevent hanging. Try a command like `find / -type c,b,p`
-to find such files. Common directories to exclude are `/dev` and `/run`, but
-that may not be exhaustive.
+special files are excluded from backups (named pipes, block devices,
+character devices, and sockets) to prevent hanging. Try a command like
+`find /your/source/path -type c,b,p,s` to find such files. Common directories
+to exclude are `/dev` and `/run`, but that may not be exhaustive.
 
 
 ### Manual restoration
 
 If you prefer to restore a database without the help of borgmatic, first
 [extract](https://torsion.org/borgmatic/docs/how-to/extract-a-backup/) an
-archive containing a database dump, and then manually restore the dump file
-found within the extracted `~/.borgmatic/` path (e.g. with `pg_restore`,
-`mysql`, or `mongorestore`, commands).
+archive containing a database dump.
+
+borgmatic extracts the dump file into the *`username`*`/.borgmatic/` directory
+within the extraction destination path, where *`username`* is the user that
+created the backup. For example, if you created the backup with the `root`
+user and you're extracting to `/tmp`, then the dump will be in
+`/tmp/root/.borgmatic`.
+
+After extraction, you can manually restore the dump file using native database
+commands like `pg_restore`, `mysql`, `mongorestore` or similar.
 
 
 ## Preparation and cleanup hooks
@@ -244,5 +252,10 @@ hooks:
 ### borgmatic hangs during backup
 
 See Limitations above about `read_special`. You may need to exclude certain
-paths with named pipes, block devices, or character devices on which borgmatic
-is hanging.
+paths with named pipes, block devices, character devices, or sockets on which
+borgmatic is hanging.
+
+Alternatively, if excluding special files is too onerous, you can create two
+separate borgmatic configuration files—one for your source files and a
+separate one for backing up databases. That way, the database `read_special`
+option will not be active when backing up special files.

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

@@ -1,7 +1,7 @@
 ---
 title: How to deal with very large backups
 eleventyNavigation:
-  key: Deal with very large backups
+  key: 📏 Deal with very large backups
   parent: How-to guides
   order: 3
 ---

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

@@ -1,7 +1,7 @@
 ---
 title: How to develop on borgmatic
 eleventyNavigation:
-  key: Develop on borgmatic
+  key: 🏗️ Develop on borgmatic
   parent: How-to guides
   order: 12
 ---

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

@@ -1,7 +1,7 @@
 ---
 title: How to extract a backup
 eleventyNavigation:
-  key: Extract a backup
+  key: 📤 Extract a backup
   parent: How-to guides
   order: 6
 ---

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

@@ -1,7 +1,7 @@
 ---
 title: How to inspect your backups
 eleventyNavigation:
-  key: Inspect your backups
+  key: 🔎 Inspect your backups
   parent: How-to guides
   order: 4
 ---

docs/how-to/make-backups-redundant.md

@@ -1,7 +1,7 @@
 ---
 title: How to make backups redundant
 eleventyNavigation:
-  key: Make backups redundant
+  key: ☁️  Make backups redundant
   parent: How-to guides
   order: 2
 ---

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

@@ -1,7 +1,7 @@
 ---
 title: How to make per-application backups
 eleventyNavigation:
-  key: Make per-application backups
+  key: 🔀 Make per-application backups
   parent: How-to guides
   order: 1
 ---
@@ -32,10 +32,16 @@ perform any merging of configuration files by default. If you'd like borgmatic
 to merge your configuration files, see below about configuration includes.
 
 Additionally, the `~/.config/borgmatic.d/` directory works the same way as
-`/etc/borgmatic.d`. If you need even more customizability, you can specify
-alternate configuration paths on the command-line with borgmatic's `--config`
-flag. See `borgmatic --help` for more information.
+`/etc/borgmatic.d`.
 
+If you need even more customizability, you can specify alternate configuration
+paths on the command-line with borgmatic's `--config` flag. (See `borgmatic
+--help` for more information.) For instance, if you want to schedule your
+various borgmatic backups to run at different times, you'll need multiple
+entries in your [scheduling software of
+choice](https://torsion.org/borgmatic/docs/how-to/set-up-backups/#autopilot),
+each entry using borgmatic's `--config` flag instead of relying on
+`/etc/borgmatic.d`.
 
 ## Configuration includes
 
@@ -69,6 +75,10 @@ themselves and complaining that they are not valid configuration files, you
 should put them in a directory other than `/etc/borgmatic.d/`. (A subdirectory
 is fine.)
 
+When a configuration include is a relative path, borgmatic loads it from either
+the current working directory or from the directory containing the file doing
+the including.
+
 Note that this form of include must be a YAML value rather than a key. For
 example, this will not work:
 
@@ -80,7 +90,7 @@ location:
 !include /etc/borgmatic/common_retention.yaml
 ```
 
-But if you do want to merge in a YAML key and its values, keep reading!
+But if you do want to merge in a YAML key *and* its values, keep reading!
 
 
 ## Include merging
@@ -89,35 +99,39 @@ If you need to get even fancier and pull in common configuration options while
 potentially overriding individual options, you can perform a YAML merge of
 included configuration using the YAML `<<` key. For instance, here's an
 example of a main configuration file that pulls in two retention options via
-an include, and then overrides one of them locally:
+an include and then overrides one of them locally:
 
 ```yaml
+<<: !include /etc/borgmatic/common.yaml
+
 location:
    ...
 
 retention:
     keep_daily: 5
-    <<: !include /etc/borgmatic/common_retention.yaml
 ```
 
-This is what `common_retention.yaml` might look like:
+This is what `common.yaml` might look like:
 
 ```yaml
-keep_hourly: 24
-keep_daily: 7
+retention:
+    keep_hourly: 24
+    keep_daily: 7
 ```
 
 Once this include gets merged in, the resulting configuration would have a
 `keep_hourly` value of `24` and an overridden `keep_daily` value of `5`.
 
-When there is a collision of an option between the local file and the merged
-include, the local file's option takes precedent. And note that this is a
-shallow merge rather than a deep merge, so the merging does not descend into
-nested values.
+When there's an option collision between the local file and the merged
+include, the local file's option takes precedence. And as of borgmatic 1.6.0,
+this feature performs a deep merge, meaning that values are merged at all
+levels in the two configuration files. Colliding list values are appended
+together. This allows you to include common configuration—up to full borgmatic
+configuration files—while overriding only the parts you want to customize.
 
 Note that this `<<` include merging syntax is only for merging in mappings
-(keys/values). If you'd like to include other types like scalars or lists
-directly, please see the section above about standard includes.
+(configuration options and their values). But if you'd like to include a
+single value directly, please see the section above about standard includes.
 
 
 ## Configuration overrides
@@ -162,7 +176,14 @@ borgmatic create --override location.repositories=[test1.borg,test2.borg]
 Or even a single list element:
 
 ```bash
-borgmatic create --override location.repositories=[/root/test1.borg]
+borgmatic create --override location.repositories=[/root/test.borg]
+```
+
+If your override value contains special YAML characters like colons, then
+you'll need quotes for it to parse correctly:
+
+```bash
+borgmatic create --override location.repositories="['user@server:test.borg']"
 ```
 
 There is not currently a way to override a single element of a list without

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

@@ -1,7 +1,7 @@
 ---
 title: How to monitor your backups
 eleventyNavigation:
-  key: Monitor your backups
+  key: 🚨 Monitor your backups
   parent: How-to guides
   order: 5
 ---
@@ -104,10 +104,9 @@ hooks:
         - send-text-message.sh "{configuration_filename}" "{repository}"
 ```
 
-In this example, when the error occurs, borgmatic interpolates a few runtime
-values into the hook command: the borgmatic configuration filename, and the
-path of the repository. Here's the full set of supported variables you can use
-here:
+In this example, when the error occurs, borgmatic interpolates runtime values
+into the hook command: the borgmatic configuration filename, and the path of
+the repository. Here's the full set of supported variables you can use here:
 
  * `configuration_filename`: borgmatic configuration filename in which the
    error occurred
@@ -137,7 +136,8 @@ URL" for your project. Here's an example:
 
 ```yaml
 hooks:
-    healthchecks: https://hc-ping.com/addffa72-da17-40ae-be9c-ff591afb942a
+    healthchecks:
+        ping_url: https://hc-ping.com/addffa72-da17-40ae-be9c-ff591afb942a
 ```
 
 With this hook in place, borgmatic pings your Healthchecks project when a
@@ -159,7 +159,10 @@ itself. But the logs are only included for errors that occur when a `prune`,
 
 You can customize the verbosity of the logs that are sent to Healthchecks with
 borgmatic's `--monitoring-verbosity` flag. The `--files` and `--stats` flags
-may also be of use. See `borgmatic --help` for more information.
+may also be of use. See `borgmatic --help` for more information. Additionally,
+see the [borgmatic configuration
+file](https://torsion.org/borgmatic/docs/reference/configuration/) for
+additional Healthchecks options.
 
 You can configure Healthchecks to notify you by a [variety of
 mechanisms](https://healthchecks.io/#welcome-integrations) when backups fail
@@ -177,7 +180,8 @@ API URL" for your monitor. Here's an example:
 
 ```yaml
 hooks:
-    cronitor: https://cronitor.link/d3x0c1
+    cronitor:
+        ping_url: https://cronitor.link/d3x0c1
 ```
 
 With this hook in place, borgmatic pings your Cronitor monitor when a backup
@@ -205,7 +209,8 @@ URL" for your monitor. Here's an example:
 
 ```yaml
 hooks:
-    cronhub: https://cronhub.io/start/1f5e3410-254c-11e8-b61d-55875966d031
+    cronhub:
+        ping_url: https://cronhub.io/start/1f5e3410-254c-11e8-b61d-55875966d031
 ```
 
 With this hook in place, borgmatic pings your Cronhub monitor when a backup
@@ -247,7 +252,8 @@ Here's an example:
 
 ```yaml
 hooks:
-    pagerduty: a177cad45bd374409f78906a810a3074
+    pagerduty:
+        integration_key: a177cad45bd374409f78906a810a3074
 ```
 
 With this hook in place, borgmatic creates a PagerDuty event for your service

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

@@ -1,7 +1,7 @@
 ---
 title: How to run arbitrary Borg commands
 eleventyNavigation:
-  key: Run arbitrary Borg commands
+  key: 🔧 Run arbitrary Borg commands
   parent: How-to guides
   order: 10
 ---

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

@@ -1,7 +1,7 @@
 ---
 title: How to set up backups
 eleventyNavigation:
-  key: Set up backups
+  key: 📥 Set up backups
   parent: How-to guides
   order: 0
 ---
@@ -28,7 +28,7 @@ sudo pip3 install --user --upgrade borgmatic
 This installs borgmatic and its commands at the `/root/.local/bin` path.
 
 Your pip binary may have a different name than "pip3". Make sure you're using
-Python 3.6+, as borgmatic does not support Python 2.
+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:
@@ -51,6 +51,11 @@ sudo 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.
+
 
 ### Global install option
 
@@ -78,7 +83,7 @@ Besides the approaches described above, there are several other options for
 installing borgmatic:
 
  * [Docker image with scheduled backups](https://hub.docker.com/r/b3vis/borgmatic/) (+ Docker Compose files)
- * [Docker base image](https://hub.docker.com/r/monachus/borgmatic/)
+ * [Docker image with multi-arch and Docker CLI support](https://hub.docker.com/r/modem7/borgmatic-docker/)
  * [Debian](https://tracker.debian.org/pkg/borgmatic)
  * [Ubuntu](https://launchpad.net/ubuntu/+source/borgmatic)
  * [Fedora official](https://bodhi.fedoraproject.org/updates/?search=borgmatic)
@@ -88,7 +93,6 @@ installing borgmatic:
  * [OpenBSD](http://ports.su/sysutils/borgmatic)
  * [openSUSE](https://software.opensuse.org/package/borgmatic)
  * [Ansible role](https://github.com/borgbase/ansible-role-borgbackup)
- * [stand-alone binary](https://github.com/cmarquardt/borgmatic-binary)
  * [virtualenv](https://virtualenv.pypa.io/en/stable/)
 
 

docs/how-to/upgrade.md

@@ -1,7 +1,7 @@
 ---
 title: How to upgrade borgmatic
 eleventyNavigation:
-  key: Upgrade borgmatic
+  key: 📦 Upgrade borgmatic
   parent: How-to guides
   order: 11
 ---

docs/reference/command-line.md

@@ -1,7 +1,7 @@
 ---
 title: Command-line reference
 eleventyNavigation:
-  key: Command-line reference
+  key: ⌨️ Command-line reference
   parent: Reference guides
   order: 1
 ---

docs/reference/configuration.md

@@ -1,7 +1,7 @@
 ---
 title: Configuration reference
 eleventyNavigation:
-  key: Configuration reference
+  key: ⚙️ Configuration reference
   parent: Reference guides
   order: 0
 ---

sample/systemd/borgmatic.timer

@@ -4,6 +4,7 @@ Description=Run borgmatic backup
 [Timer]
 OnCalendar=daily
 Persistent=true
+RandomizedDelaySec=3h
 
 [Install]
 WantedBy=timers.target

scripts/release

@@ -31,8 +31,8 @@ python3 setup.py bdist_wheel
 python3 setup.py sdist
 gpg --detach-sign --armor dist/borgmatic-*.tar.gz
 gpg --detach-sign --armor dist/borgmatic-*-py3-none-any.whl
-twine upload -r pypi dist/borgmatic-*.tar.gz dist/borgmatic-*.tar.gz.asc
-twine upload -r pypi dist/borgmatic-*-py3-none-any.whl dist/borgmatic-*-py3-none-any.whl.asc
+twine upload -r pypi --username __token__ dist/borgmatic-*.tar.gz dist/borgmatic-*.tar.gz.asc
+twine upload -r pypi --username __token__ dist/borgmatic-*-py3-none-any.whl dist/borgmatic-*-py3-none-any.whl.asc
 
 # Set release changelogs on projects.torsion.org and GitHub.
 release_changelog="$(cat NEWS | sed '/^$/q' | grep -v '^\S')"

setup.py

@@ -1,6 +1,6 @@
 from setuptools import find_packages, setup
 
-VERSION = '1.5.23'
+VERSION = '1.6.1'
 
 
 setup(

tests/integration/config/test_load.py

@@ -1,3 +1,4 @@
+import io
 import sys
 
 import pytest
@@ -14,49 +15,360 @@ def test_load_configuration_parses_contents():
     assert module.load_configuration('config.yaml') == {'key': 'value'}
 
 
-def test_load_configuration_inlines_include():
+def test_load_configuration_inlines_include_relative_to_current_directory():
     builtins = flexmock(sys.modules['builtins'])
-    builtins.should_receive('open').with_args('include.yaml').and_return('value')
-    builtins.should_receive('open').with_args('config.yaml').and_return(
-        'key: !include include.yaml'
-    )
+    flexmock(module.os).should_receive('getcwd').and_return('/tmp')
+    flexmock(module.os.path).should_receive('isabs').and_return(False)
+    flexmock(module.os.path).should_receive('exists').and_return(True)
+    include_file = io.StringIO('value')
+    include_file.name = 'include.yaml'
+    builtins.should_receive('open').with_args('/tmp/include.yaml').and_return(include_file)
+    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)
 
     assert module.load_configuration('config.yaml') == {'key': 'value'}
 
 
+def test_load_configuration_inlines_include_relative_to_config_parent_directory():
+    builtins = flexmock(sys.modules['builtins'])
+    flexmock(module.os).should_receive('getcwd').and_return('/tmp')
+    flexmock(module.os.path).should_receive('isabs').with_args('/etc').and_return(True)
+    flexmock(module.os.path).should_receive('isabs').with_args('/etc/config.yaml').and_return(True)
+    flexmock(module.os.path).should_receive('isabs').with_args('include.yaml').and_return(False)
+    flexmock(module.os.path).should_receive('exists').with_args('/tmp/include.yaml').and_return(
+        False
+    )
+    flexmock(module.os.path).should_receive('exists').with_args('/etc/include.yaml').and_return(
+        True
+    )
+    include_file = io.StringIO('value')
+    include_file.name = 'include.yaml'
+    builtins.should_receive('open').with_args('/etc/include.yaml').and_return(include_file)
+    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)
+
+    assert module.load_configuration('/etc/config.yaml') == {'key': 'value'}
+
+
+def test_load_configuration_raises_if_relative_include_does_not_exist():
+    builtins = flexmock(sys.modules['builtins'])
+    flexmock(module.os).should_receive('getcwd').and_return('/tmp')
+    flexmock(module.os.path).should_receive('isabs').with_args('/etc').and_return(True)
+    flexmock(module.os.path).should_receive('isabs').with_args('/etc/config.yaml').and_return(True)
+    flexmock(module.os.path).should_receive('isabs').with_args('include.yaml').and_return(False)
+    flexmock(module.os.path).should_receive('exists').and_return(False)
+    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)
+
+    with pytest.raises(FileNotFoundError):
+        module.load_configuration('/etc/config.yaml')
+
+
+def test_load_configuration_inlines_absolute_include():
+    builtins = flexmock(sys.modules['builtins'])
+    flexmock(module.os).should_receive('getcwd').and_return('/tmp')
+    flexmock(module.os.path).should_receive('isabs').and_return(True)
+    flexmock(module.os.path).should_receive('exists').never()
+    include_file = io.StringIO('value')
+    include_file.name = '/root/include.yaml'
+    builtins.should_receive('open').with_args('/root/include.yaml').and_return(include_file)
+    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)
+
+    assert module.load_configuration('config.yaml') == {'key': 'value'}
+
+
+def test_load_configuration_raises_if_absolute_include_does_not_exist():
+    builtins = flexmock(sys.modules['builtins'])
+    flexmock(module.os).should_receive('getcwd').and_return('/tmp')
+    flexmock(module.os.path).should_receive('isabs').and_return(True)
+    builtins.should_receive('open').with_args('/root/include.yaml').and_raise(FileNotFoundError)
+    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)
+
+    with pytest.raises(FileNotFoundError):
+        assert module.load_configuration('config.yaml')
+
+
 def test_load_configuration_merges_include():
     builtins = flexmock(sys.modules['builtins'])
-    builtins.should_receive('open').with_args('include.yaml').and_return(
+    flexmock(module.os).should_receive('getcwd').and_return('/tmp')
+    flexmock(module.os.path).should_receive('isabs').and_return(False)
+    flexmock(module.os.path).should_receive('exists').and_return(True)
+    include_file = io.StringIO(
         '''
         foo: bar
         baz: quux
         '''
     )
-    builtins.should_receive('open').with_args('config.yaml').and_return(
+    include_file.name = 'include.yaml'
+    builtins.should_receive('open').with_args('/tmp/include.yaml').and_return(include_file)
+    config_file = io.StringIO(
         '''
         foo: override
         <<: !include include.yaml
         '''
     )
+    config_file.name = 'config.yaml'
+    builtins.should_receive('open').with_args('config.yaml').and_return(config_file)
 
     assert module.load_configuration('config.yaml') == {'foo': 'override', 'baz': 'quux'}
 
 
 def test_load_configuration_does_not_merge_include_list():
     builtins = flexmock(sys.modules['builtins'])
-    builtins.should_receive('open').with_args('include.yaml').and_return(
+    flexmock(module.os).should_receive('getcwd').and_return('/tmp')
+    flexmock(module.os.path).should_receive('isabs').and_return(False)
+    flexmock(module.os.path).should_receive('exists').and_return(True)
+    include_file = io.StringIO(
         '''
           - one
           - two
         '''
     )
-    builtins.should_receive('open').with_args('config.yaml').and_return(
+    include_file.name = 'include.yaml'
+    builtins.should_receive('open').with_args('/tmp/include.yaml').and_return(include_file)
+    config_file = io.StringIO(
         '''
         foo: bar
         repositories:
           <<: !include include.yaml
         '''
     )
+    config_file.name = 'config.yaml'
+    builtins.should_receive('open').with_args('config.yaml').and_return(config_file)
 
     with pytest.raises(ruamel.yaml.error.YAMLError):
         assert module.load_configuration('config.yaml')
+
+
+def test_deep_merge_nodes_replaces_colliding_scalar_values():
+    node_values = [
+        (
+            ruamel.yaml.nodes.ScalarNode(tag='tag:yaml.org,2002:str', value='retention'),
+            ruamel.yaml.nodes.MappingNode(
+                tag='tag:yaml.org,2002:map',
+                value=[
+                    (
+                        ruamel.yaml.nodes.ScalarNode(
+                            tag='tag:yaml.org,2002:str', value='keep_hourly'
+                        ),
+                        ruamel.yaml.nodes.ScalarNode(tag='tag:yaml.org,2002:int', value='24'),
+                    ),
+                    (
+                        ruamel.yaml.nodes.ScalarNode(
+                            tag='tag:yaml.org,2002:str', value='keep_daily'
+                        ),
+                        ruamel.yaml.nodes.ScalarNode(tag='tag:yaml.org,2002:int', value='7'),
+                    ),
+                ],
+            ),
+        ),
+        (
+            ruamel.yaml.nodes.ScalarNode(tag='tag:yaml.org,2002:str', value='retention'),
+            ruamel.yaml.nodes.MappingNode(
+                tag='tag:yaml.org,2002:map',
+                value=[
+                    (
+                        ruamel.yaml.nodes.ScalarNode(
+                            tag='tag:yaml.org,2002:str', value='keep_daily'
+                        ),
+                        ruamel.yaml.nodes.ScalarNode(tag='tag:yaml.org,2002:int', value='5'),
+                    ),
+                ],
+            ),
+        ),
+    ]
+
+    result = module.deep_merge_nodes(node_values)
+    assert len(result) == 1
+    (section_key, section_value) = result[0]
+    assert section_key.value == 'retention'
+    options = section_value.value
+    assert len(options) == 2
+    assert options[0][0].value == 'keep_hourly'
+    assert options[0][1].value == '24'
+    assert options[1][0].value == 'keep_daily'
+    assert options[1][1].value == '5'
+
+
+def test_deep_merge_nodes_keeps_non_colliding_scalar_values():
+    node_values = [
+        (
+            ruamel.yaml.nodes.ScalarNode(tag='tag:yaml.org,2002:str', value='retention'),
+            ruamel.yaml.nodes.MappingNode(
+                tag='tag:yaml.org,2002:map',
+                value=[
+                    (
+                        ruamel.yaml.nodes.ScalarNode(
+                            tag='tag:yaml.org,2002:str', value='keep_hourly'
+                        ),
+                        ruamel.yaml.nodes.ScalarNode(tag='tag:yaml.org,2002:int', value='24'),
+                    ),
+                    (
+                        ruamel.yaml.nodes.ScalarNode(
+                            tag='tag:yaml.org,2002:str', value='keep_daily'
+                        ),
+                        ruamel.yaml.nodes.ScalarNode(tag='tag:yaml.org,2002:int', value='7'),
+                    ),
+                ],
+            ),
+        ),
+        (
+            ruamel.yaml.nodes.ScalarNode(tag='tag:yaml.org,2002:str', value='retention'),
+            ruamel.yaml.nodes.MappingNode(
+                tag='tag:yaml.org,2002:map',
+                value=[
+                    (
+                        ruamel.yaml.nodes.ScalarNode(
+                            tag='tag:yaml.org,2002:str', value='keep_minutely'
+                        ),
+                        ruamel.yaml.nodes.ScalarNode(tag='tag:yaml.org,2002:int', value='10'),
+                    ),
+                ],
+            ),
+        ),
+    ]
+
+    result = module.deep_merge_nodes(node_values)
+    assert len(result) == 1
+    (section_key, section_value) = result[0]
+    assert section_key.value == 'retention'
+    options = section_value.value
+    assert len(options) == 3
+    assert options[0][0].value == 'keep_hourly'
+    assert options[0][1].value == '24'
+    assert options[1][0].value == 'keep_daily'
+    assert options[1][1].value == '7'
+    assert options[2][0].value == 'keep_minutely'
+    assert options[2][1].value == '10'
+
+
+def test_deep_merge_nodes_keeps_deeply_nested_values():
+    node_values = [
+        (
+            ruamel.yaml.nodes.ScalarNode(tag='tag:yaml.org,2002:str', value='storage'),
+            ruamel.yaml.nodes.MappingNode(
+                tag='tag:yaml.org,2002:map',
+                value=[
+                    (
+                        ruamel.yaml.nodes.ScalarNode(
+                            tag='tag:yaml.org,2002:str', value='lock_wait'
+                        ),
+                        ruamel.yaml.nodes.ScalarNode(tag='tag:yaml.org,2002:int', value='5'),
+                    ),
+                    (
+                        ruamel.yaml.nodes.ScalarNode(
+                            tag='tag:yaml.org,2002:str', value='extra_borg_options'
+                        ),
+                        ruamel.yaml.nodes.MappingNode(
+                            tag='tag:yaml.org,2002:map',
+                            value=[
+                                (
+                                    ruamel.yaml.nodes.ScalarNode(
+                                        tag='tag:yaml.org,2002:str', value='init'
+                                    ),
+                                    ruamel.yaml.nodes.ScalarNode(
+                                        tag='tag:yaml.org,2002:str', value='--init-option'
+                                    ),
+                                ),
+                            ],
+                        ),
+                    ),
+                ],
+            ),
+        ),
+        (
+            ruamel.yaml.nodes.ScalarNode(tag='tag:yaml.org,2002:str', value='storage'),
+            ruamel.yaml.nodes.MappingNode(
+                tag='tag:yaml.org,2002:map',
+                value=[
+                    (
+                        ruamel.yaml.nodes.ScalarNode(
+                            tag='tag:yaml.org,2002:str', value='extra_borg_options'
+                        ),
+                        ruamel.yaml.nodes.MappingNode(
+                            tag='tag:yaml.org,2002:map',
+                            value=[
+                                (
+                                    ruamel.yaml.nodes.ScalarNode(
+                                        tag='tag:yaml.org,2002:str', value='prune'
+                                    ),
+                                    ruamel.yaml.nodes.ScalarNode(
+                                        tag='tag:yaml.org,2002:str', value='--prune-option'
+                                    ),
+                                ),
+                            ],
+                        ),
+                    ),
+                ],
+            ),
+        ),
+    ]
+
+    result = module.deep_merge_nodes(node_values)
+    assert len(result) == 1
+    (section_key, section_value) = result[0]
+    assert section_key.value == 'storage'
+    options = section_value.value
+    assert len(options) == 2
+    assert options[0][0].value == 'lock_wait'
+    assert options[0][1].value == '5'
+    assert options[1][0].value == 'extra_borg_options'
+    nested_options = options[1][1].value
+    assert len(nested_options) == 2
+    assert nested_options[0][0].value == 'init'
+    assert nested_options[0][1].value == '--init-option'
+    assert nested_options[1][0].value == 'prune'
+    assert nested_options[1][1].value == '--prune-option'
+
+
+def test_deep_merge_nodes_appends_colliding_sequence_values():
+    node_values = [
+        (
+            ruamel.yaml.nodes.ScalarNode(tag='tag:yaml.org,2002:str', value='hooks'),
+            ruamel.yaml.nodes.MappingNode(
+                tag='tag:yaml.org,2002:map',
+                value=[
+                    (
+                        ruamel.yaml.nodes.ScalarNode(
+                            tag='tag:yaml.org,2002:str', value='before_backup'
+                        ),
+                        ruamel.yaml.nodes.SequenceNode(
+                            tag='tag:yaml.org,2002:int', value=['echo 1', 'echo 2']
+                        ),
+                    ),
+                ],
+            ),
+        ),
+        (
+            ruamel.yaml.nodes.ScalarNode(tag='tag:yaml.org,2002:str', value='hooks'),
+            ruamel.yaml.nodes.MappingNode(
+                tag='tag:yaml.org,2002:map',
+                value=[
+                    (
+                        ruamel.yaml.nodes.ScalarNode(
+                            tag='tag:yaml.org,2002:str', value='before_backup'
+                        ),
+                        ruamel.yaml.nodes.SequenceNode(
+                            tag='tag:yaml.org,2002:int', value=['echo 3', 'echo 4']
+                        ),
+                    ),
+                ],
+            ),
+        ),
+    ]
+
+    result = module.deep_merge_nodes(node_values)
+    assert len(result) == 1
+    (section_key, section_value) = result[0]
+    assert section_key.value == 'hooks'
+    options = section_value.value
+    assert len(options) == 1
+    assert options[0][0].value == 'before_backup'
+    assert options[0][1].value == ['echo 1', 'echo 2', 'echo 3', 'echo 4']

tests/integration/config/test_validate.py

@@ -21,14 +21,20 @@ def mock_config_and_schema(config_yaml, schema_yaml=None):
     when parsing the configuration.
     '''
     config_stream = io.StringIO(config_yaml)
+    config_stream.name = 'config.yaml'
+
     if schema_yaml is None:
         schema_stream = open(module.schema_filename())
     else:
         schema_stream = io.StringIO(schema_yaml)
+        schema_stream.name = 'schema.yaml'
 
     builtins = flexmock(sys.modules['builtins'])
-    builtins.should_receive('open').with_args('config.yaml').and_return(config_stream)
-    builtins.should_receive('open').with_args('schema.yaml').and_return(schema_stream)
+    flexmock(module.os).should_receive('getcwd').and_return('/tmp')
+    flexmock(module.os.path).should_receive('isabs').and_return(False)
+    flexmock(module.os.path).should_receive('exists').and_return(True)
+    builtins.should_receive('open').with_args('/tmp/config.yaml').and_return(config_stream)
+    builtins.should_receive('open').with_args('/tmp/schema.yaml').and_return(schema_stream)
 
 
 def test_parse_configuration_transforms_file_into_mapping():
@@ -54,7 +60,7 @@ def test_parse_configuration_transforms_file_into_mapping():
         '''
     )
 
-    result = module.parse_configuration('config.yaml', 'schema.yaml')
+    result = module.parse_configuration('/tmp/config.yaml', '/tmp/schema.yaml')
 
     assert result == {
         'location': {'source_directories': ['/home', '/etc'], 'repositories': ['hostname.borg']},
@@ -79,7 +85,7 @@ def test_parse_configuration_passes_through_quoted_punctuation():
         )
     )
 
-    result = module.parse_configuration('config.yaml', 'schema.yaml')
+    result = module.parse_configuration('/tmp/config.yaml', '/tmp/schema.yaml')
 
     assert result == {
         'location': {
@@ -115,7 +121,7 @@ def test_parse_configuration_with_schema_lacking_examples_does_not_raise():
         ''',
     )
 
-    module.parse_configuration('config.yaml', 'schema.yaml')
+    module.parse_configuration('/tmp/config.yaml', '/tmp/schema.yaml')
 
 
 def test_parse_configuration_inlines_include():
@@ -133,14 +139,16 @@ def test_parse_configuration_inlines_include():
         '''
     )
     builtins = flexmock(sys.modules['builtins'])
-    builtins.should_receive('open').with_args('include.yaml').and_return(
+    include_file = io.StringIO(
         '''
         keep_daily: 7
         keep_hourly: 24
         '''
     )
+    include_file.name = 'include.yaml'
+    builtins.should_receive('open').with_args('/tmp/include.yaml').and_return(include_file)
 
-    result = module.parse_configuration('config.yaml', 'schema.yaml')
+    result = module.parse_configuration('/tmp/config.yaml', '/tmp/schema.yaml')
 
     assert result == {
         'location': {'source_directories': ['/home'], 'repositories': ['hostname.borg']},
@@ -164,14 +172,16 @@ def test_parse_configuration_merges_include():
         '''
     )
     builtins = flexmock(sys.modules['builtins'])
-    builtins.should_receive('open').with_args('include.yaml').and_return(
+    include_file = io.StringIO(
         '''
         keep_daily: 7
         keep_hourly: 24
         '''
     )
+    include_file.name = 'include.yaml'
+    builtins.should_receive('open').with_args('/tmp/include.yaml').and_return(include_file)
 
-    result = module.parse_configuration('config.yaml', 'schema.yaml')
+    result = module.parse_configuration('/tmp/config.yaml', '/tmp/schema.yaml')
 
     assert result == {
         'location': {'source_directories': ['/home'], 'repositories': ['hostname.borg']},
@@ -181,23 +191,23 @@ def test_parse_configuration_merges_include():
 
 def test_parse_configuration_raises_for_missing_config_file():
     with pytest.raises(FileNotFoundError):
-        module.parse_configuration('config.yaml', 'schema.yaml')
+        module.parse_configuration('/tmp/config.yaml', '/tmp/schema.yaml')
 
 
 def test_parse_configuration_raises_for_missing_schema_file():
     mock_config_and_schema('')
     builtins = flexmock(sys.modules['builtins'])
-    builtins.should_receive('open').with_args('schema.yaml').and_raise(FileNotFoundError)
+    builtins.should_receive('open').with_args('/tmp/schema.yaml').and_raise(FileNotFoundError)
 
     with pytest.raises(FileNotFoundError):
-        module.parse_configuration('config.yaml', 'schema.yaml')
+        module.parse_configuration('/tmp/config.yaml', '/tmp/schema.yaml')
 
 
 def test_parse_configuration_raises_for_syntax_error():
     mock_config_and_schema('foo:\nbar')
 
     with pytest.raises(ValueError):
-        module.parse_configuration('config.yaml', 'schema.yaml')
+        module.parse_configuration('/tmp/config.yaml', '/tmp/schema.yaml')
 
 
 def test_parse_configuration_raises_for_validation_error():
@@ -211,7 +221,7 @@ def test_parse_configuration_raises_for_validation_error():
     )
 
     with pytest.raises(module.Validation_error):
-        module.parse_configuration('config.yaml', 'schema.yaml')
+        module.parse_configuration('/tmp/config.yaml', '/tmp/schema.yaml')
 
 
 def test_parse_configuration_applies_overrides():
@@ -229,7 +239,7 @@ def test_parse_configuration_applies_overrides():
     )
 
     result = module.parse_configuration(
-        'config.yaml', 'schema.yaml', overrides=['location.local_path=borg2']
+        '/tmp/config.yaml', '/tmp/schema.yaml', overrides=['location.local_path=borg2']
     )
 
     assert result == {
@@ -255,7 +265,7 @@ def test_parse_configuration_applies_normalization():
         '''
     )
 
-    result = module.parse_configuration('config.yaml', 'schema.yaml')
+    result = module.parse_configuration('/tmp/config.yaml', '/tmp/schema.yaml')
 
     assert result == {
         'location': {

tests/unit/borg/test_borg.py

@@ -121,3 +121,13 @@ def test_run_arbitrary_borg_without_borg_specific_parameters_does_not_raise():
     module.run_arbitrary_borg(
         repository='repo', storage_config={}, options=[],
     )
+
+
+def test_run_arbitrary_borg_passes_key_sub_command_to_borg_before_repository():
+    flexmock(module).should_receive('execute_command').with_args(
+        ('borg', 'key', 'export', 'repo'), output_log_level=logging.WARNING, borg_local_path='borg',
+    )
+
+    module.run_arbitrary_borg(
+        repository='repo', storage_config={}, options=['key', 'export'],
+    )

tests/unit/borg/test_compact.py

@@ -36,8 +36,8 @@ def test_compact_segments_with_log_debug_calls_borg_with_debug_parameter():
     module.compact_segments(repository='repo', storage_config={}, dry_run=False)
 
 
-def test_compact_segments_with_dry_run_calls_borg_with_dry_run_parameter():
-    insert_execute_command_mock(COMPACT_COMMAND + ('--dry-run', 'repo'), logging.INFO)
+def test_compact_segments_with_dry_run_skips_borg_call():
+    flexmock(module).should_receive('execute_command').never()
 
     module.compact_segments(repository='repo', storage_config={}, dry_run=True)
 

tests/unit/commands/test_borgmatic.py

@@ -35,99 +35,14 @@ def test_run_configuration_with_invalid_borg_version_errors():
     list(module.run_configuration('test.yaml', config, arguments))
 
 
-def test_run_configuration_calls_hooks_for_prune_action():
+def test_run_configuration_logs_monitor_start_error():
     flexmock(module.borg_environment).should_receive('initialize')
     flexmock(module.borg_version).should_receive('local_borg_version').and_return(flexmock())
-    flexmock(module.command).should_receive('execute_hook').twice()
-    flexmock(module.dispatch).should_receive('call_hooks').at_least().twice()
-    flexmock(module).should_receive('run_actions').and_return([])
-    config = {'location': {'repositories': ['foo']}}
-    arguments = {'global': flexmock(monitoring_verbosity=1, dry_run=False), 'prune': flexmock()}
-
-    list(module.run_configuration('test.yaml', config, arguments))
-
-
-def test_run_configuration_calls_hooks_for_compact_action():
-    flexmock(module.borg_environment).should_receive('initialize')
-    flexmock(module.borg_version).should_receive('local_borg_version').and_return(flexmock())
-    flexmock(module.command).should_receive('execute_hook').twice()
-    flexmock(module).should_receive('run_actions').and_return([])
-    config = {'location': {'repositories': ['foo']}}
-    arguments = {'global': flexmock(monitoring_verbosity=1, dry_run=False), 'compact': flexmock()}
-
-    list(module.run_configuration('test.yaml', config, arguments))
-
-
-def test_run_configuration_executes_and_calls_hooks_for_create_action():
-    flexmock(module.borg_environment).should_receive('initialize')
-    flexmock(module.borg_version).should_receive('local_borg_version').and_return(flexmock())
-    flexmock(module.command).should_receive('execute_hook').twice()
-    flexmock(module.dispatch).should_receive('call_hooks').at_least().twice()
-    flexmock(module).should_receive('run_actions').and_return([])
-    config = {'location': {'repositories': ['foo']}}
-    arguments = {'global': flexmock(monitoring_verbosity=1, dry_run=False), 'create': flexmock()}
-
-    list(module.run_configuration('test.yaml', config, arguments))
-
-
-def test_run_configuration_calls_hooks_for_check_action():
-    flexmock(module.borg_environment).should_receive('initialize')
-    flexmock(module.borg_version).should_receive('local_borg_version').and_return(flexmock())
-    flexmock(module.command).should_receive('execute_hook').twice()
-    flexmock(module.dispatch).should_receive('call_hooks').at_least().twice()
-    flexmock(module).should_receive('run_actions').and_return([])
-    config = {'location': {'repositories': ['foo']}}
-    arguments = {'global': flexmock(monitoring_verbosity=1, dry_run=False), 'check': flexmock()}
-
-    list(module.run_configuration('test.yaml', config, arguments))
-
-
-def test_run_configuration_calls_hooks_for_extract_action():
-    flexmock(module.borg_environment).should_receive('initialize')
-    flexmock(module.borg_version).should_receive('local_borg_version').and_return(flexmock())
-    flexmock(module.command).should_receive('execute_hook').twice()
-    flexmock(module.dispatch).should_receive('call_hooks').never()
-    flexmock(module).should_receive('run_actions').and_return([])
-    config = {'location': {'repositories': ['foo']}}
-    arguments = {'global': flexmock(monitoring_verbosity=1, dry_run=False), 'extract': flexmock()}
-
-    list(module.run_configuration('test.yaml', config, arguments))
-
-
-def test_run_configuration_does_not_trigger_hooks_for_list_action():
-    flexmock(module.borg_environment).should_receive('initialize')
-    flexmock(module.borg_version).should_receive('local_borg_version').and_return(flexmock())
-    flexmock(module.command).should_receive('execute_hook').never()
-    flexmock(module.dispatch).should_receive('call_hooks').never()
-    flexmock(module).should_receive('run_actions').and_return([])
-    config = {'location': {'repositories': ['foo']}}
-    arguments = {'global': flexmock(monitoring_verbosity=1, dry_run=False), 'list': flexmock()}
-
-    list(module.run_configuration('test.yaml', config, arguments))
-
-
-def test_run_configuration_logs_actions_error():
-    flexmock(module.borg_environment).should_receive('initialize')
-    flexmock(module.borg_version).should_receive('local_borg_version').and_return(flexmock())
-    flexmock(module.command).should_receive('execute_hook')
-    flexmock(module.dispatch).should_receive('call_hooks')
+    flexmock(module.dispatch).should_receive('call_hooks').and_raise(OSError).and_return(
+        None
+    ).and_return(None)
     expected_results = [flexmock()]
-    flexmock(module).should_receive('make_error_log_records').and_return(expected_results)
-    flexmock(module).should_receive('run_actions').and_raise(OSError)
-    config = {'location': {'repositories': ['foo']}}
-    arguments = {'global': flexmock(monitoring_verbosity=1, dry_run=False)}
-
-    results = list(module.run_configuration('test.yaml', config, arguments))
-
-    assert results == expected_results
-
-
-def test_run_configuration_logs_pre_hook_error():
-    flexmock(module.borg_environment).should_receive('initialize')
-    flexmock(module.borg_version).should_receive('local_borg_version').and_return(flexmock())
-    flexmock(module.command).should_receive('execute_hook').and_raise(OSError).and_return(None)
-    expected_results = [flexmock()]
-    flexmock(module).should_receive('make_error_log_records').and_return(expected_results)
+    flexmock(module).should_receive('log_error_records').and_return(expected_results)
     flexmock(module).should_receive('run_actions').never()
     config = {'location': {'repositories': ['foo']}}
     arguments = {'global': flexmock(monitoring_verbosity=1, dry_run=False), 'create': flexmock()}
@@ -137,12 +52,12 @@ def test_run_configuration_logs_pre_hook_error():
     assert results == expected_results
 
 
-def test_run_configuration_bails_for_pre_hook_soft_failure():
+def test_run_configuration_bails_for_monitor_start_soft_failure():
     flexmock(module.borg_environment).should_receive('initialize')
     flexmock(module.borg_version).should_receive('local_borg_version').and_return(flexmock())
     error = subprocess.CalledProcessError(borgmatic.hooks.command.SOFT_FAIL_EXIT_CODE, 'try again')
-    flexmock(module.command).should_receive('execute_hook').and_raise(error).and_return(None)
-    flexmock(module).should_receive('make_error_log_records').never()
+    flexmock(module.dispatch).should_receive('call_hooks').and_raise(error)
+    flexmock(module).should_receive('log_error_records').never()
     flexmock(module).should_receive('run_actions').never()
     config = {'location': {'repositories': ['foo']}}
     arguments = {'global': flexmock(monitoring_verbosity=1, dry_run=False), 'create': flexmock()}
@@ -152,15 +67,46 @@ def test_run_configuration_bails_for_pre_hook_soft_failure():
     assert results == []
 
 
-def test_run_configuration_logs_post_hook_error():
+def test_run_configuration_logs_actions_error():
     flexmock(module.borg_environment).should_receive('initialize')
     flexmock(module.borg_version).should_receive('local_borg_version').and_return(flexmock())
-    flexmock(module.command).should_receive('execute_hook').and_return(None).and_raise(
-        OSError
-    ).and_return(None)
+    flexmock(module.command).should_receive('execute_hook')
     flexmock(module.dispatch).should_receive('call_hooks')
     expected_results = [flexmock()]
-    flexmock(module).should_receive('make_error_log_records').and_return(expected_results)
+    flexmock(module).should_receive('log_error_records').and_return(expected_results)
+    flexmock(module).should_receive('run_actions').and_raise(OSError)
+    config = {'location': {'repositories': ['foo']}}
+    arguments = {'global': flexmock(monitoring_verbosity=1, dry_run=False)}
+
+    results = list(module.run_configuration('test.yaml', config, arguments))
+
+    assert results == expected_results
+
+
+def test_run_configuration_bails_for_actions_soft_failure():
+    flexmock(module.borg_environment).should_receive('initialize')
+    flexmock(module.borg_version).should_receive('local_borg_version').and_return(flexmock())
+    flexmock(module.dispatch).should_receive('call_hooks')
+    error = subprocess.CalledProcessError(borgmatic.hooks.command.SOFT_FAIL_EXIT_CODE, 'try again')
+    flexmock(module).should_receive('run_actions').and_raise(error)
+    flexmock(module).should_receive('log_error_records').never()
+    flexmock(module.command).should_receive('considered_soft_failure').and_return(True)
+    config = {'location': {'repositories': ['foo']}}
+    arguments = {'global': flexmock(monitoring_verbosity=1, dry_run=False), 'create': flexmock()}
+
+    results = list(module.run_configuration('test.yaml', config, arguments))
+
+    assert results == []
+
+
+def test_run_configuration_logs_monitor_finish_error():
+    flexmock(module.borg_environment).should_receive('initialize')
+    flexmock(module.borg_version).should_receive('local_borg_version').and_return(flexmock())
+    flexmock(module.dispatch).should_receive('call_hooks').and_return(None).and_return(
+        None
+    ).and_raise(OSError)
+    expected_results = [flexmock()]
+    flexmock(module).should_receive('log_error_records').and_return(expected_results)
     flexmock(module).should_receive('run_actions').and_return([])
     config = {'location': {'repositories': ['foo']}}
     arguments = {'global': flexmock(monitoring_verbosity=1, dry_run=False), 'create': flexmock()}
@@ -170,16 +116,16 @@ def test_run_configuration_logs_post_hook_error():
     assert results == expected_results
 
 
-def test_run_configuration_bails_for_post_hook_soft_failure():
+def test_run_configuration_bails_for_monitor_finish_soft_failure():
     flexmock(module.borg_environment).should_receive('initialize')
     flexmock(module.borg_version).should_receive('local_borg_version').and_return(flexmock())
     error = subprocess.CalledProcessError(borgmatic.hooks.command.SOFT_FAIL_EXIT_CODE, 'try again')
-    flexmock(module.command).should_receive('execute_hook').and_return(None).and_raise(
-        error
-    ).and_return(None)
-    flexmock(module.dispatch).should_receive('call_hooks')
-    flexmock(module).should_receive('make_error_log_records').never()
+    flexmock(module.dispatch).should_receive('call_hooks').and_return(None).and_return(
+        None
+    ).and_raise(error)
+    flexmock(module).should_receive('log_error_records').never()
     flexmock(module).should_receive('run_actions').and_return([])
+    flexmock(module.command).should_receive('considered_soft_failure').and_return(True)
     config = {'location': {'repositories': ['foo']}}
     arguments = {'global': flexmock(monitoring_verbosity=1, dry_run=False), 'create': flexmock()}
 
@@ -193,7 +139,7 @@ def test_run_configuration_logs_on_error_hook_error():
     flexmock(module.borg_version).should_receive('local_borg_version').and_return(flexmock())
     flexmock(module.command).should_receive('execute_hook').and_raise(OSError)
     expected_results = [flexmock(), flexmock()]
-    flexmock(module).should_receive('make_error_log_records').and_return(
+    flexmock(module).should_receive('log_error_records').and_return(
         expected_results[:1]
     ).and_return(expected_results[1:])
     flexmock(module).should_receive('run_actions').and_raise(OSError)
@@ -209,9 +155,9 @@ def test_run_configuration_bails_for_on_error_hook_soft_failure():
     flexmock(module.borg_environment).should_receive('initialize')
     flexmock(module.borg_version).should_receive('local_borg_version').and_return(flexmock())
     error = subprocess.CalledProcessError(borgmatic.hooks.command.SOFT_FAIL_EXIT_CODE, 'try again')
-    flexmock(module.command).should_receive('execute_hook').and_return(None).and_raise(error)
+    flexmock(module.command).should_receive('execute_hook').and_raise(error)
     expected_results = [flexmock()]
-    flexmock(module).should_receive('make_error_log_records').and_return(expected_results)
+    flexmock(module).should_receive('log_error_records').and_return(expected_results)
     flexmock(module).should_receive('run_actions').and_raise(OSError)
     config = {'location': {'repositories': ['foo']}}
     arguments = {'global': flexmock(monitoring_verbosity=1, dry_run=False), 'create': flexmock()}
@@ -227,12 +173,11 @@ def test_run_configuration_retries_soft_error():
     flexmock(module.borg_version).should_receive('local_borg_version').and_return(flexmock())
     flexmock(module.command).should_receive('execute_hook')
     flexmock(module).should_receive('run_actions').and_raise(OSError).and_return([])
-    expected_results = [flexmock()]
-    flexmock(module).should_receive('make_error_log_records').and_return(expected_results).once()
+    flexmock(module).should_receive('log_error_records').and_return([flexmock()]).once()
     config = {'location': {'repositories': ['foo']}, 'storage': {'retries': 1}}
     arguments = {'global': flexmock(monitoring_verbosity=1, dry_run=False), 'create': flexmock()}
     results = list(module.run_configuration('test.yaml', config, arguments))
-    assert results == expected_results
+    assert results == []
 
 
 def test_run_configuration_retries_hard_error():
@@ -241,18 +186,20 @@ def test_run_configuration_retries_hard_error():
     flexmock(module.borg_version).should_receive('local_borg_version').and_return(flexmock())
     flexmock(module.command).should_receive('execute_hook')
     flexmock(module).should_receive('run_actions').and_raise(OSError).times(2)
-    expected_results = [flexmock(), flexmock()]
-    flexmock(module).should_receive('make_error_log_records').with_args(
-        'foo: Error running actions for repository', OSError
-    ).and_return(expected_results[:1]).with_args(
-        'foo: Error running actions for repository', OSError
-    ).and_return(
-        expected_results[1:]
-    ).twice()
+    flexmock(module).should_receive('log_error_records').with_args(
+        'foo: Error running actions for repository',
+        OSError,
+        levelno=logging.WARNING,
+        log_command_error_output=True,
+    ).and_return([flexmock()])
+    error_logs = [flexmock()]
+    flexmock(module).should_receive('log_error_records').with_args(
+        'foo: Error running actions for repository', OSError,
+    ).and_return(error_logs)
     config = {'location': {'repositories': ['foo']}, 'storage': {'retries': 1}}
     arguments = {'global': flexmock(monitoring_verbosity=1, dry_run=False), 'create': flexmock()}
     results = list(module.run_configuration('test.yaml', config, arguments))
-    assert results == expected_results
+    assert results == error_logs
 
 
 def test_run_repos_ordered():
@@ -261,10 +208,10 @@ def test_run_repos_ordered():
     flexmock(module.command).should_receive('execute_hook')
     flexmock(module).should_receive('run_actions').and_raise(OSError).times(2)
     expected_results = [flexmock(), flexmock()]
-    flexmock(module).should_receive('make_error_log_records').with_args(
+    flexmock(module).should_receive('log_error_records').with_args(
         'foo: Error running actions for repository', OSError
     ).and_return(expected_results[:1]).ordered()
-    flexmock(module).should_receive('make_error_log_records').with_args(
+    flexmock(module).should_receive('log_error_records').with_args(
         'bar: Error running actions for repository', OSError
     ).and_return(expected_results[1:]).ordered()
     config = {'location': {'repositories': ['foo', 'bar']}}
@@ -278,23 +225,30 @@ def test_run_configuration_retries_round_robbin():
     flexmock(module.borg_version).should_receive('local_borg_version').and_return(flexmock())
     flexmock(module.command).should_receive('execute_hook')
     flexmock(module).should_receive('run_actions').and_raise(OSError).times(4)
-    expected_results = [flexmock(), flexmock(), flexmock(), flexmock()]
-    flexmock(module).should_receive('make_error_log_records').with_args(
+    flexmock(module).should_receive('log_error_records').with_args(
+        'foo: Error running actions for repository',
+        OSError,
+        levelno=logging.WARNING,
+        log_command_error_output=True,
+    ).and_return([flexmock()]).ordered()
+    flexmock(module).should_receive('log_error_records').with_args(
+        'bar: Error running actions for repository',
+        OSError,
+        levelno=logging.WARNING,
+        log_command_error_output=True,
+    ).and_return([flexmock()]).ordered()
+    foo_error_logs = [flexmock()]
+    flexmock(module).should_receive('log_error_records').with_args(
         'foo: Error running actions for repository', OSError
-    ).and_return(expected_results[0:1]).ordered()
-    flexmock(module).should_receive('make_error_log_records').with_args(
+    ).and_return(foo_error_logs).ordered()
+    bar_error_logs = [flexmock()]
+    flexmock(module).should_receive('log_error_records').with_args(
         'bar: Error running actions for repository', OSError
-    ).and_return(expected_results[1:2]).ordered()
-    flexmock(module).should_receive('make_error_log_records').with_args(
-        'foo: Error running actions for repository', OSError
-    ).and_return(expected_results[2:3]).ordered()
-    flexmock(module).should_receive('make_error_log_records').with_args(
-        'bar: Error running actions for repository', OSError
-    ).and_return(expected_results[3:4]).ordered()
+    ).and_return(bar_error_logs).ordered()
     config = {'location': {'repositories': ['foo', 'bar']}, 'storage': {'retries': 1}}
     arguments = {'global': flexmock(monitoring_verbosity=1, dry_run=False), 'create': flexmock()}
     results = list(module.run_configuration('test.yaml', config, arguments))
-    assert results == expected_results
+    assert results == foo_error_logs + bar_error_logs
 
 
 def test_run_configuration_retries_one_passes():
@@ -304,20 +258,26 @@ def test_run_configuration_retries_one_passes():
     flexmock(module).should_receive('run_actions').and_raise(OSError).and_raise(OSError).and_return(
         []
     ).and_raise(OSError).times(4)
-    expected_results = [flexmock(), flexmock(), flexmock()]
-    flexmock(module).should_receive('make_error_log_records').with_args(
-        'foo: Error running actions for repository', OSError
-    ).and_return(expected_results[0:1]).ordered()
-    flexmock(module).should_receive('make_error_log_records').with_args(
+    flexmock(module).should_receive('log_error_records').with_args(
+        'foo: Error running actions for repository',
+        OSError,
+        levelno=logging.WARNING,
+        log_command_error_output=True,
+    ).and_return([flexmock()]).ordered()
+    flexmock(module).should_receive('log_error_records').with_args(
+        'bar: Error running actions for repository',
+        OSError,
+        levelno=logging.WARNING,
+        log_command_error_output=True,
+    ).and_return(flexmock()).ordered()
+    error_logs = [flexmock()]
+    flexmock(module).should_receive('log_error_records').with_args(
         'bar: Error running actions for repository', OSError
-    ).and_return(expected_results[1:2]).ordered()
-    flexmock(module).should_receive('make_error_log_records').with_args(
-        'bar: Error running actions for repository', OSError
-    ).and_return(expected_results[2:3]).ordered()
+    ).and_return(error_logs).ordered()
     config = {'location': {'repositories': ['foo', 'bar']}, 'storage': {'retries': 1}}
     arguments = {'global': flexmock(monitoring_verbosity=1, dry_run=False), 'create': flexmock()}
     results = list(module.run_configuration('test.yaml', config, arguments))
-    assert results == expected_results
+    assert results == error_logs
 
 
 def test_run_configuration_retry_wait():
@@ -325,29 +285,38 @@ def test_run_configuration_retry_wait():
     flexmock(module.borg_version).should_receive('local_borg_version').and_return(flexmock())
     flexmock(module.command).should_receive('execute_hook')
     flexmock(module).should_receive('run_actions').and_raise(OSError).times(4)
-    expected_results = [flexmock(), flexmock(), flexmock(), flexmock()]
-    flexmock(module).should_receive('make_error_log_records').with_args(
-        'foo: Error running actions for repository', OSError
-    ).and_return(expected_results[0:1]).ordered()
+    flexmock(module).should_receive('log_error_records').with_args(
+        'foo: Error running actions for repository',
+        OSError,
+        levelno=logging.WARNING,
+        log_command_error_output=True,
+    ).and_return([flexmock()]).ordered()
 
     flexmock(time).should_receive('sleep').with_args(10).and_return().ordered()
-    flexmock(module).should_receive('make_error_log_records').with_args(
-        'foo: Error running actions for repository', OSError
-    ).and_return(expected_results[1:2]).ordered()
+    flexmock(module).should_receive('log_error_records').with_args(
+        'foo: Error running actions for repository',
+        OSError,
+        levelno=logging.WARNING,
+        log_command_error_output=True,
+    ).and_return([flexmock()]).ordered()
 
     flexmock(time).should_receive('sleep').with_args(20).and_return().ordered()
-    flexmock(module).should_receive('make_error_log_records').with_args(
-        'foo: Error running actions for repository', OSError
-    ).and_return(expected_results[2:3]).ordered()
+    flexmock(module).should_receive('log_error_records').with_args(
+        'foo: Error running actions for repository',
+        OSError,
+        levelno=logging.WARNING,
+        log_command_error_output=True,
+    ).and_return([flexmock()]).ordered()
 
     flexmock(time).should_receive('sleep').with_args(30).and_return().ordered()
-    flexmock(module).should_receive('make_error_log_records').with_args(
+    error_logs = [flexmock()]
+    flexmock(module).should_receive('log_error_records').with_args(
         'foo: Error running actions for repository', OSError
-    ).and_return(expected_results[3:4]).ordered()
+    ).and_return(error_logs).ordered()
     config = {'location': {'repositories': ['foo']}, 'storage': {'retries': 3, 'retry_wait': 10}}
     arguments = {'global': flexmock(monitoring_verbosity=1, dry_run=False), 'create': flexmock()}
     results = list(module.run_configuration('test.yaml', config, arguments))
-    assert results == expected_results
+    assert results == error_logs
 
 
 def test_run_configuration_retries_timeout_multiple_repos():
@@ -357,29 +326,342 @@ def test_run_configuration_retries_timeout_multiple_repos():
     flexmock(module).should_receive('run_actions').and_raise(OSError).and_raise(OSError).and_return(
         []
     ).and_raise(OSError).times(4)
-    expected_results = [flexmock(), flexmock(), flexmock()]
-    flexmock(module).should_receive('make_error_log_records').with_args(
-        'foo: Error running actions for repository', OSError
-    ).and_return(expected_results[0:1]).ordered()
-    flexmock(module).should_receive('make_error_log_records').with_args(
-        'bar: Error running actions for repository', OSError
-    ).and_return(expected_results[1:2]).ordered()
+    flexmock(module).should_receive('log_error_records').with_args(
+        'foo: Error running actions for repository',
+        OSError,
+        levelno=logging.WARNING,
+        log_command_error_output=True,
+    ).and_return([flexmock()]).ordered()
+    flexmock(module).should_receive('log_error_records').with_args(
+        'bar: Error running actions for repository',
+        OSError,
+        levelno=logging.WARNING,
+        log_command_error_output=True,
+    ).and_return([flexmock()]).ordered()
 
     # Sleep before retrying foo (and passing)
     flexmock(time).should_receive('sleep').with_args(10).and_return().ordered()
 
     # Sleep before retrying bar (and failing)
     flexmock(time).should_receive('sleep').with_args(10).and_return().ordered()
-    flexmock(module).should_receive('make_error_log_records').with_args(
+    error_logs = [flexmock()]
+    flexmock(module).should_receive('log_error_records').with_args(
         'bar: Error running actions for repository', OSError
-    ).and_return(expected_results[2:3]).ordered()
+    ).and_return(error_logs).ordered()
     config = {
         'location': {'repositories': ['foo', 'bar']},
         'storage': {'retries': 1, 'retry_wait': 10},
     }
     arguments = {'global': flexmock(monitoring_verbosity=1, dry_run=False), 'create': flexmock()}
     results = list(module.run_configuration('test.yaml', config, arguments))
-    assert results == expected_results
+    assert results == error_logs
+
+
+def test_run_actions_does_not_raise_for_init_action():
+    flexmock(module.borg_init).should_receive('initialize_repository')
+    arguments = {
+        'global': flexmock(monitoring_verbosity=1, dry_run=False),
+        'init': flexmock(
+            encryption_mode=flexmock(), append_only=flexmock(), storage_quota=flexmock()
+        ),
+    }
+
+    list(
+        module.run_actions(
+            arguments=arguments,
+            config_filename='test.yaml',
+            location={'repositories': ['repo']},
+            storage={},
+            retention={},
+            consistency={},
+            hooks={},
+            local_path=None,
+            remote_path=None,
+            local_borg_version=None,
+            repository_path='repo',
+        )
+    )
+
+
+def test_run_actions_calls_hooks_for_prune_action():
+    flexmock(module.borg_prune).should_receive('prune_archives')
+    flexmock(module.command).should_receive('execute_hook').twice()
+    arguments = {
+        'global': flexmock(monitoring_verbosity=1, dry_run=False),
+        'prune': flexmock(stats=flexmock(), files=flexmock()),
+    }
+
+    list(
+        module.run_actions(
+            arguments=arguments,
+            config_filename='test.yaml',
+            location={'repositories': ['repo']},
+            storage={},
+            retention={},
+            consistency={},
+            hooks={},
+            local_path=None,
+            remote_path=None,
+            local_borg_version=None,
+            repository_path='repo',
+        )
+    )
+
+
+def test_run_actions_calls_hooks_for_compact_action():
+    flexmock(module.borg_feature).should_receive('available').and_return(True)
+    flexmock(module.borg_compact).should_receive('compact_segments')
+    flexmock(module.command).should_receive('execute_hook').twice()
+    arguments = {
+        'global': flexmock(monitoring_verbosity=1, dry_run=False),
+        'compact': flexmock(progress=flexmock(), cleanup_commits=flexmock(), threshold=flexmock()),
+    }
+
+    list(
+        module.run_actions(
+            arguments=arguments,
+            config_filename='test.yaml',
+            location={'repositories': ['repo']},
+            storage={},
+            retention={},
+            consistency={},
+            hooks={},
+            local_path=None,
+            remote_path=None,
+            local_borg_version=None,
+            repository_path='repo',
+        )
+    )
+
+
+def test_run_actions_executes_and_calls_hooks_for_create_action():
+    flexmock(module.borg_create).should_receive('create_archive')
+    flexmock(module.command).should_receive('execute_hook').twice()
+    flexmock(module.dispatch).should_receive('call_hooks').and_return({}).times(3)
+    arguments = {
+        'global': flexmock(monitoring_verbosity=1, dry_run=False),
+        'create': flexmock(
+            progress=flexmock(), stats=flexmock(), json=flexmock(), files=flexmock()
+        ),
+    }
+
+    list(
+        module.run_actions(
+            arguments=arguments,
+            config_filename='test.yaml',
+            location={'repositories': ['repo']},
+            storage={},
+            retention={},
+            consistency={},
+            hooks={},
+            local_path=None,
+            remote_path=None,
+            local_borg_version=None,
+            repository_path='repo',
+        )
+    )
+
+
+def test_run_actions_calls_hooks_for_check_action():
+    flexmock(module.checks).should_receive('repository_enabled_for_checks').and_return(True)
+    flexmock(module.borg_check).should_receive('check_archives')
+    flexmock(module.command).should_receive('execute_hook').twice()
+    arguments = {
+        'global': flexmock(monitoring_verbosity=1, dry_run=False),
+        'check': flexmock(progress=flexmock(), repair=flexmock(), only=flexmock()),
+    }
+
+    list(
+        module.run_actions(
+            arguments=arguments,
+            config_filename='test.yaml',
+            location={'repositories': ['repo']},
+            storage={},
+            retention={},
+            consistency={},
+            hooks={},
+            local_path=None,
+            remote_path=None,
+            local_borg_version=None,
+            repository_path='repo',
+        )
+    )
+
+
+def test_run_actions_calls_hooks_for_extract_action():
+    flexmock(module.validate).should_receive('repositories_match').and_return(True)
+    flexmock(module.borg_extract).should_receive('extract_archive')
+    flexmock(module.command).should_receive('execute_hook').twice()
+    arguments = {
+        'global': flexmock(monitoring_verbosity=1, dry_run=False),
+        'extract': flexmock(
+            paths=flexmock(),
+            progress=flexmock(),
+            destination=flexmock(),
+            strip_components=flexmock(),
+            archive=flexmock(),
+            repository='repo',
+        ),
+    }
+
+    list(
+        module.run_actions(
+            arguments=arguments,
+            config_filename='test.yaml',
+            location={'repositories': ['repo']},
+            storage={},
+            retention={},
+            consistency={},
+            hooks={},
+            local_path=None,
+            remote_path=None,
+            local_borg_version=None,
+            repository_path='repo',
+        )
+    )
+
+
+def test_run_actions_does_not_raise_for_export_tar_action():
+    flexmock(module.validate).should_receive('repositories_match').and_return(True)
+    flexmock(module.borg_export_tar).should_receive('export_tar_archive')
+    arguments = {
+        'global': flexmock(monitoring_verbosity=1, dry_run=False),
+        'export-tar': flexmock(
+            repository=flexmock(),
+            archive=flexmock(),
+            paths=flexmock(),
+            destination=flexmock(),
+            tar_filter=flexmock(),
+            files=flexmock(),
+            strip_components=flexmock(),
+        ),
+    }
+
+    list(
+        module.run_actions(
+            arguments=arguments,
+            config_filename='test.yaml',
+            location={'repositories': ['repo']},
+            storage={},
+            retention={},
+            consistency={},
+            hooks={},
+            local_path=None,
+            remote_path=None,
+            local_borg_version=None,
+            repository_path='repo',
+        )
+    )
+
+
+def test_run_actions_does_not_raise_for_mount_action():
+    flexmock(module.validate).should_receive('repositories_match').and_return(True)
+    flexmock(module.borg_mount).should_receive('mount_archive')
+    arguments = {
+        'global': flexmock(monitoring_verbosity=1, dry_run=False),
+        'mount': flexmock(
+            repository=flexmock(),
+            archive=flexmock(),
+            mount_point=flexmock(),
+            paths=flexmock(),
+            foreground=flexmock(),
+            options=flexmock(),
+        ),
+    }
+
+    list(
+        module.run_actions(
+            arguments=arguments,
+            config_filename='test.yaml',
+            location={'repositories': ['repo']},
+            storage={},
+            retention={},
+            consistency={},
+            hooks={},
+            local_path=None,
+            remote_path=None,
+            local_borg_version=None,
+            repository_path='repo',
+        )
+    )
+
+
+def test_run_actions_does_not_raise_for_list_action():
+    flexmock(module.validate).should_receive('repositories_match').and_return(True)
+    flexmock(module.borg_list).should_receive('resolve_archive_name').and_return(flexmock())
+    flexmock(module.borg_list).should_receive('list_archives')
+    arguments = {
+        'global': flexmock(monitoring_verbosity=1, dry_run=False),
+        'list': flexmock(repository=flexmock(), archive=flexmock(), json=flexmock()),
+    }
+
+    list(
+        module.run_actions(
+            arguments=arguments,
+            config_filename='test.yaml',
+            location={'repositories': ['repo']},
+            storage={},
+            retention={},
+            consistency={},
+            hooks={},
+            local_path=None,
+            remote_path=None,
+            local_borg_version=None,
+            repository_path='repo',
+        )
+    )
+
+
+def test_run_actions_does_not_raise_for_info_action():
+    flexmock(module.validate).should_receive('repositories_match').and_return(True)
+    flexmock(module.borg_list).should_receive('resolve_archive_name').and_return(flexmock())
+    flexmock(module.borg_info).should_receive('display_archives_info')
+    arguments = {
+        'global': flexmock(monitoring_verbosity=1, dry_run=False),
+        'info': flexmock(repository=flexmock(), archive=flexmock(), json=flexmock()),
+    }
+
+    list(
+        module.run_actions(
+            arguments=arguments,
+            config_filename='test.yaml',
+            location={'repositories': ['repo']},
+            storage={},
+            retention={},
+            consistency={},
+            hooks={},
+            local_path=None,
+            remote_path=None,
+            local_borg_version=None,
+            repository_path='repo',
+        )
+    )
+
+
+def test_run_actions_does_not_raise_for_borg_action():
+    flexmock(module.validate).should_receive('repositories_match').and_return(True)
+    flexmock(module.borg_list).should_receive('resolve_archive_name').and_return(flexmock())
+    flexmock(module.borg_borg).should_receive('run_arbitrary_borg')
+    arguments = {
+        'global': flexmock(monitoring_verbosity=1, dry_run=False),
+        'borg': flexmock(repository=flexmock(), archive=flexmock(), options=flexmock()),
+    }
+
+    list(
+        module.run_actions(
+            arguments=arguments,
+            config_filename='test.yaml',
+            location={'repositories': ['repo']},
+            storage={},
+            retention={},
+            consistency={},
+            hooks={},
+            local_path=None,
+            remote_path=None,
+            local_borg_version=None,
+            repository_path='repo',
+        )
+    )
 
 
 def test_load_configurations_collects_parsed_configurations():
@@ -395,6 +677,15 @@ def test_load_configurations_collects_parsed_configurations():
     assert logs == []
 
 
+def test_load_configurations_logs_warning_for_permission_error():
+    flexmock(module.validate).should_receive('parse_configuration').and_raise(PermissionError)
+
+    configs, logs = tuple(module.load_configurations(('test.yaml',)))
+
+    assert configs == {}
+    assert {log.levelno for log in logs} == {logging.WARNING}
+
+
 def test_load_configurations_logs_critical_for_parse_error():
     flexmock(module.validate).should_receive('parse_configuration').and_raise(ValueError)
 
@@ -412,48 +703,46 @@ def test_log_record_with_suppress_does_not_raise():
     module.log_record(levelno=1, foo='bar', baz='quux', suppress_log=True)
 
 
-def test_make_error_log_records_generates_output_logs_for_message_only():
+def test_log_error_records_generates_output_logs_for_message_only():
     flexmock(module).should_receive('log_record').replace_with(dict)
 
-    logs = tuple(module.make_error_log_records('Error'))
+    logs = tuple(module.log_error_records('Error'))
 
     assert {log['levelno'] for log in logs} == {logging.CRITICAL}
 
 
-def test_make_error_log_records_generates_output_logs_for_called_process_error():
+def test_log_error_records_generates_output_logs_for_called_process_error():
     flexmock(module).should_receive('log_record').replace_with(dict)
     flexmock(module.logger).should_receive('getEffectiveLevel').and_return(logging.WARNING)
 
     logs = tuple(
-        module.make_error_log_records(
-            'Error', subprocess.CalledProcessError(1, 'ls', 'error output')
-        )
+        module.log_error_records('Error', subprocess.CalledProcessError(1, 'ls', 'error output'))
     )
 
     assert {log['levelno'] for log in logs} == {logging.CRITICAL}
     assert any(log for log in logs if 'error output' in str(log))
 
 
-def test_make_error_log_records_generates_logs_for_value_error():
+def test_log_error_records_generates_logs_for_value_error():
     flexmock(module).should_receive('log_record').replace_with(dict)
 
-    logs = tuple(module.make_error_log_records('Error', ValueError()))
+    logs = tuple(module.log_error_records('Error', ValueError()))
 
     assert {log['levelno'] for log in logs} == {logging.CRITICAL}
 
 
-def test_make_error_log_records_generates_logs_for_os_error():
+def test_log_error_records_generates_logs_for_os_error():
     flexmock(module).should_receive('log_record').replace_with(dict)
 
-    logs = tuple(module.make_error_log_records('Error', OSError()))
+    logs = tuple(module.log_error_records('Error', OSError()))
 
     assert {log['levelno'] for log in logs} == {logging.CRITICAL}
 
 
-def test_make_error_log_records_generates_nothing_for_other_error():
+def test_log_error_records_generates_nothing_for_other_error():
     flexmock(module).should_receive('log_record').replace_with(dict)
 
-    logs = tuple(module.make_error_log_records('Error', KeyError()))
+    logs = tuple(module.log_error_records('Error', KeyError()))
 
     assert logs == ()
 
@@ -510,7 +799,7 @@ def test_collect_configuration_run_summary_logs_extract_with_repository_error():
         ValueError
     )
     expected_logs = (flexmock(),)
-    flexmock(module).should_receive('make_error_log_records').and_return(expected_logs)
+    flexmock(module).should_receive('log_error_records').and_return(expected_logs)
     arguments = {'extract': flexmock(repository='repo')}
 
     logs = tuple(
@@ -537,7 +826,7 @@ def test_collect_configuration_run_summary_logs_mount_with_repository_error():
         ValueError
     )
     expected_logs = (flexmock(),)
-    flexmock(module).should_receive('make_error_log_records').and_return(expected_logs)
+    flexmock(module).should_receive('log_error_records').and_return(expected_logs)
     arguments = {'mount': flexmock(repository='repo')}
 
     logs = tuple(
@@ -550,7 +839,7 @@ def test_collect_configuration_run_summary_logs_mount_with_repository_error():
 def test_collect_configuration_run_summary_logs_missing_configs_error():
     arguments = {'global': flexmock(config_paths=[])}
     expected_logs = (flexmock(),)
-    flexmock(module).should_receive('make_error_log_records').and_return(expected_logs)
+    flexmock(module).should_receive('log_error_records').and_return(expected_logs)
 
     logs = tuple(module.collect_configuration_run_summary_logs({}, arguments=arguments))
 
@@ -560,7 +849,7 @@ def test_collect_configuration_run_summary_logs_missing_configs_error():
 def test_collect_configuration_run_summary_logs_pre_hook_error():
     flexmock(module.command).should_receive('execute_hook').and_raise(ValueError)
     expected_logs = (flexmock(),)
-    flexmock(module).should_receive('make_error_log_records').and_return(expected_logs)
+    flexmock(module).should_receive('log_error_records').and_return(expected_logs)
     arguments = {'create': flexmock(), 'global': flexmock(monitoring_verbosity=1, dry_run=False)}
 
     logs = tuple(
@@ -574,7 +863,7 @@ def test_collect_configuration_run_summary_logs_post_hook_error():
     flexmock(module.command).should_receive('execute_hook').and_return(None).and_raise(ValueError)
     flexmock(module).should_receive('run_configuration').and_return([])
     expected_logs = (flexmock(),)
-    flexmock(module).should_receive('make_error_log_records').and_return(expected_logs)
+    flexmock(module).should_receive('log_error_records').and_return(expected_logs)
     arguments = {'create': flexmock(), 'global': flexmock(monitoring_verbosity=1, dry_run=False)}
 
     logs = tuple(
@@ -589,7 +878,7 @@ def test_collect_configuration_run_summary_logs_for_list_with_archive_and_reposi
         ValueError
     )
     expected_logs = (flexmock(),)
-    flexmock(module).should_receive('make_error_log_records').and_return(expected_logs)
+    flexmock(module).should_receive('log_error_records').and_return(expected_logs)
     arguments = {'list': flexmock(repository='repo', archive='test')}
 
     logs = tuple(
@@ -615,7 +904,7 @@ def test_collect_configuration_run_summary_logs_run_configuration_error():
     flexmock(module).should_receive('run_configuration').and_return(
         [logging.makeLogRecord(dict(levelno=logging.CRITICAL, levelname='CRITICAL', msg='Error'))]
     )
-    flexmock(module).should_receive('make_error_log_records').and_return([])
+    flexmock(module).should_receive('log_error_records').and_return([])
     arguments = {}
 
     logs = tuple(
@@ -629,7 +918,7 @@ def test_collect_configuration_run_summary_logs_run_umount_error():
     flexmock(module.validate).should_receive('guard_configuration_contains_repository')
     flexmock(module).should_receive('run_configuration').and_return([])
     flexmock(module.borg_umount).should_receive('unmount_archive').and_raise(OSError)
-    flexmock(module).should_receive('make_error_log_records').and_return(
+    flexmock(module).should_receive('log_error_records').and_return(
         [logging.makeLogRecord(dict(levelno=logging.CRITICAL, levelname='CRITICAL', msg='Error'))]
     )
     arguments = {'umount': flexmock(mount_point='/mnt')}

tests/unit/config/test_normalize.py

@@ -19,6 +19,22 @@ from borgmatic.config import normalize as module
             {'location': {'source_directories': ['foo', 'bar']}},
         ),
         ({'storage': {'compression': 'yes_please'}}, {'storage': {'compression': 'yes_please'}}),
+        (
+            {'hooks': {'healthchecks': 'https://example.com'}},
+            {'hooks': {'healthchecks': {'ping_url': 'https://example.com'}}},
+        ),
+        (
+            {'hooks': {'cronitor': 'https://example.com'}},
+            {'hooks': {'cronitor': {'ping_url': 'https://example.com'}}},
+        ),
+        (
+            {'hooks': {'pagerduty': 'https://example.com'}},
+            {'hooks': {'pagerduty': {'integration_key': 'https://example.com'}}},
+        ),
+        (
+            {'hooks': {'cronhub': 'https://example.com'}},
+            {'hooks': {'cronhub': {'ping_url': 'https://example.com'}}},
+        ),
     ),
 )
 def test_normalize_applies_hard_coded_normalization_to_config(config, expected_config):

tests/unit/config/test_validate.py

@@ -37,33 +37,6 @@ def test_validation_error_string_contains_errors():
     assert 'uh oh' in result
 
 
-def test_apply_logical_validation_raises_if_archive_name_format_present_without_prefix():
-    flexmock(module).format_json_error = lambda error: error.message
-
-    with pytest.raises(module.Validation_error):
-        module.apply_logical_validation(
-            'config.yaml',
-            {
-                'storage': {'archive_name_format': '{hostname}-{now}'},
-                'retention': {'keep_daily': 7},
-            },
-        )
-
-
-def test_apply_logical_validation_raises_if_archive_name_format_present_without_retention_prefix():
-    flexmock(module).format_json_error = lambda error: error.message
-
-    with pytest.raises(module.Validation_error):
-        module.apply_logical_validation(
-            'config.yaml',
-            {
-                'storage': {'archive_name_format': '{hostname}-{now}'},
-                'retention': {'keep_daily': 7},
-                'consistency': {'prefix': '{hostname}-'},
-            },
-        )
-
-
 def test_apply_locical_validation_raises_if_unknown_repository_in_check_repositories():
     flexmock(module).format_json_error = lambda error: error.message
 

tests/unit/hooks/test_command.py

@@ -7,22 +7,34 @@ from borgmatic.hooks import command as module
 
 
 def test_interpolate_context_passes_through_command_without_variable():
-    assert module.interpolate_context('ls', {'foo': 'bar'}) == 'ls'
+    assert module.interpolate_context('test.yaml', 'pre-backup', 'ls', {'foo': 'bar'}) == 'ls'
 
 
 def test_interpolate_context_passes_through_command_with_unknown_variable():
-    assert module.interpolate_context('ls {baz}', {'foo': 'bar'}) == 'ls {baz}'
+    assert (
+        module.interpolate_context('test.yaml', 'pre-backup', 'ls {baz}', {'foo': 'bar'})
+        == 'ls {baz}'
+    )
 
 
 def test_interpolate_context_interpolates_variables():
     context = {'foo': 'bar', 'baz': 'quux'}
 
-    assert module.interpolate_context('ls {foo}{baz} {baz}', context) == 'ls barquux quux'
+    assert (
+        module.interpolate_context('test.yaml', 'pre-backup', 'ls {foo}{baz} {baz}', context)
+        == 'ls barquux quux'
+    )
+
+
+def test_interpolate_context_does_not_touch_unknown_variables():
+    context = {'foo': 'bar', 'baz': 'quux'}
+
+    assert module.interpolate_context('test.yaml', 'pre-backup', 'ls {wtf}', context) == 'ls {wtf}'
 
 
 def test_execute_hook_invokes_each_command():
     flexmock(module).should_receive('interpolate_context').replace_with(
-        lambda command, context: command
+        lambda config_file, hook_description, command, context: command
     )
     flexmock(module.execute).should_receive('execute_command').with_args(
         [':'], output_log_level=logging.WARNING, shell=True
@@ -33,7 +45,7 @@ def test_execute_hook_invokes_each_command():
 
 def test_execute_hook_with_multiple_commands_invokes_each_command():
     flexmock(module).should_receive('interpolate_context').replace_with(
-        lambda command, context: command
+        lambda config_file, hook_description, command, context: command
     )
     flexmock(module.execute).should_receive('execute_command').with_args(
         [':'], output_log_level=logging.WARNING, shell=True
@@ -47,7 +59,7 @@ def test_execute_hook_with_multiple_commands_invokes_each_command():
 
 def test_execute_hook_with_umask_sets_that_umask():
     flexmock(module).should_receive('interpolate_context').replace_with(
-        lambda command, context: command
+        lambda config_file, hook_description, command, context: command
     )
     flexmock(module.os).should_receive('umask').with_args(0o77).and_return(0o22).once()
     flexmock(module.os).should_receive('umask').with_args(0o22).once()
@@ -60,7 +72,7 @@ def test_execute_hook_with_umask_sets_that_umask():
 
 def test_execute_hook_with_dry_run_skips_commands():
     flexmock(module).should_receive('interpolate_context').replace_with(
-        lambda command, context: command
+        lambda config_file, hook_description, command, context: command
     )
     flexmock(module.execute).should_receive('execute_command').never()
 
@@ -73,7 +85,7 @@ def test_execute_hook_with_empty_commands_does_not_raise():
 
 def test_execute_hook_on_error_logs_as_error():
     flexmock(module).should_receive('interpolate_context').replace_with(
-        lambda command, context: command
+        lambda config_file, hook_description, command, context: command
     )
     flexmock(module.execute).should_receive('execute_command').with_args(
         [':'], output_log_level=logging.ERROR, shell=True

tests/unit/hooks/test_cronhub.py

@@ -4,45 +4,72 @@ from borgmatic.hooks import cronhub as module
 
 
 def test_ping_monitor_rewrites_ping_url_for_start_state():
-    ping_url = 'https://example.com/start/abcdef'
+    hook_config = {'ping_url': 'https://example.com/start/abcdef'}
     flexmock(module.requests).should_receive('get').with_args('https://example.com/start/abcdef')
 
     module.ping_monitor(
-        ping_url, 'config.yaml', module.monitor.State.START, monitoring_log_level=1, dry_run=False
+        hook_config,
+        'config.yaml',
+        module.monitor.State.START,
+        monitoring_log_level=1,
+        dry_run=False,
     )
 
 
 def test_ping_monitor_rewrites_ping_url_and_state_for_start_state():
-    ping_url = 'https://example.com/ping/abcdef'
+    hook_config = {'ping_url': 'https://example.com/ping/abcdef'}
     flexmock(module.requests).should_receive('get').with_args('https://example.com/start/abcdef')
 
     module.ping_monitor(
-        ping_url, 'config.yaml', module.monitor.State.START, monitoring_log_level=1, dry_run=False
+        hook_config,
+        'config.yaml',
+        module.monitor.State.START,
+        monitoring_log_level=1,
+        dry_run=False,
     )
 
 
 def test_ping_monitor_rewrites_ping_url_for_finish_state():
-    ping_url = 'https://example.com/start/abcdef'
+    hook_config = {'ping_url': 'https://example.com/start/abcdef'}
     flexmock(module.requests).should_receive('get').with_args('https://example.com/finish/abcdef')
 
     module.ping_monitor(
-        ping_url, 'config.yaml', module.monitor.State.FINISH, monitoring_log_level=1, dry_run=False
+        hook_config,
+        'config.yaml',
+        module.monitor.State.FINISH,
+        monitoring_log_level=1,
+        dry_run=False,
     )
 
 
 def test_ping_monitor_rewrites_ping_url_for_fail_state():
-    ping_url = 'https://example.com/start/abcdef'
+    hook_config = {'ping_url': 'https://example.com/start/abcdef'}
     flexmock(module.requests).should_receive('get').with_args('https://example.com/fail/abcdef')
 
     module.ping_monitor(
-        ping_url, 'config.yaml', module.monitor.State.FAIL, monitoring_log_level=1, dry_run=False
+        hook_config, 'config.yaml', module.monitor.State.FAIL, monitoring_log_level=1, dry_run=False
     )
 
 
 def test_ping_monitor_dry_run_does_not_hit_ping_url():
-    ping_url = 'https://example.com'
+    hook_config = {'ping_url': 'https://example.com'}
     flexmock(module.requests).should_receive('get').never()
 
     module.ping_monitor(
-        ping_url, 'config.yaml', module.monitor.State.START, monitoring_log_level=1, dry_run=True
+        hook_config, 'config.yaml', module.monitor.State.START, monitoring_log_level=1, dry_run=True
+    )
+
+
+def test_ping_monitor_with_connection_error_does_not_raise():
+    hook_config = {'ping_url': 'https://example.com/start/abcdef'}
+    flexmock(module.requests).should_receive('get').and_raise(
+        module.requests.exceptions.ConnectionError
+    )
+
+    module.ping_monitor(
+        hook_config,
+        'config.yaml',
+        module.monitor.State.START,
+        monitoring_log_level=1,
+        dry_run=False,
     )

tests/unit/hooks/test_cronitor.py

@@ -4,36 +4,59 @@ from borgmatic.hooks import cronitor as module
 
 
 def test_ping_monitor_hits_ping_url_for_start_state():
-    ping_url = 'https://example.com'
-    flexmock(module.requests).should_receive('get').with_args('{}/{}'.format(ping_url, 'run'))
+    hook_config = {'ping_url': 'https://example.com'}
+    flexmock(module.requests).should_receive('get').with_args('https://example.com/run')
 
     module.ping_monitor(
-        ping_url, 'config.yaml', module.monitor.State.START, monitoring_log_level=1, dry_run=False
+        hook_config,
+        'config.yaml',
+        module.monitor.State.START,
+        monitoring_log_level=1,
+        dry_run=False,
     )
 
 
 def test_ping_monitor_hits_ping_url_for_finish_state():
-    ping_url = 'https://example.com'
-    flexmock(module.requests).should_receive('get').with_args('{}/{}'.format(ping_url, 'complete'))
+    hook_config = {'ping_url': 'https://example.com'}
+    flexmock(module.requests).should_receive('get').with_args('https://example.com/complete')
 
     module.ping_monitor(
-        ping_url, 'config.yaml', module.monitor.State.FINISH, monitoring_log_level=1, dry_run=False
+        hook_config,
+        'config.yaml',
+        module.monitor.State.FINISH,
+        monitoring_log_level=1,
+        dry_run=False,
     )
 
 
 def test_ping_monitor_hits_ping_url_for_fail_state():
-    ping_url = 'https://example.com'
-    flexmock(module.requests).should_receive('get').with_args('{}/{}'.format(ping_url, 'fail'))
+    hook_config = {'ping_url': 'https://example.com'}
+    flexmock(module.requests).should_receive('get').with_args('https://example.com/fail')
 
     module.ping_monitor(
-        ping_url, 'config.yaml', module.monitor.State.FAIL, monitoring_log_level=1, dry_run=False
+        hook_config, 'config.yaml', module.monitor.State.FAIL, monitoring_log_level=1, dry_run=False
     )
 
 
 def test_ping_monitor_dry_run_does_not_hit_ping_url():
-    ping_url = 'https://example.com'
+    hook_config = {'ping_url': 'https://example.com'}
     flexmock(module.requests).should_receive('get').never()
 
     module.ping_monitor(
-        ping_url, 'config.yaml', module.monitor.State.START, monitoring_log_level=1, dry_run=True
+        hook_config, 'config.yaml', module.monitor.State.START, monitoring_log_level=1, dry_run=True
+    )
+
+
+def test_ping_monitor_with_connection_error_does_not_raise():
+    hook_config = {'ping_url': 'https://example.com'}
+    flexmock(module.requests).should_receive('get').and_raise(
+        module.requests.exceptions.ConnectionError
+    )
+
+    module.ping_monitor(
+        hook_config,
+        'config.yaml',
+        module.monitor.State.START,
+        monitoring_log_level=1,
+        dry_run=False,
     )

tests/unit/hooks/test_healthchecks.py

@@ -12,6 +12,15 @@ def test_forgetful_buffering_handler_emit_collects_log_records():
     assert not handler.forgot
 
 
+def test_forgetful_buffering_handler_emit_collects_log_records_with_zero_byte_capacity():
+    handler = module.Forgetful_buffering_handler(byte_capacity=0, log_level=1)
+    handler.emit(flexmock(getMessage=lambda: 'foo'))
+    handler.emit(flexmock(getMessage=lambda: 'bar'))
+
+    assert handler.buffer == ['foo\n', 'bar\n']
+    assert not handler.forgot
+
+
 def test_forgetful_buffering_handler_emit_forgets_log_records_when_capacity_reached():
     handler = module.Forgetful_buffering_handler(byte_capacity=len('foo\nbar\n'), log_level=1)
     handler.emit(flexmock(getMessage=lambda: 'foo'))
@@ -60,15 +69,68 @@ def test_format_buffered_logs_for_payload_without_handler_produces_empty_payload
     assert payload == ''
 
 
+def test_initialize_monitor_creates_log_handler_with_ping_body_limit():
+    ping_body_limit = 100
+    monitoring_log_level = 1
+
+    flexmock(module).should_receive('Forgetful_buffering_handler').with_args(
+        ping_body_limit - len(module.PAYLOAD_TRUNCATION_INDICATOR), monitoring_log_level
+    ).once()
+
+    module.initialize_monitor(
+        {'ping_body_limit': ping_body_limit}, 'test.yaml', monitoring_log_level, dry_run=False
+    )
+
+
+def test_initialize_monitor_creates_log_handler_with_default_ping_body_limit():
+    monitoring_log_level = 1
+
+    flexmock(module).should_receive('Forgetful_buffering_handler').with_args(
+        module.DEFAULT_PING_BODY_LIMIT_BYTES - len(module.PAYLOAD_TRUNCATION_INDICATOR),
+        monitoring_log_level,
+    ).once()
+
+    module.initialize_monitor({}, 'test.yaml', monitoring_log_level, dry_run=False)
+
+
+def test_initialize_monitor_creates_log_handler_with_zero_ping_body_limit():
+    ping_body_limit = 0
+    monitoring_log_level = 1
+
+    flexmock(module).should_receive('Forgetful_buffering_handler').with_args(
+        ping_body_limit, monitoring_log_level
+    ).once()
+
+    module.initialize_monitor(
+        {'ping_body_limit': ping_body_limit}, 'test.yaml', monitoring_log_level, dry_run=False
+    )
+
+
+def test_initialize_monitor_creates_log_handler_when_send_logs_true():
+    flexmock(module).should_receive('Forgetful_buffering_handler').once()
+
+    module.initialize_monitor(
+        {'send_logs': True}, 'test.yaml', monitoring_log_level=1, dry_run=False
+    )
+
+
+def test_initialize_monitor_bails_when_send_logs_false():
+    flexmock(module).should_receive('Forgetful_buffering_handler').never()
+
+    module.initialize_monitor(
+        {'send_logs': False}, 'test.yaml', monitoring_log_level=1, dry_run=False
+    )
+
+
 def test_ping_monitor_hits_ping_url_for_start_state():
     flexmock(module).should_receive('Forgetful_buffering_handler')
-    ping_url = 'https://example.com'
+    hook_config = {'ping_url': 'https://example.com'}
     flexmock(module.requests).should_receive('post').with_args(
-        '{}/{}'.format(ping_url, 'start'), data=''.encode('utf-8')
+        'https://example.com/start', data=''.encode('utf-8')
     )
 
     module.ping_monitor(
-        ping_url,
+        hook_config,
         'config.yaml',
         state=module.monitor.State.START,
         monitoring_log_level=1,
@@ -77,15 +139,15 @@ def test_ping_monitor_hits_ping_url_for_start_state():
 
 
 def test_ping_monitor_hits_ping_url_for_finish_state():
-    ping_url = 'https://example.com'
+    hook_config = {'ping_url': 'https://example.com'}
     payload = 'data'
     flexmock(module).should_receive('format_buffered_logs_for_payload').and_return(payload)
     flexmock(module.requests).should_receive('post').with_args(
-        ping_url, data=payload.encode('utf-8')
+        'https://example.com', data=payload.encode('utf-8')
     )
 
     module.ping_monitor(
-        ping_url,
+        hook_config,
         'config.yaml',
         state=module.monitor.State.FINISH,
         monitoring_log_level=1,
@@ -94,15 +156,15 @@ def test_ping_monitor_hits_ping_url_for_finish_state():
 
 
 def test_ping_monitor_hits_ping_url_for_fail_state():
-    ping_url = 'https://example.com'
+    hook_config = {'ping_url': 'https://example.com'}
     payload = 'data'
     flexmock(module).should_receive('format_buffered_logs_for_payload').and_return(payload)
     flexmock(module.requests).should_receive('post').with_args(
-        '{}/{}'.format(ping_url, 'fail'), data=payload.encode('utf')
+        'https://example.com/fail', data=payload.encode('utf')
     )
 
     module.ping_monitor(
-        ping_url,
+        hook_config,
         'config.yaml',
         state=module.monitor.State.FAIL,
         monitoring_log_level=1,
@@ -111,15 +173,15 @@ def test_ping_monitor_hits_ping_url_for_fail_state():
 
 
 def test_ping_monitor_with_ping_uuid_hits_corresponding_url():
-    ping_uuid = 'abcd-efgh-ijkl-mnop'
+    hook_config = {'ping_url': 'abcd-efgh-ijkl-mnop'}
     payload = 'data'
     flexmock(module).should_receive('format_buffered_logs_for_payload').and_return(payload)
     flexmock(module.requests).should_receive('post').with_args(
-        'https://hc-ping.com/{}'.format(ping_uuid), data=payload.encode('utf-8')
+        'https://hc-ping.com/{}'.format(hook_config['ping_url']), data=payload.encode('utf-8')
     )
 
     module.ping_monitor(
-        ping_uuid,
+        hook_config,
         'config.yaml',
         state=module.monitor.State.FINISH,
         monitoring_log_level=1,
@@ -129,13 +191,60 @@ def test_ping_monitor_with_ping_uuid_hits_corresponding_url():
 
 def test_ping_monitor_dry_run_does_not_hit_ping_url():
     flexmock(module).should_receive('Forgetful_buffering_handler')
-    ping_url = 'https://example.com'
+    hook_config = {'ping_url': 'https://example.com'}
     flexmock(module.requests).should_receive('post').never()
 
     module.ping_monitor(
-        ping_url,
+        hook_config,
         'config.yaml',
         state=module.monitor.State.START,
         monitoring_log_level=1,
         dry_run=True,
     )
+
+
+def test_ping_monitor_does_not_hit_ping_url_when_states_not_matching():
+    flexmock(module).should_receive('Forgetful_buffering_handler')
+    hook_config = {'ping_url': 'https://example.com', 'states': ['finish']}
+    flexmock(module.requests).should_receive('post').never()
+
+    module.ping_monitor(
+        hook_config,
+        'config.yaml',
+        state=module.monitor.State.START,
+        monitoring_log_level=1,
+        dry_run=True,
+    )
+
+
+def test_ping_monitor_hits_ping_url_when_states_matching():
+    flexmock(module).should_receive('Forgetful_buffering_handler')
+    hook_config = {'ping_url': 'https://example.com', 'states': ['start', 'finish']}
+    flexmock(module.requests).should_receive('post').with_args(
+        'https://example.com/start', data=''.encode('utf-8')
+    )
+
+    module.ping_monitor(
+        hook_config,
+        'config.yaml',
+        state=module.monitor.State.START,
+        monitoring_log_level=1,
+        dry_run=False,
+    )
+
+
+def test_ping_monitor_with_connection_error_does_not_raise():
+    flexmock(module).should_receive('Forgetful_buffering_handler')
+    flexmock(module.logger).should_receive('warning')
+    hook_config = {'ping_url': 'https://example.com'}
+    flexmock(module.requests).should_receive('post').with_args(
+        'https://example.com/start', data=''.encode('utf-8')
+    ).and_raise(module.requests.exceptions.ConnectionError)
+
+    module.ping_monitor(
+        hook_config,
+        'config.yaml',
+        state=module.monitor.State.START,
+        monitoring_log_level=1,
+        dry_run=False,
+    )

tests/unit/hooks/test_pagerduty.py

@@ -7,7 +7,11 @@ def test_ping_monitor_ignores_start_state():
     flexmock(module.requests).should_receive('post').never()
 
     module.ping_monitor(
-        'abc123', 'config.yaml', module.monitor.State.START, monitoring_log_level=1, dry_run=False
+        {'integration_key': 'abc123'},
+        'config.yaml',
+        module.monitor.State.START,
+        monitoring_log_level=1,
+        dry_run=False,
     )
 
 
@@ -15,7 +19,11 @@ def test_ping_monitor_ignores_finish_state():
     flexmock(module.requests).should_receive('post').never()
 
     module.ping_monitor(
-        'abc123', 'config.yaml', module.monitor.State.FINISH, monitoring_log_level=1, dry_run=False
+        {'integration_key': 'abc123'},
+        'config.yaml',
+        module.monitor.State.FINISH,
+        monitoring_log_level=1,
+        dry_run=False,
     )
 
 
@@ -23,7 +31,11 @@ def test_ping_monitor_calls_api_for_fail_state():
     flexmock(module.requests).should_receive('post')
 
     module.ping_monitor(
-        'abc123', 'config.yaml', module.monitor.State.FAIL, monitoring_log_level=1, dry_run=False
+        {'integration_key': 'abc123'},
+        'config.yaml',
+        module.monitor.State.FAIL,
+        monitoring_log_level=1,
+        dry_run=False,
     )
 
 
@@ -31,5 +43,24 @@ def test_ping_monitor_dry_run_does_not_call_api():
     flexmock(module.requests).should_receive('post').never()
 
     module.ping_monitor(
-        'abc123', 'config.yaml', module.monitor.State.FAIL, monitoring_log_level=1, dry_run=True
+        {'integration_key': 'abc123'},
+        'config.yaml',
+        module.monitor.State.FAIL,
+        monitoring_log_level=1,
+        dry_run=True,
+    )
+
+
+def test_ping_monitor_with_connection_error_does_not_raise():
+    flexmock(module.requests).should_receive('post').and_raise(
+        module.requests.exceptions.ConnectionError
+    )
+    flexmock(module.logger).should_receive('warning')
+
+    module.ping_monitor(
+        {'integration_key': 'abc123'},
+        'config.yaml',
+        module.monitor.State.FAIL,
+        monitoring_log_level=1,
+        dry_run=False,
     )

tests/unit/test_signals.py

@@ -0,0 +1,40 @@
+from flexmock import flexmock
+
+from borgmatic import signals as module
+
+
+def test_handle_signal_forwards_to_subprocesses():
+    signal_number = 100
+    frame = flexmock(f_back=flexmock(f_code=flexmock(co_name='something')))
+    process_group = flexmock()
+    flexmock(module.os).should_receive('getpgrp').and_return(process_group)
+    flexmock(module.os).should_receive('killpg').with_args(process_group, signal_number).once()
+
+    module.handle_signal(signal_number, frame)
+
+
+def test_handle_signal_bails_on_recursion():
+    signal_number = 100
+    frame = flexmock(f_back=flexmock(f_code=flexmock(co_name='handle_signal')))
+    flexmock(module.os).should_receive('getpgrp').never()
+    flexmock(module.os).should_receive('killpg').never()
+
+    module.handle_signal(signal_number, frame)
+
+
+def test_handle_signal_exits_on_sigterm():
+    signal_number = module.signal.SIGTERM
+    frame = flexmock(f_back=flexmock(f_code=flexmock(co_name='something')))
+    flexmock(module.os).should_receive('getpgrp').and_return(flexmock)
+    flexmock(module.os).should_receive('killpg')
+    flexmock(module.sys).should_receive('exit').with_args(
+        module.EXIT_CODE_FROM_SIGNAL + signal_number
+    ).once()
+
+    module.handle_signal(signal_number, frame)
+
+
+def test_configure_signals_installs_signal_handlers():
+    flexmock(module.signal).should_receive('signal').at_least().once()
+
+    module.configure_signals()