Document validate-borgmatic-config and add a few tests.

Useful when generating the borgmatic configuration file with
configuration management and before moving the generated file in place
checking if it is actually valid.

.drone.yml

@@ -11,7 +11,7 @@ pipeline:
 matrix:
   ALPINE_VERSION:
     - 3.7
-    - 3.8
+    - 3.9
   PYTHON_VERSION:
     - 3.5
     - 3.6

AUTHORS

@@ -7,6 +7,6 @@ Johannes Feichtner: Support for user hooks
 Michele Lazzeri: Custom archive names
 Nick Whyte: Support prefix filtering for archive consistency checks
 newtonne: Read encryption password from external file
-Robin `ypid` Schneider: Support additional options of Borg
+Robin `ypid` Schneider: Support additional options of Borg and add validate-borgmatic-config command
 Scott Squires: Custom archive names
 Thomas LÉVEIL: Support for a keep_minutely prune option. Support for the --json option

NEWS

@@ -1,3 +1,10 @@
+1.3.3
+ * Add validate-borgmatic-config command, useful for validating borgmatic config generated by
+   configuration management or even edited by hand.
+
+1.3.2
+ * #160: Fix for hooks executing when using --dry-run. Now hooks are skipped during a dry run.
+
 1.3.1
  * #155: Fix for invalid JSON output when using multiple borgmatic configuration files.
  * #157: Fix for seemingly random filename ordering when running through a directory of

borgmatic/commands/borgmatic.py

@@ -272,7 +272,9 @@ def run_configuration(config_filename, config, args):  # pragma: no cover
         borg_environment.initialize(storage)
 
         if args.create:
-            hook.execute_hook(hooks.get('before_backup'), config_filename, 'pre-backup')
+            hook.execute_hook(
+                hooks.get('before_backup'), config_filename, 'pre-backup', args.dry_run
+            )
 
         for repository_path in location['repositories']:
             yield from run_actions(
@@ -287,9 +289,11 @@ def run_configuration(config_filename, config, args):  # pragma: no cover
             )
 
         if args.create:
-            hook.execute_hook(hooks.get('after_backup'), config_filename, 'post-backup')
+            hook.execute_hook(
+                hooks.get('after_backup'), config_filename, 'post-backup', args.dry_run
+            )
     except (OSError, CalledProcessError):
-        hook.execute_hook(hooks.get('on_error'), config_filename, 'on-error')
+        hook.execute_hook(hooks.get('on_error'), config_filename, 'on-error', args.dry_run)
         raise
 
 

borgmatic/commands/hook.py

@@ -5,20 +5,30 @@ import subprocess
 logger = logging.getLogger(__name__)
 
 
-def execute_hook(commands, config_filename, description):
+def execute_hook(commands, config_filename, description, dry_run):
+    '''
+
+    Given a list of hook commands to execute, a config filename, 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.
+    '''
     if not commands:
         logger.debug('{}: No commands to run for {} hook'.format(config_filename, description))
         return
 
+    dry_run_label = ' (dry run; not actually running hooks)' if dry_run else ''
+
     if len(commands) == 1:
-        logger.info('{}: Running command for {} hook'.format(config_filename, description))
+        logger.info(
+            '{}: Running command for {} hook{}'.format(config_filename, description, dry_run_label)
+        )
     else:
         logger.info(
-            '{}: Running {} commands for {} hook'.format(
-                config_filename, len(commands), description
+            '{}: Running {} commands for {} hook{}'.format(
+                config_filename, len(commands), description, dry_run_label
             )
         )
 
     for command in commands:
         logger.debug('{}: Hook command: {}'.format(config_filename, command))
-        subprocess.check_call(command, shell=True)
+        if not dry_run:
+            subprocess.check_call(command, shell=True)

borgmatic/commands/validate_config.py

@@ -0,0 +1,56 @@
+from argparse import ArgumentParser
+import sys
+import logging
+
+from borgmatic.config import collect, validate
+
+logger = logging.getLogger(__name__)
+
+
+def parse_arguments(*arguments):
+    '''
+    Given command-line arguments with which this script was invoked, parse the arguments and return
+    them as an ArgumentParser instance.
+    '''
+    config_paths = collect.get_default_config_paths()
+
+    parser = ArgumentParser(description='Validate borgmatic configuration file(s).')
+    parser.add_argument(
+        '-c',
+        '--config',
+        nargs='+',
+        dest='config_paths',
+        default=config_paths,
+        help='Configuration filenames or directories, defaults to: {}'.format(
+            ' '.join(config_paths)
+        ),
+    )
+
+    return parser.parse_args(arguments)
+
+
+def main():  # pragma: no cover
+    args = parse_arguments(*sys.argv[1:])
+
+    logging.basicConfig(level=logging.INFO, format='%(message)s')
+
+    config_filenames = tuple(collect.collect_config_filenames(args.config_paths))
+    if len(config_filenames) == 0:
+        logger.critical('No files to validate found')
+        sys.exit(1)
+
+    found_issues = False
+    for config_filename in config_filenames:
+        try:
+            validate.parse_configuration(config_filename, validate.schema_filename())
+        except (ValueError, OSError, validate.Validation_error) as error:
+            logging.critical('{}: Error parsing configuration file'.format(config_filename))
+            logging.critical(error)
+            found_issues = True
+
+    if found_issues:
+        sys.exit(1)
+    else:
+        logger.info(
+            'All given configuration files are valid: {}'.format(', '.join(config_filenames))
+        )

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

@@ -76,7 +76,21 @@ FAQ](http://borgbackup.readthedocs.io/en/stable/faq.html#how-can-i-specify-the-e
 for more info.
 
 
-###
+### Validation
+
+If you'd like to validate that your borgmatic configuration is valid, the
+following command is available for that:
+
+```bash
+sudo validate-borgmatic-config
+```
+
+This command's exit status (`$?` in Bash) is zero when configuration is valid
+and non-zero otherwise.
+
+Validating configuration can be useful if you generate your configuration
+files via configuration management, or you just want to double check that your
+hand edits are valid.
 
 
 ## Initialization

setup.py

@@ -1,7 +1,7 @@
 from setuptools import setup, find_packages
 
 
-VERSION = '1.3.1'
+VERSION = '1.3.3'
 
 
 setup(
@@ -26,6 +26,7 @@ setup(
             'borgmatic = borgmatic.commands.borgmatic:main',
             'upgrade-borgmatic-config = borgmatic.commands.convert_config:main',
             'generate-borgmatic-config = borgmatic.commands.generate_config:main',
+            'validate-borgmatic-config = borgmatic.commands.validate_config:main',
         ]
     },
     obsoletes=['atticmatic'],

tests/end-to-end/test_validate_config.py

@@ -0,0 +1,36 @@
+import os
+import subprocess
+import tempfile
+
+
+def test_validate_config_command_with_valid_configuration_succeeds():
+    with tempfile.TemporaryDirectory() as temporary_directory:
+        config_path = os.path.join(temporary_directory, 'test.yaml')
+
+        subprocess.check_call(
+            'generate-borgmatic-config --destination {}'.format(config_path).split(' ')
+        )
+        exit_code = subprocess.call(
+            'validate-borgmatic-config --config {}'.format(config_path).split(' ')
+        )
+
+        assert exit_code == 0
+
+
+def test_validate_config_command_with_invalid_configuration_fails():
+    with tempfile.TemporaryDirectory() as temporary_directory:
+        config_path = os.path.join(temporary_directory, 'test.yaml')
+
+        subprocess.check_call(
+            'generate-borgmatic-config --destination {}'.format(config_path).split(' ')
+        )
+        config = open(config_path).read().replace('keep_daily: 7', 'keep_daily: "7"')
+        config_file = open(config_path, 'w')
+        config_file.write(config)
+        config_file.close()
+
+        exit_code = subprocess.call(
+            'validate-borgmatic-config --config {}'.format(config_path).split(' ')
+        )
+
+        assert exit_code == 1

tests/integration/commands/test_validate_config.py

@@ -0,0 +1,20 @@
+from flexmock import flexmock
+
+from borgmatic.commands import validate_config as module
+
+
+def test_parse_arguments_with_no_arguments_uses_defaults():
+    config_paths = ['default']
+    flexmock(module.collect).should_receive('get_default_config_paths').and_return(config_paths)
+
+    parser = module.parse_arguments()
+
+    assert parser.config_paths == config_paths
+
+
+def test_parse_arguments_with_multiple_config_paths_parses_as_list():
+    flexmock(module.collect).should_receive('get_default_config_paths').and_return(['default'])
+
+    parser = module.parse_arguments('--config', 'myconfig', 'otherconfig')
+
+    assert parser.config_paths == ['myconfig', 'otherconfig']

tests/unit/commands/test_hook.py

@@ -7,7 +7,7 @@ def test_execute_hook_invokes_each_command():
     subprocess = flexmock(module.subprocess)
     subprocess.should_receive('check_call').with_args(':', shell=True).once()
 
-    module.execute_hook([':'], 'config.yaml', 'pre-backup')
+    module.execute_hook([':'], 'config.yaml', 'pre-backup', dry_run=False)
 
 
 def test_execute_hook_with_multiple_commands_invokes_each_command():
@@ -15,8 +15,15 @@ def test_execute_hook_with_multiple_commands_invokes_each_command():
     subprocess.should_receive('check_call').with_args(':', shell=True).once()
     subprocess.should_receive('check_call').with_args('true', shell=True).once()
 
-    module.execute_hook([':', 'true'], 'config.yaml', 'pre-backup')
+    module.execute_hook([':', 'true'], 'config.yaml', 'pre-backup', dry_run=False)
+
+
+def test_execute_hook_with_dry_run_skips_commands():
+    subprocess = flexmock(module.subprocess)
+    subprocess.should_receive('check_call').never()
+
+    module.execute_hook([':', 'true'], 'config.yaml', 'pre-backup', dry_run=True)
 
 
 def test_execute_hook_with_empty_commands_does_not_raise():
-    module.execute_hook([], 'config.yaml', 'post-backup')
+    module.execute_hook([], 'config.yaml', 'post-backup', dry_run=False)