Bump version for release.

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

.drone.yml

@@ -8,16 +8,38 @@ services:
     environment:
       POSTGRES_PASSWORD: test
       POSTGRES_DB: test
+  - name: postgresql2
+    image: docker.io/postgres:13.1-alpine
+    environment:
+      POSTGRES_PASSWORD: test2
+      POSTGRES_DB: test
+      POSTGRES_USER: postgres2
+    commands:
+      - docker-entrypoint.sh -p 5433
   - name: mysql
     image: docker.io/mariadb:10.5
     environment:
       MYSQL_ROOT_PASSWORD: test
       MYSQL_DATABASE: test
+  - name: mysql2
+    image: docker.io/mariadb:10.5
+    environment:
+      MYSQL_ROOT_PASSWORD: test2
+      MYSQL_DATABASE: test
+    commands:
+      - docker-entrypoint.sh --port=3307
   - name: mongodb
     image: docker.io/mongo:5.0.5
     environment:
       MONGO_INITDB_ROOT_USERNAME: root
       MONGO_INITDB_ROOT_PASSWORD: test
+  - name: mongodb2
+    image: docker.io/mongo:5.0.5
+    environment:
+      MONGO_INITDB_ROOT_USERNAME: root2
+      MONGO_INITDB_ROOT_PASSWORD: test2
+    commands:
+      - docker-entrypoint.sh --port=27018
 
 clone:
   skip_verify: true

.gitea/issue_template.md

@@ -1,35 +0,0 @@
-#### What I'm trying to do and why
-
-#### Steps to reproduce (if a bug)
-
-Include (sanitized) borgmatic configuration files if applicable.
-
-#### Actual behavior (if a bug)
-
-Include (sanitized) `--verbosity 2` output if applicable.
-
-#### Expected behavior (if a bug)
-
-#### Other notes / implementation ideas
-
-#### Environment
-
-**borgmatic version:** [version here]
-
-Use `sudo borgmatic --version` or `sudo pip show borgmatic | grep ^Version`
-
-**borgmatic installation method:** [e.g., Debian package, Docker container, etc.]
-
-**Borg version:** [version here]
-
-Use `sudo borg --version`
-
-**Python version:** [version here]
-
-Use `python3 --version`
-
-**Database version (if applicable):** [version here]
-
-Use `psql --version` or `mysql --version` on client and server.
-
-**operating system and version:** [OS here]

.gitea/issue_template/bug_template.yaml

@@ -0,0 +1,77 @@
+name: "Bug or question/support"
+about: "For filing a bug or getting support"
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What I'm trying to do and why
+    validations:
+      required: true
+  - type: textarea
+    id: repro_steps
+    attributes:
+      label: Steps to reproduce
+      description: Include (sanitized) borgmatic configuration files if applicable.
+    validations:
+      required: false
+  - type: textarea
+    id: actual_behavior
+    attributes:
+      label: Actual behavior
+      description: Include (sanitized) `--verbosity 2` output if applicable.
+    validations:
+      required: false
+  - type: textarea
+    id: expected_behavior
+    attributes:
+      label: Expected behavior
+    validations:
+      required: false
+  - type: textarea
+    id: notes
+    attributes:
+      label: Other notes / implementation ideas
+    validations:
+      required: false
+  - type: input
+    id: borgmatic_version
+    attributes:
+      label: borgmatic version
+      description: Use `sudo borgmatic --version` or `sudo pip show borgmatic | grep ^Version`
+    validations:
+      required: false
+  - type: input
+    id: borgmatic_install_method
+    attributes:
+      label: borgmatic installation method
+      description: e.g., pip install, Debian package, container, etc.
+    validations:
+      required: false
+  - type: input
+    id: borg_version
+    attributes:
+      label: Borg version
+      description: Use `sudo borg --version`
+    validations:
+      required: false
+  - type: input
+    id: python_version
+    attributes:
+      label: Python version
+      description: Use `python3 --version`
+    validations:
+      required: false
+  - type: input
+    id: database_version
+    attributes:
+      label: Database version (if applicable)
+      description: Use `psql --version` / `mysql --version` / `mongodump --version` / `sqlite3 --version`
+    validations:
+      required: false
+  - type: input
+    id: operating_system_version
+    attributes:
+      label: Operating system and version
+      description: On Linux, use `cat /etc/os-release`
+    validations:
+      required: false

.gitea/issue_template/config.yaml

@@ -0,0 +1 @@
+blank_issues_enabled: false

.gitea/issue_template/feature_template.yaml

@@ -0,0 +1,15 @@
+name: "Feature"
+about: "For filing a feature request or idea"
+body:
+  - type: textarea
+    id: request
+    attributes:
+      label: What I'd like to do and why
+    validations:
+      required: true
+  - type: textarea
+    id: notes
+    attributes:
+      label: Other notes / implementation ideas
+    validations:
+      required: false

NEWS

@@ -1,3 +1,59 @@
+1.8.0
+ * #575: BREAKING: For the "borgmatic borg" action, instead of implicitly injecting
+   repository/archive into the resulting Borg command-line, pass repository to Borg via an
+   environment variable and make archive available for explicit use in your commands. See the
+   documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/run-arbitrary-borg-commands/
+ * #719: Fix an error when running "borg key export" through borgmatic.
+ * #720: Fix an error when dumping a database and the "exclude_nodump" option is set.
+ * #724: Add "check_i_know_what_i_am_doing" option to bypass Borg confirmation prompt when running
+   "check --repair".
+ * When merging two configuration files, error gracefully if the two files do not adhere to the same
+   format.
+ * #721: Remove configuration sections ("location:", "storage:", "hooks:" etc.), while still keeping
+   deprecated support for them. Now, all options are at the same level, and you don't need to worry
+   about commenting/uncommenting section headers when you change an option (if you remove your
+   sections first).
+ * #721: BREAKING: The retention prefix and the consistency prefix can no longer have different
+   values (unless one is not set).
+ * #721: BREAKING: The storage umask and the hooks umask can no longer have different values (unless
+   one is not set).
+ * BREAKING: Flags like "--config" that previously took multiple values now need to be given once
+   per value, e.g. "--config first.yaml --config second.yaml" instead of "--config first.yaml
+   second.yaml". This prevents argument parsing errors on ambiguous commands.
+ * BREAKING: Remove the deprecated (and silently ignored) "--successful" flag on the "list" action,
+   as newer versions of Borg list successful (non-checkpoint) archives by default.
+ * All deprecated configuration option values now generate warning logs.
+ * Remove the deprecated (and non-functional) "--excludes" flag in favor of excludes within
+   configuration.
+ * Fix an error when logging too-long command output during error handling. Now, long command output
+   is truncated before logging.
+
+1.7.15
+ * #326: Add configuration options and command-line flags for backing up a database from one
+   location while restoring it somewhere else.
+ * #399: Add a documentation troubleshooting note for MySQL/MariaDB authentication errors.
+ * #529: Remove upgrade-borgmatic-config command for upgrading borgmatic 1.1.0 INI-style
+   configuration.
+ * #529: Deprecate generate-borgmatic-config in favor of new "config generate" action.
+ * #529: Deprecate validate-borgmatic-config in favor of new "config validate" action.
+ * #697, #712, #716: Extract borgmatic configuration from backup via new "config bootstrap"
+   action—even when borgmatic has no configuration yet!
+ * #669: Add sample systemd user service for running borgmatic as a non-root user.
+ * #711, #713: Fix an error when "data" check time files are accessed without getting upgraded
+   first.
+
+1.7.14
+ * #484: Add a new verbosity level (-2) to disable output entirely (for console, syslog, log file,
+   or monitoring), so not even errors are shown.
+ * #688: Tweak archive check probing logic to use the newest timestamp found when multiple exist.
+ * #659: Add Borg 2 date-based matching flags to various actions for archive selection.
+ * #703: Fix an error when loading the configuration schema on Fedora Linux.
+ * #704: Fix "check" action error when repository and archive checks are configured but the archive
+   check gets skipped due to the configured frequency.
+ * #706: Fix "--archive latest" on "list" and "info" actions that only worked on the first of
+   multiple configured repositories.
+
 1.7.13
  * #375: Restore particular PostgreSQL schemas from a database dump via "borgmatic restore --schema"
    flag. See the documentation for more information:

README.md

@@ -16,50 +16,41 @@ The canonical home of borgmatic is at <a href="https://torsion.org/borgmatic">ht
 Here's an example configuration file:
 
 ```yaml
-location:
-    # List of source directories to backup.
-    source_directories:
-        - /home
-        - /etc
+# List of source directories to backup.
+source_directories:
+    - /home
+    - /etc
 
-    # Paths of local or remote repositories to backup to.
-    repositories:
-        - path: ssh://k8pDxu32@k8pDxu32.repo.borgbase.com/./repo
-          label: borgbase
-        - path: /var/lib/backups/local.borg
-          label: local
+# Paths of local or remote repositories to backup to.
+repositories:
+    - path: ssh://k8pDxu32@k8pDxu32.repo.borgbase.com/./repo
+      label: borgbase
+    - path: /var/lib/backups/local.borg
+      label: local
 
-retention:
-    # Retention policy for how many backups to keep.
-    keep_daily: 7
-    keep_weekly: 4
-    keep_monthly: 6
+# Retention policy for how many backups to keep.
+keep_daily: 7
+keep_weekly: 4
+keep_monthly: 6
 
-consistency:
-    # List of checks to run to validate your backups.
-    checks:
-        - name: repository
-        - name: archives
-          frequency: 2 weeks
+# List of checks to run to validate your backups.
+checks:
+    - name: repository
+    - name: archives
+      frequency: 2 weeks
 
-hooks:
-    # Custom preparation scripts to run.
-    before_backup:
-        - prepare-for-backup.sh
+# Custom preparation scripts to run.
+before_backup:
+    - prepare-for-backup.sh
 
-    # Databases to dump and include in backups.
-    postgresql_databases:
-        - name: users
+# Databases to dump and include in backups.
+postgresql_databases:
+    - name: users
 
-    # Third-party services to notify you if backups aren't happening.
-    healthchecks: https://hc-ping.com/be067061-cf96-4412-8eae-62b0c50d6a8c
+# Third-party services to notify you if backups aren't happening.
+healthchecks: https://hc-ping.com/be067061-cf96-4412-8eae-62b0c50d6a8c
 ```
 
-Want to see borgmatic in action? Check out the <a
-href="https://asciinema.org/a/203761?autoplay=1" target="_blank">screencast</a>.
-
-<a href="https://asciinema.org/a/203761?autoplay=1" target="_blank"><img src="https://asciinema.org/a/203761.png" width="480"></a>
-
 borgmatic is powered by [Borg Backup](https://www.borgbackup.org/).
 
 ## Integrations
@@ -91,16 +82,15 @@ reference guides</a>.
 
 Need somewhere to store your encrypted off-site backups? The following hosting
 providers include specific support for Borg/borgmatic—and fund borgmatic
-development and hosting when you use these links to sign up. (These are
-referral links, but without any tracking scripts or cookies.)
+development and hosting when you use these referral links to sign up:
 
 <ul>
  <li class="referral"><a href="https://www.borgbase.com/?utm_source=borgmatic">BorgBase</a>: Borg hosting service with support for monitoring, 2FA, and append-only repos</li>
+ <li class="referral"><a href="https://hetzner.cloud/?ref=v9dOJ98Ic9I8">Hetzner</a>: A "storage box" that includes support for Borg</li>
 </ul>
 
-Additionally, [rsync.net](https://www.rsync.net/products/borg.html) and
-[Hetzner](https://www.hetzner.com/storage/storage-box) have compatible storage
-offerings, but do not currently fund borgmatic development or hosting.
+Additionally, rsync.net has a compatible storage offering, but does not fund
+borgmatic development or hosting.
 
 ## Support and contributing
 
@@ -121,10 +111,7 @@ issues.
 
 ### Social
 
-Check out the [Borg subreddit](https://www.reddit.com/r/BorgBackup/) for
-general Borg and borgmatic discussion and support.
-
-Also follow [borgmatic on Mastodon](https://fosstodon.org/@borgmatic).
+Follow [borgmatic on Mastodon](https://fosstodon.org/@borgmatic).
 
 
 ### Chat

borgmatic/actions/arguments.py

@@ -0,0 +1,9 @@
+import argparse
+
+
+def update_arguments(arguments, **updates):
+    '''
+    Given an argparse.Namespace instance of command-line arguments and one or more keyword argument
+    updates to perform, return a copy of the arguments with those updates applied.
+    '''
+    return argparse.Namespace(**dict(vars(arguments), **updates))

borgmatic/actions/borg.py

@@ -9,7 +9,7 @@ logger = logging.getLogger(__name__)
 
 def run_borg(
     repository,
-    storage,
+    config,
     local_borg_version,
     borg_arguments,
     global_arguments,
@@ -28,7 +28,7 @@ def run_borg(
         archive_name = borgmatic.borg.rlist.resolve_archive_name(
             repository['path'],
             borg_arguments.archive,
-            storage,
+            config,
             local_borg_version,
             global_arguments,
             local_path,
@@ -36,7 +36,7 @@ def run_borg(
         )
         borgmatic.borg.borg.run_arbitrary_borg(
             repository['path'],
-            storage,
+            config,
             local_borg_version,
             options=borg_arguments.options,
             archive=archive_name,

borgmatic/actions/break_lock.py

@@ -8,7 +8,7 @@ logger = logging.getLogger(__name__)
 
 def run_break_lock(
     repository,
-    storage,
+    config,
     local_borg_version,
     break_lock_arguments,
     global_arguments,
@@ -26,7 +26,7 @@ def run_break_lock(
         )
         borgmatic.borg.break_lock.break_lock(
             repository['path'],
-            storage,
+            config,
             local_borg_version,
             global_arguments,
             local_path=local_path,

borgmatic/actions/check.py

@@ -10,10 +10,7 @@ logger = logging.getLogger(__name__)
 def run_check(
     config_filename,
     repository,
-    location,
-    storage,
-    consistency,
-    hooks,
+    config,
     hook_context,
     local_borg_version,
     check_arguments,
@@ -30,8 +27,8 @@ def run_check(
         return
 
     borgmatic.hooks.command.execute_hook(
-        hooks.get('before_check'),
-        hooks.get('umask'),
+        config.get('before_check'),
+        config.get('umask'),
         config_filename,
         'pre-check',
         global_arguments.dry_run,
@@ -40,9 +37,7 @@ def run_check(
     logger.info(f'{repository.get("label", repository["path"])}: Running consistency checks')
     borgmatic.borg.check.check_archives(
         repository['path'],
-        location,
-        storage,
-        consistency,
+        config,
         local_borg_version,
         global_arguments,
         local_path=local_path,
@@ -53,8 +48,8 @@ def run_check(
         force=check_arguments.force,
     )
     borgmatic.hooks.command.execute_hook(
-        hooks.get('after_check'),
-        hooks.get('umask'),
+        config.get('after_check'),
+        config.get('umask'),
         config_filename,
         'post-check',
         global_arguments.dry_run,

borgmatic/actions/compact.py

@@ -11,9 +11,7 @@ logger = logging.getLogger(__name__)
 def run_compact(
     config_filename,
     repository,
-    storage,
-    retention,
-    hooks,
+    config,
     hook_context,
     local_borg_version,
     compact_arguments,
@@ -31,8 +29,8 @@ def run_compact(
         return
 
     borgmatic.hooks.command.execute_hook(
-        hooks.get('before_compact'),
-        hooks.get('umask'),
+        config.get('before_compact'),
+        config.get('umask'),
         config_filename,
         'pre-compact',
         global_arguments.dry_run,
@@ -45,7 +43,7 @@ def run_compact(
         borgmatic.borg.compact.compact_segments(
             global_arguments.dry_run,
             repository['path'],
-            storage,
+            config,
             local_borg_version,
             global_arguments,
             local_path=local_path,
@@ -59,8 +57,8 @@ def run_compact(
             f'{repository.get("label", repository["path"])}: Skipping compact (only available/needed in Borg 1.2+)'
         )
     borgmatic.hooks.command.execute_hook(
-        hooks.get('after_compact'),
-        hooks.get('umask'),
+        config.get('after_compact'),
+        config.get('umask'),
         config_filename,
         'post-compact',
         global_arguments.dry_run,

borgmatic/actions/config/bootstrap.py

@@ -0,0 +1,103 @@
+import json
+import logging
+import os
+
+import borgmatic.borg.extract
+import borgmatic.borg.rlist
+import borgmatic.config.validate
+import borgmatic.hooks.command
+from borgmatic.borg.state import DEFAULT_BORGMATIC_SOURCE_DIRECTORY
+
+logger = logging.getLogger(__name__)
+
+
+def get_config_paths(bootstrap_arguments, global_arguments, local_borg_version):
+    '''
+    Given:
+    The bootstrap arguments, which include the repository and archive name, borgmatic source directory,
+    destination directory, and whether to strip components.
+    The global arguments, which include the dry run flag
+    and the local borg version,
+    Return:
+    The config paths from the manifest.json file in the borgmatic source directory after extracting it from the
+    repository.
+
+    Raise ValueError if the manifest JSON is missing, can't be decoded, or doesn't contain the
+    expected configuration path data.
+    '''
+    borgmatic_source_directory = (
+        bootstrap_arguments.borgmatic_source_directory or DEFAULT_BORGMATIC_SOURCE_DIRECTORY
+    )
+    borgmatic_manifest_path = os.path.expanduser(
+        os.path.join(borgmatic_source_directory, 'bootstrap', 'manifest.json')
+    )
+    extract_process = borgmatic.borg.extract.extract_archive(
+        global_arguments.dry_run,
+        bootstrap_arguments.repository,
+        borgmatic.borg.rlist.resolve_archive_name(
+            bootstrap_arguments.repository,
+            bootstrap_arguments.archive,
+            {},
+            local_borg_version,
+            global_arguments,
+        ),
+        [borgmatic_manifest_path],
+        {},
+        local_borg_version,
+        global_arguments,
+        extract_to_stdout=True,
+    )
+
+    manifest_json = extract_process.stdout.read()
+    if not manifest_json:
+        raise ValueError(
+            'Cannot read configuration paths from archive due to missing bootstrap manifest'
+        )
+
+    try:
+        manifest_data = json.loads(manifest_json)
+    except json.JSONDecodeError as error:
+        raise ValueError(
+            f'Cannot read configuration paths from archive due to invalid bootstrap manifest JSON: {error}'
+        )
+
+    try:
+        return manifest_data['config_paths']
+    except KeyError:
+        raise ValueError(
+            'Cannot read configuration paths from archive due to invalid bootstrap manifest'
+        )
+
+
+def run_bootstrap(bootstrap_arguments, global_arguments, local_borg_version):
+    '''
+    Run the "bootstrap" action for the given repository.
+
+    Raise ValueError if the bootstrap configuration could not be loaded.
+    Raise CalledProcessError or OSError if Borg could not be run.
+    '''
+    manifest_config_paths = get_config_paths(
+        bootstrap_arguments, global_arguments, local_borg_version
+    )
+
+    logger.info(f"Bootstrapping config paths: {', '.join(manifest_config_paths)}")
+
+    borgmatic.borg.extract.extract_archive(
+        global_arguments.dry_run,
+        bootstrap_arguments.repository,
+        borgmatic.borg.rlist.resolve_archive_name(
+            bootstrap_arguments.repository,
+            bootstrap_arguments.archive,
+            {},
+            local_borg_version,
+            global_arguments,
+        ),
+        [config_path.lstrip(os.path.sep) for config_path in manifest_config_paths],
+        {},
+        local_borg_version,
+        global_arguments,
+        extract_to_stdout=False,
+        destination_path=bootstrap_arguments.destination,
+        strip_components=bootstrap_arguments.strip_components,
+        progress=bootstrap_arguments.progress,
+    )

borgmatic/actions/config/generate.py

@@ -0,0 +1,48 @@
+import logging
+
+import borgmatic.config.generate
+import borgmatic.config.validate
+import borgmatic.logger
+
+logger = logging.getLogger(__name__)
+
+
+def run_generate(generate_arguments, global_arguments):
+    '''
+    Given the generate arguments and the global arguments, each as an argparse.Namespace instance,
+    run the "generate" action.
+
+    Raise FileExistsError if a file already exists at the destination path and the generate
+    arguments do not have overwrite set.
+    '''
+    borgmatic.logger.add_custom_log_levels()
+    dry_run_label = ' (dry run; not actually writing anything)' if global_arguments.dry_run else ''
+
+    logger.answer(
+        f'Generating a configuration file at: {generate_arguments.destination_filename}{dry_run_label}'
+    )
+
+    borgmatic.config.generate.generate_sample_configuration(
+        global_arguments.dry_run,
+        generate_arguments.source_filename,
+        generate_arguments.destination_filename,
+        borgmatic.config.validate.schema_filename(),
+        overwrite=generate_arguments.overwrite,
+    )
+
+    if generate_arguments.source_filename:
+        logger.answer(
+            f'''
+Merged in the contents of configuration file at: {generate_arguments.source_filename}
+To review the changes made, run:
+
+    diff --unified {generate_arguments.source_filename} {generate_arguments.destination_filename}'''
+        )
+
+    logger.answer(
+        '''
+This includes all available configuration options with example values, the few
+required options as indicated. Please edit the file to suit your needs.
+
+If you ever need help: https://torsion.org/borgmatic/#issues'''
+    )

borgmatic/actions/config/validate.py

@@ -0,0 +1,25 @@
+import logging
+
+import borgmatic.config.generate
+import borgmatic.logger
+
+logger = logging.getLogger(__name__)
+
+
+def run_validate(validate_arguments, configs):
+    '''
+    Given the validate arguments as an argparse.Namespace instance and a dict of configuration
+    filename to corresponding parsed configuration, run the "validate" action.
+
+    Most of the validation is actually performed implicitly by the standard borgmatic configuration
+    loading machinery prior to here, so this function mainly exists to support additional validate
+    flags like "--show".
+    '''
+    borgmatic.logger.add_custom_log_levels()
+
+    if validate_arguments.show:
+        for config_path, config in configs.items():
+            if len(configs) > 1:
+                logger.answer('---')
+
+            logger.answer(borgmatic.config.generate.render_configuration(config))

borgmatic/actions/create.py

@@ -1,7 +1,14 @@
 import json
 import logging
+import os
+
+try:
+    import importlib_metadata
+except ModuleNotFoundError:  # pragma: nocover
+    import importlib.metadata as importlib_metadata
 
 import borgmatic.borg.create
+import borgmatic.borg.state
 import borgmatic.config.validate
 import borgmatic.hooks.command
 import borgmatic.hooks.dispatch
@@ -10,12 +17,39 @@ import borgmatic.hooks.dump
 logger = logging.getLogger(__name__)
 
 
+def create_borgmatic_manifest(config, config_paths, dry_run):
+    '''
+    Create a borgmatic manifest file to store the paths to the configuration files used to create
+    the archive.
+    '''
+    if dry_run:
+        return
+
+    borgmatic_source_directory = config.get(
+        'borgmatic_source_directory', borgmatic.borg.state.DEFAULT_BORGMATIC_SOURCE_DIRECTORY
+    )
+
+    borgmatic_manifest_path = os.path.expanduser(
+        os.path.join(borgmatic_source_directory, 'bootstrap', 'manifest.json')
+    )
+
+    if not os.path.exists(borgmatic_manifest_path):
+        os.makedirs(os.path.dirname(borgmatic_manifest_path), exist_ok=True)
+
+    with open(borgmatic_manifest_path, 'w') as config_list_file:
+        json.dump(
+            {
+                'borgmatic_version': importlib_metadata.version('borgmatic'),
+                'config_paths': config_paths,
+            },
+            config_list_file,
+        )
+
+
 def run_create(
     config_filename,
     repository,
-    location,
-    storage,
-    hooks,
+    config,
     hook_context,
     local_borg_version,
     create_arguments,
@@ -35,8 +69,8 @@ def run_create(
         return
 
     borgmatic.hooks.command.execute_hook(
-        hooks.get('before_backup'),
-        hooks.get('umask'),
+        config.get('before_backup'),
+        config.get('umask'),
         config_filename,
         'pre-backup',
         global_arguments.dry_run,
@@ -45,27 +79,25 @@ def run_create(
     logger.info(f'{repository.get("label", repository["path"])}: Creating archive{dry_run_label}')
     borgmatic.hooks.dispatch.call_hooks_even_if_unconfigured(
         'remove_database_dumps',
-        hooks,
+        config,
         repository['path'],
         borgmatic.hooks.dump.DATABASE_HOOK_NAMES,
-        location,
         global_arguments.dry_run,
     )
     active_dumps = borgmatic.hooks.dispatch.call_hooks(
         'dump_databases',
-        hooks,
+        config,
         repository['path'],
         borgmatic.hooks.dump.DATABASE_HOOK_NAMES,
-        location,
         global_arguments.dry_run,
     )
+    create_borgmatic_manifest(config, global_arguments.used_config_paths, global_arguments.dry_run)
     stream_processes = [process for processes in active_dumps.values() for process in processes]
 
     json_output = borgmatic.borg.create.create_archive(
         global_arguments.dry_run,
         repository['path'],
-        location,
-        storage,
+        config,
         local_borg_version,
         global_arguments,
         local_path=local_path,
@@ -81,15 +113,14 @@ def run_create(
 
     borgmatic.hooks.dispatch.call_hooks_even_if_unconfigured(
         'remove_database_dumps',
-        hooks,
+        config,
         config_filename,
         borgmatic.hooks.dump.DATABASE_HOOK_NAMES,
-        location,
         global_arguments.dry_run,
     )
     borgmatic.hooks.command.execute_hook(
-        hooks.get('after_backup'),
-        hooks.get('umask'),
+        config.get('after_backup'),
+        config.get('umask'),
         config_filename,
         'post-backup',
         global_arguments.dry_run,

borgmatic/actions/export_tar.py

@@ -9,7 +9,7 @@ logger = logging.getLogger(__name__)
 
 def run_export_tar(
     repository,
-    storage,
+    config,
     local_borg_version,
     export_tar_arguments,
     global_arguments,
@@ -31,7 +31,7 @@ def run_export_tar(
             borgmatic.borg.rlist.resolve_archive_name(
                 repository['path'],
                 export_tar_arguments.archive,
-                storage,
+                config,
                 local_borg_version,
                 global_arguments,
                 local_path,
@@ -39,7 +39,7 @@ def run_export_tar(
             ),
             export_tar_arguments.paths,
             export_tar_arguments.destination,
-            storage,
+            config,
             local_borg_version,
             global_arguments,
             local_path=local_path,

borgmatic/actions/extract.py

@@ -11,9 +11,7 @@ logger = logging.getLogger(__name__)
 def run_extract(
     config_filename,
     repository,
-    location,
-    storage,
-    hooks,
+    config,
     hook_context,
     local_borg_version,
     extract_arguments,
@@ -25,8 +23,8 @@ def run_extract(
     Run the "extract" action for the given repository.
     '''
     borgmatic.hooks.command.execute_hook(
-        hooks.get('before_extract'),
-        hooks.get('umask'),
+        config.get('before_extract'),
+        config.get('umask'),
         config_filename,
         'pre-extract',
         global_arguments.dry_run,
@@ -44,15 +42,14 @@ def run_extract(
             borgmatic.borg.rlist.resolve_archive_name(
                 repository['path'],
                 extract_arguments.archive,
-                storage,
+                config,
                 local_borg_version,
                 global_arguments,
                 local_path,
                 remote_path,
             ),
             extract_arguments.paths,
-            location,
-            storage,
+            config,
             local_borg_version,
             global_arguments,
             local_path=local_path,
@@ -62,8 +59,8 @@ def run_extract(
             progress=extract_arguments.progress,
         )
     borgmatic.hooks.command.execute_hook(
-        hooks.get('after_extract'),
-        hooks.get('umask'),
+        config.get('after_extract'),
+        config.get('umask'),
         config_filename,
         'post-extract',
         global_arguments.dry_run,

borgmatic/actions/info.py

@@ -1,6 +1,7 @@
 import json
 import logging
 
+import borgmatic.actions.arguments
 import borgmatic.borg.info
 import borgmatic.borg.rlist
 import borgmatic.config.validate
@@ -10,7 +11,7 @@ logger = logging.getLogger(__name__)
 
 def run_info(
     repository,
-    storage,
+    config,
     local_borg_version,
     info_arguments,
     global_arguments,
@@ -29,10 +30,10 @@ def run_info(
             logger.answer(
                 f'{repository.get("label", repository["path"])}: Displaying archive summary information'
             )
-        info_arguments.archive = borgmatic.borg.rlist.resolve_archive_name(
+        archive_name = borgmatic.borg.rlist.resolve_archive_name(
             repository['path'],
             info_arguments.archive,
-            storage,
+            config,
             local_borg_version,
             global_arguments,
             local_path,
@@ -40,9 +41,9 @@ def run_info(
         )
         json_output = borgmatic.borg.info.display_archives_info(
             repository['path'],
-            storage,
+            config,
             local_borg_version,
-            info_arguments,
+            borgmatic.actions.arguments.update_arguments(info_arguments, archive=archive_name),
             global_arguments,
             local_path,
             remote_path,

borgmatic/actions/list.py

@@ -1,6 +1,7 @@
 import json
 import logging
 
+import borgmatic.actions.arguments
 import borgmatic.borg.list
 import borgmatic.config.validate
 
@@ -9,7 +10,7 @@ logger = logging.getLogger(__name__)
 
 def run_list(
     repository,
-    storage,
+    config,
     local_borg_version,
     list_arguments,
     global_arguments,
@@ -29,10 +30,11 @@ def run_list(
                 logger.answer(f'{repository.get("label", repository["path"])}: Searching archives')
             elif not list_arguments.archive:
                 logger.answer(f'{repository.get("label", repository["path"])}: Listing archives')
-        list_arguments.archive = borgmatic.borg.rlist.resolve_archive_name(
+
+        archive_name = borgmatic.borg.rlist.resolve_archive_name(
             repository['path'],
             list_arguments.archive,
-            storage,
+            config,
             local_borg_version,
             global_arguments,
             local_path,
@@ -40,9 +42,9 @@ def run_list(
         )
         json_output = borgmatic.borg.list.list_archive(
             repository['path'],
-            storage,
+            config,
             local_borg_version,
-            list_arguments,
+            borgmatic.actions.arguments.update_arguments(list_arguments, archive=archive_name),
             global_arguments,
             local_path,
             remote_path,

borgmatic/actions/mount.py

@@ -9,7 +9,7 @@ logger = logging.getLogger(__name__)
 
 def run_mount(
     repository,
-    storage,
+    config,
     local_borg_version,
     mount_arguments,
     global_arguments,
@@ -34,17 +34,14 @@ def run_mount(
             borgmatic.borg.rlist.resolve_archive_name(
                 repository['path'],
                 mount_arguments.archive,
-                storage,
+                config,
                 local_borg_version,
                 global_arguments,
                 local_path,
                 remote_path,
             ),
-            mount_arguments.mount_point,
-            mount_arguments.paths,
-            mount_arguments.foreground,
-            mount_arguments.options,
-            storage,
+            mount_arguments,
+            config,
             local_borg_version,
             global_arguments,
             local_path=local_path,

borgmatic/actions/prune.py

@@ -10,9 +10,7 @@ logger = logging.getLogger(__name__)
 def run_prune(
     config_filename,
     repository,
-    storage,
-    retention,
-    hooks,
+    config,
     hook_context,
     local_borg_version,
     prune_arguments,
@@ -30,8 +28,8 @@ def run_prune(
         return
 
     borgmatic.hooks.command.execute_hook(
-        hooks.get('before_prune'),
-        hooks.get('umask'),
+        config.get('before_prune'),
+        config.get('umask'),
         config_filename,
         'pre-prune',
         global_arguments.dry_run,
@@ -41,18 +39,16 @@ def run_prune(
     borgmatic.borg.prune.prune_archives(
         global_arguments.dry_run,
         repository['path'],
-        storage,
-        retention,
+        config,
         local_borg_version,
+        prune_arguments,
         global_arguments,
         local_path=local_path,
         remote_path=remote_path,
-        stats=prune_arguments.stats,
-        list_archives=prune_arguments.list_archives,
     )
     borgmatic.hooks.command.execute_hook(
-        hooks.get('after_prune'),
-        hooks.get('umask'),
+        config.get('after_prune'),
+        config.get('umask'),
         config_filename,
         'post-prune',
         global_arguments.dry_run,

borgmatic/actions/rcreate.py

@@ -8,7 +8,7 @@ logger = logging.getLogger(__name__)
 
 def run_rcreate(
     repository,
-    storage,
+    config,
     local_borg_version,
     rcreate_arguments,
     global_arguments,
@@ -27,7 +27,7 @@ def run_rcreate(
     borgmatic.borg.rcreate.create_repository(
         global_arguments.dry_run,
         repository['path'],
-        storage,
+        config,
         local_borg_version,
         global_arguments,
         rcreate_arguments.encryption_mode,

borgmatic/actions/restore.py

@@ -18,12 +18,12 @@ UNSPECIFIED_HOOK = object()
 
 
 def get_configured_database(
-    hooks, archive_database_names, hook_name, database_name, configuration_database_name=None
+    config, archive_database_names, hook_name, database_name, configuration_database_name=None
 ):
     '''
-    Find the first database with the given hook name and database name in the configured hooks
-    dict and the given archive database names dict (from hook name to database names contained in
-    a particular backup archive). If UNSPECIFIED_HOOK is given as the hook name, search all database
+    Find the first database with the given hook name and database name in the configuration dict and
+    the given archive database names dict (from hook name to database names contained in a
+    particular backup archive). If UNSPECIFIED_HOOK is given as the hook name, search all database
     hooks for the named database. If a configuration database name is given, use that instead of the
     database name to lookup the database in the given hooks configuration.
 
@@ -33,9 +33,13 @@ def get_configured_database(
         configuration_database_name = database_name
 
     if hook_name == UNSPECIFIED_HOOK:
-        hooks_to_search = hooks
+        hooks_to_search = {
+            hook_name: value
+            for (hook_name, value) in config.items()
+            if hook_name in borgmatic.hooks.dump.DATABASE_HOOK_NAMES
+        }
     else:
-        hooks_to_search = {hook_name: hooks[hook_name]}
+        hooks_to_search = {hook_name: config[hook_name]}
 
     return next(
         (
@@ -58,9 +62,7 @@ def get_configured_hook_name_and_database(hooks, database_name):
 
 def restore_single_database(
     repository,
-    location,
-    storage,
-    hooks,
+    config,
     local_borg_version,
     global_arguments,
     local_path,
@@ -68,9 +70,11 @@ def restore_single_database(
     archive_name,
     hook_name,
     database,
+    connection_params,
 ):  # pragma: no cover
     '''
-    Given (among other things) an archive name, a database hook name, and a configured database
+    Given (among other things) an archive name, a database hook name, the hostname,
+    port, username and password as connection params, and a configured database
     configuration dict, restore that database from the archive.
     '''
     logger.info(
@@ -79,10 +83,9 @@ def restore_single_database(
 
     dump_pattern = borgmatic.hooks.dispatch.call_hooks(
         'make_database_dump_pattern',
-        hooks,
+        config,
         repository['path'],
         borgmatic.hooks.dump.DATABASE_HOOK_NAMES,
-        location,
         database['name'],
     )[hook_name]
 
@@ -92,8 +95,7 @@ def restore_single_database(
         repository=repository['path'],
         archive=archive_name,
         paths=borgmatic.hooks.dump.convert_glob_patterns_to_borg_patterns([dump_pattern]),
-        location_config=location,
-        storage_config=storage,
+        config=config,
         local_borg_version=local_borg_version,
         global_arguments=global_arguments,
         local_path=local_path,
@@ -107,33 +109,33 @@ def restore_single_database(
     # Run a single database restore, consuming the extract stdout (if any).
     borgmatic.hooks.dispatch.call_hooks(
         'restore_database_dump',
-        {hook_name: [database]},
+        config,
         repository['path'],
+        database['name'],
         borgmatic.hooks.dump.DATABASE_HOOK_NAMES,
-        location,
         global_arguments.dry_run,
         extract_process,
+        connection_params,
     )
 
 
 def collect_archive_database_names(
     repository,
     archive,
-    location,
-    storage,
+    config,
     local_borg_version,
     global_arguments,
     local_path,
     remote_path,
 ):
     '''
-    Given a local or remote repository path, a resolved archive name, a location configuration dict,
-    a storage configuration dict, the local Borg version, global_arguments an argparse.Namespace,
-    and local and remote Borg paths, query the archive for the names of databases it contains and
-    return them as a dict from hook name to a sequence of database names.
+    Given a local or remote repository path, a resolved archive name, a configuration dict, the
+    local Borg version, global_arguments an argparse.Namespace, and local and remote Borg paths,
+    query the archive for the names of databases it contains and return them as a dict from hook
+    name to a sequence of database names.
     '''
     borgmatic_source_directory = os.path.expanduser(
-        location.get(
+        config.get(
             'borgmatic_source_directory', borgmatic.borg.state.DEFAULT_BORGMATIC_SOURCE_DIRECTORY
         )
     ).lstrip('/')
@@ -143,7 +145,7 @@ def collect_archive_database_names(
     dump_paths = borgmatic.borg.list.capture_archive_listing(
         repository,
         archive,
-        storage,
+        config,
         local_borg_version,
         global_arguments,
         list_path=parent_dump_path,
@@ -246,9 +248,7 @@ def ensure_databases_found(restore_names, remaining_restore_names, found_names):
 
 def run_restore(
     repository,
-    location,
-    storage,
-    hooks,
+    config,
     local_borg_version,
     restore_arguments,
     global_arguments,
@@ -272,17 +272,16 @@ def run_restore(
 
     borgmatic.hooks.dispatch.call_hooks_even_if_unconfigured(
         'remove_database_dumps',
-        hooks,
+        config,
         repository['path'],
         borgmatic.hooks.dump.DATABASE_HOOK_NAMES,
-        location,
         global_arguments.dry_run,
     )
 
     archive_name = borgmatic.borg.rlist.resolve_archive_name(
         repository['path'],
         restore_arguments.archive,
-        storage,
+        config,
         local_borg_version,
         global_arguments,
         local_path,
@@ -291,8 +290,7 @@ def run_restore(
     archive_database_names = collect_archive_database_names(
         repository['path'],
         archive_name,
-        location,
-        storage,
+        config,
         local_borg_version,
         global_arguments,
         local_path,
@@ -301,11 +299,18 @@ def run_restore(
     restore_names = find_databases_to_restore(restore_arguments.databases, archive_database_names)
     found_names = set()
     remaining_restore_names = {}
+    connection_params = {
+        'hostname': restore_arguments.hostname,
+        'port': restore_arguments.port,
+        'username': restore_arguments.username,
+        'password': restore_arguments.password,
+        'restore_path': restore_arguments.restore_path,
+    }
 
     for hook_name, database_names in restore_names.items():
         for database_name in database_names:
             found_hook_name, found_database = get_configured_database(
-                hooks, archive_database_names, hook_name, database_name
+                config, archive_database_names, hook_name, database_name
             )
 
             if not found_database:
@@ -317,9 +322,7 @@ def run_restore(
             found_names.add(database_name)
             restore_single_database(
                 repository,
-                location,
-                storage,
-                hooks,
+                config,
                 local_borg_version,
                 global_arguments,
                 local_path,
@@ -327,14 +330,15 @@ def run_restore(
                 archive_name,
                 found_hook_name or hook_name,
                 dict(found_database, **{'schemas': restore_arguments.schemas}),
+                connection_params,
             )
 
-    # For any database that weren't found via exact matches in the hooks configuration, try to
-    # fallback to "all" entries.
+    # For any database that weren't found via exact matches in the configuration, try to fallback
+    # to "all" entries.
     for hook_name, database_names in remaining_restore_names.items():
         for database_name in database_names:
             found_hook_name, found_database = get_configured_database(
-                hooks, archive_database_names, hook_name, database_name, 'all'
+                config, archive_database_names, hook_name, database_name, 'all'
             )
 
             if not found_database:
@@ -346,9 +350,7 @@ def run_restore(
 
             restore_single_database(
                 repository,
-                location,
-                storage,
-                hooks,
+                config,
                 local_borg_version,
                 global_arguments,
                 local_path,
@@ -356,14 +358,14 @@ def run_restore(
                 archive_name,
                 found_hook_name or hook_name,
                 dict(database, **{'schemas': restore_arguments.schemas}),
+                connection_params,
             )
 
     borgmatic.hooks.dispatch.call_hooks_even_if_unconfigured(
         'remove_database_dumps',
-        hooks,
+        config,
         repository['path'],
         borgmatic.hooks.dump.DATABASE_HOOK_NAMES,
-        location,
         global_arguments.dry_run,
     )
 

borgmatic/actions/rinfo.py

@@ -9,7 +9,7 @@ logger = logging.getLogger(__name__)
 
 def run_rinfo(
     repository,
-    storage,
+    config,
     local_borg_version,
     rinfo_arguments,
     global_arguments,
@@ -31,7 +31,7 @@ def run_rinfo(
 
         json_output = borgmatic.borg.rinfo.display_repository_info(
             repository['path'],
-            storage,
+            config,
             local_borg_version,
             rinfo_arguments=rinfo_arguments,
             global_arguments=global_arguments,

borgmatic/actions/rlist.py

@@ -9,7 +9,7 @@ logger = logging.getLogger(__name__)
 
 def run_rlist(
     repository,
-    storage,
+    config,
     local_borg_version,
     rlist_arguments,
     global_arguments,
@@ -29,7 +29,7 @@ def run_rlist(
 
         json_output = borgmatic.borg.rlist.list_repository(
             repository['path'],
-            storage,
+            config,
             local_borg_version,
             rlist_arguments=rlist_arguments,
             global_arguments=global_arguments,

borgmatic/actions/transfer.py

@@ -7,7 +7,7 @@ logger = logging.getLogger(__name__)
 
 def run_transfer(
     repository,
-    storage,
+    config,
     local_borg_version,
     transfer_arguments,
     global_arguments,
@@ -23,7 +23,7 @@ def run_transfer(
     borgmatic.borg.transfer.transfer_archives(
         global_arguments.dry_run,
         repository['path'],
-        storage,
+        config,
         local_borg_version,
         transfer_arguments,
         global_arguments,

borgmatic/borg/borg.py

@@ -8,14 +8,12 @@ from borgmatic.execute import DO_NOT_CAPTURE, execute_command
 logger = logging.getLogger(__name__)
 
 
-REPOSITORYLESS_BORG_COMMANDS = {'serve', None}
 BORG_SUBCOMMANDS_WITH_SUBCOMMANDS = {'key', 'debug'}
-BORG_SUBCOMMANDS_WITHOUT_REPOSITORY = (('debug', 'info'), ('debug', 'convert-profile'), ())
 
 
 def run_arbitrary_borg(
     repository_path,
-    storage_config,
+    config,
     local_borg_version,
     options,
     archive=None,
@@ -23,12 +21,13 @@ def run_arbitrary_borg(
     remote_path=None,
 ):
     '''
-    Given a local or remote repository path, a storage config dict, the local Borg version, a
+    Given a local or remote repository path, a configuration dict, the local Borg version, a
     sequence of arbitrary command-line Borg options, and an optional archive name, run an arbitrary
-    Borg command on the given repository/archive.
+    Borg command, passing in REPOSITORY and ARCHIVE environment variables for optional use in the
+    command.
     '''
     borgmatic.logger.add_custom_log_levels()
-    lock_wait = storage_config.get('lock_wait', None)
+    lock_wait = config.get('lock_wait', None)
 
     try:
         options = options[1:] if options[0] == '--' else options
@@ -38,10 +37,7 @@ def run_arbitrary_borg(
         borg_command = tuple(options[:command_options_start_index])
         command_options = tuple(options[command_options_start_index:])
 
-        if (
-            borg_command
-            and borg_command[0] in borgmatic.commands.arguments.SUBPARSER_ALIASES.keys()
-        ):
+        if borg_command and borg_command[0] in borgmatic.commands.arguments.ACTION_ALIASES.keys():
             logger.warning(
                 f"Borg's {borg_command[0]} subcommand is supported natively by borgmatic. Try this instead: borgmatic {borg_command[0]}"
             )
@@ -49,29 +45,26 @@ def run_arbitrary_borg(
         borg_command = ()
         command_options = ()
 
-    if borg_command in BORG_SUBCOMMANDS_WITHOUT_REPOSITORY:
-        repository_archive_flags = ()
-    elif archive:
-        repository_archive_flags = flags.make_repository_archive_flags(
-            repository_path, archive, local_borg_version
-        )
-    else:
-        repository_archive_flags = flags.make_repository_flags(repository_path, local_borg_version)
-
     full_command = (
         (local_path,)
         + borg_command
-        + repository_archive_flags
-        + command_options
         + (('--info',) if logger.getEffectiveLevel() == logging.INFO else ())
         + (('--debug', '--show-rc') if logger.isEnabledFor(logging.DEBUG) else ())
         + flags.make_flags('remote-path', remote_path)
         + flags.make_flags('lock-wait', lock_wait)
+        + command_options
     )
 
     return execute_command(
         full_command,
         output_file=DO_NOT_CAPTURE,
         borg_local_path=local_path,
-        extra_environment=environment.make_environment(storage_config),
+        shell=True,
+        extra_environment=dict(
+            (environment.make_environment(config) or {}),
+            **{
+                'BORG_REPO': repository_path,
+                'ARCHIVE': archive if archive else '',
+            },
+        ),
     )

borgmatic/borg/break_lock.py

@@ -8,19 +8,19 @@ logger = logging.getLogger(__name__)
 
 def break_lock(
     repository_path,
-    storage_config,
+    config,
     local_borg_version,
     global_arguments,
     local_path='borg',
     remote_path=None,
 ):
     '''
-    Given a local or remote repository path, a storage configuration dict, the local Borg version,
-    an argparse.Namespace of global arguments, and optional local and remote Borg paths, break any
+    Given a local or remote repository path, a configuration dict, the local Borg version, an
+    argparse.Namespace of global arguments, and optional local and remote Borg paths, break any
     repository and cache locks leftover from Borg aborting.
     '''
-    umask = storage_config.get('umask', None)
-    lock_wait = storage_config.get('lock_wait', None)
+    umask = config.get('umask', None)
+    lock_wait = config.get('lock_wait', None)
 
     full_command = (
         (local_path, 'break-lock')
@@ -33,5 +33,5 @@ def break_lock(
         + flags.make_repository_flags(repository_path, local_borg_version)
     )
 
-    borg_environment = environment.make_environment(storage_config)
+    borg_environment = environment.make_environment(config)
     execute_command(full_command, borg_local_path=local_path, extra_environment=borg_environment)

borgmatic/borg/check.py

@@ -19,12 +19,12 @@ DEFAULT_CHECKS = (
 logger = logging.getLogger(__name__)
 
 
-def parse_checks(consistency_config, only_checks=None):
+def parse_checks(config, only_checks=None):
     '''
-    Given a consistency config with a "checks" sequence of dicts and an optional list of override
+    Given a configuration dict with a "checks" sequence of dicts and an optional list of override
     checks, return a tuple of named checks to run.
 
-    For example, given a retention config of:
+    For example, given a config of:
 
         {'checks': ({'name': 'repository'}, {'name': 'archives'})}
 
@@ -36,8 +36,7 @@ def parse_checks(consistency_config, only_checks=None):
     has a name of "disabled", return an empty tuple, meaning that no checks should be run.
     '''
     checks = only_checks or tuple(
-        check_config['name']
-        for check_config in (consistency_config.get('checks', None) or DEFAULT_CHECKS)
+        check_config['name'] for check_config in (config.get('checks', None) or DEFAULT_CHECKS)
     )
     checks = tuple(check.lower() for check in checks)
     if 'disabled' in checks:
@@ -90,23 +89,22 @@ def parse_frequency(frequency):
 
 
 def filter_checks_on_frequency(
-    location_config,
-    consistency_config,
+    config,
     borg_repository_id,
     checks,
     force,
     archives_check_id=None,
 ):
     '''
-    Given a location config, a consistency config with a "checks" sequence of dicts, a Borg
-    repository ID, a sequence of checks, whether to force checks to run, and an ID for the archives
-    check potentially being run (if any), filter down those checks based on the configured
-    "frequency" for each check as compared to its check time file.
+    Given a configuration dict with a "checks" sequence of dicts, a Borg repository ID, a sequence
+    of checks, whether to force checks to run, and an ID for the archives check potentially being
+    run (if any), filter down those checks based on the configured "frequency" for each check as
+    compared to its check time file.
 
     In other words, a check whose check time file's timestamp is too new (based on the configured
     frequency) will get cut from the returned sequence of checks. Example:
 
-    consistency_config = {
+    config = {
         'checks': [
             {
                 'name': 'archives',
@@ -115,9 +113,9 @@ def filter_checks_on_frequency(
         ]
     }
 
-    When this function is called with that consistency_config and "archives" in checks, "archives"
-    will get filtered out of the returned result if its check time file is newer than 2 weeks old,
-    indicating that it's not yet time to run that check again.
+    When this function is called with that config and "archives" in checks, "archives" will get
+    filtered out of the returned result if its check time file is newer than 2 weeks old, indicating
+    that it's not yet time to run that check again.
 
     Raise ValueError if a frequency cannot be parsed.
     '''
@@ -126,7 +124,7 @@ def filter_checks_on_frequency(
     if force:
         return tuple(filtered_checks)
 
-    for check_config in consistency_config.get('checks', DEFAULT_CHECKS):
+    for check_config in config.get('checks', DEFAULT_CHECKS):
         check = check_config['name']
         if checks and check not in checks:
             continue
@@ -135,9 +133,7 @@ def filter_checks_on_frequency(
         if not frequency_delta:
             continue
 
-        check_time = probe_for_check_time(
-            location_config, borg_repository_id, check, archives_check_id
-        )
+        check_time = probe_for_check_time(config, borg_repository_id, check, archives_check_id)
         if not check_time:
             continue
 
@@ -153,13 +149,11 @@ def filter_checks_on_frequency(
     return tuple(filtered_checks)
 
 
-def make_archive_filter_flags(
-    local_borg_version, storage_config, checks, check_last=None, prefix=None
-):
+def make_archive_filter_flags(local_borg_version, config, checks, check_last=None, prefix=None):
     '''
-    Given the local Borg version, a storage configuration dict, a parsed sequence of checks, the
-    check last value, and a consistency check prefix, transform the checks into tuple of
-    command-line flags for filtering archives in a check command.
+    Given the local Borg version, a configuration dict, a parsed sequence of checks, the check last
+    value, and a consistency check prefix, transform the checks into tuple of command-line flags for
+    filtering archives in a check command.
 
     If a check_last value is given and "archives" is in checks, then include a "--last" flag. And if
     a prefix value is given and "archives" is in checks, then include a "--match-archives" flag.
@@ -174,8 +168,8 @@ def make_archive_filter_flags(
             if prefix
             else (
                 flags.make_match_archives_flags(
-                    storage_config.get('match_archives'),
-                    storage_config.get('archive_name_format'),
+                    config.get('match_archives'),
+                    config.get('archive_name_format'),
                     local_borg_version,
                 )
             )
@@ -226,7 +220,7 @@ def make_check_flags(checks, archive_filter_flags):
     else:
         data_flags = ()
 
-    common_flags = archive_filter_flags + data_flags
+    common_flags = (archive_filter_flags if 'archives' in checks else ()) + data_flags
 
     if {'repository', 'archives'}.issubset(set(checks)):
         return common_flags
@@ -237,14 +231,14 @@ def make_check_flags(checks, archive_filter_flags):
     )
 
 
-def make_check_time_path(location_config, borg_repository_id, check_type, archives_check_id=None):
+def make_check_time_path(config, borg_repository_id, check_type, archives_check_id=None):
     '''
-    Given a location configuration dict, a Borg repository ID, the name of a check type
-    ("repository", "archives", etc.), and a unique hash of the archives filter flags, return a
-    path for recording that check's time (the time of that check last occurring).
+    Given a configuration dict, a Borg repository ID, the name of a check type ("repository",
+    "archives", etc.), and a unique hash of the archives filter flags, return a path for recording
+    that check's time (the time of that check last occurring).
     '''
     borgmatic_source_directory = os.path.expanduser(
-        location_config.get('borgmatic_source_directory', state.DEFAULT_BORGMATIC_SOURCE_DIRECTORY)
+        config.get('borgmatic_source_directory', state.DEFAULT_BORGMATIC_SOURCE_DIRECTORY)
     )
 
     if check_type in ('archives', 'data'):
@@ -287,11 +281,11 @@ def read_check_time(path):
         return None
 
 
-def probe_for_check_time(location_config, borg_repository_id, check, archives_check_id):
+def probe_for_check_time(config, borg_repository_id, check, archives_check_id):
     '''
-    Given a location configuration dict, a Borg repository ID, the name of a check type
-    ("repository", "archives", etc.), and a unique hash of the archives filter flags, return a
-    the corresponding check time or None if such a check time does not exist.
+    Given a configuration dict, a Borg repository ID, the name of a check type ("repository",
+    "archives", etc.), and a unique hash of the archives filter flags, return a the corresponding
+    check time or None if such a check time does not exist.
 
     When the check type is "archives" or "data", this function probes two different paths to find
     the check time, e.g.:
@@ -299,7 +293,7 @@ def probe_for_check_time(location_config, borg_repository_id, check, archives_ch
       ~/.borgmatic/checks/1234567890/archives/9876543210
       ~/.borgmatic/checks/1234567890/archives/all
 
-    ... and returns the modification time of the first file found (if any). The first path
+    ... and returns the maximum modification time of the files found (if any). The first path
     represents a more specific archives check time (a check on a subset of archives), and the second
     is a fallback to the last "all" archives check.
 
@@ -311,22 +305,22 @@ def probe_for_check_time(location_config, borg_repository_id, check, archives_ch
         read_check_time(group[0])
         for group in itertools.groupby(
             (
-                make_check_time_path(location_config, borg_repository_id, check, archives_check_id),
-                make_check_time_path(location_config, borg_repository_id, check),
+                make_check_time_path(config, borg_repository_id, check, archives_check_id),
+                make_check_time_path(config, borg_repository_id, check),
             )
         )
     )
 
     try:
-        return next(check_time for check_time in check_times if check_time)
-    except StopIteration:
+        return max(check_time for check_time in check_times if check_time)
+    except ValueError:
         return None
 
 
-def upgrade_check_times(location_config, borg_repository_id):
+def upgrade_check_times(config, borg_repository_id):
     '''
-    Given a location configuration dict and a Borg repository ID, upgrade any corresponding check
-    times on disk from old-style paths to new-style paths.
+    Given a configuration dict and a Borg repository ID, upgrade any corresponding check times on
+    disk from old-style paths to new-style paths.
 
     Currently, the only upgrade performed is renaming an archive or data check path that looks like:
 
@@ -337,12 +331,12 @@ def upgrade_check_times(location_config, borg_repository_id):
       ~/.borgmatic/checks/1234567890/archives/all
     '''
     for check_type in ('archives', 'data'):
-        new_path = make_check_time_path(location_config, borg_repository_id, check_type, 'all')
+        new_path = make_check_time_path(config, borg_repository_id, check_type, 'all')
         old_path = os.path.dirname(new_path)
         temporary_path = f'{old_path}.temp'
 
         if not os.path.isfile(old_path) and not os.path.isfile(temporary_path):
-            return
+            continue
 
         logger.debug(f'Upgrading archives check time from {old_path} to {new_path}')
 
@@ -357,9 +351,7 @@ def upgrade_check_times(location_config, borg_repository_id):
 
 def check_archives(
     repository_path,
-    location_config,
-    storage_config,
-    consistency_config,
+    config,
     local_borg_version,
     global_arguments,
     local_path='borg',
@@ -370,10 +362,9 @@ def check_archives(
     force=None,
 ):
     '''
-    Given a local or remote repository path, a storage config dict, a consistency config dict,
-    local/remote commands to run, whether to include progress information, whether to attempt a
-    repair, and an optional list of checks to use instead of configured checks, check the contained
-    Borg archives for consistency.
+    Given a local or remote repository path, a configuration dict, local/remote commands to run,
+    whether to include progress information, whether to attempt a repair, and an optional list of
+    checks to use instead of configured checks, check the contained Borg archives for consistency.
 
     If there are no consistency checks to run, skip running them.
 
@@ -383,7 +374,7 @@ def check_archives(
         borg_repository_id = json.loads(
             rinfo.display_repository_info(
                 repository_path,
-                storage_config,
+                config,
                 local_borg_version,
                 argparse.Namespace(json=True),
                 global_arguments,
@@ -394,21 +385,20 @@ def check_archives(
     except (json.JSONDecodeError, KeyError):
         raise ValueError(f'Cannot determine Borg repository ID for {repository_path}')
 
-    upgrade_check_times(location_config, borg_repository_id)
+    upgrade_check_times(config, borg_repository_id)
 
-    check_last = consistency_config.get('check_last', None)
-    prefix = consistency_config.get('prefix')
-    configured_checks = parse_checks(consistency_config, only_checks)
+    check_last = config.get('check_last', None)
+    prefix = config.get('prefix')
+    configured_checks = parse_checks(config, only_checks)
     lock_wait = None
-    extra_borg_options = storage_config.get('extra_borg_options', {}).get('check', '')
+    extra_borg_options = config.get('extra_borg_options', {}).get('check', '')
     archive_filter_flags = make_archive_filter_flags(
-        local_borg_version, storage_config, configured_checks, check_last, prefix
+        local_borg_version, config, configured_checks, check_last, prefix
     )
     archives_check_id = make_archives_check_id(archive_filter_flags)
 
     checks = filter_checks_on_frequency(
-        location_config,
-        consistency_config,
+        config,
         borg_repository_id,
         configured_checks,
         force,
@@ -416,7 +406,7 @@ def check_archives(
     )
 
     if set(checks).intersection({'repository', 'archives', 'data'}):
-        lock_wait = storage_config.get('lock_wait')
+        lock_wait = config.get('lock_wait')
 
         verbosity_flags = ()
         if logger.isEnabledFor(logging.INFO):
@@ -437,7 +427,7 @@ def check_archives(
             + flags.make_repository_flags(repository_path, local_borg_version)
         )
 
-        borg_environment = environment.make_environment(storage_config)
+        borg_environment = environment.make_environment(config)
 
         # The Borg repair option triggers an interactive prompt, which won't work when output is
         # captured. And progress messes with the terminal directly.
@@ -450,12 +440,12 @@ def check_archives(
 
         for check in checks:
             write_check_time(
-                make_check_time_path(location_config, borg_repository_id, check, archives_check_id)
+                make_check_time_path(config, borg_repository_id, check, archives_check_id)
             )
 
     if 'extract' in checks:
         extract.extract_last_archive_dry_run(
-            storage_config,
+            config,
             local_borg_version,
             global_arguments,
             repository_path,
@@ -463,4 +453,4 @@ def check_archives(
             local_path,
             remote_path,
         )
-        write_check_time(make_check_time_path(location_config, borg_repository_id, 'extract'))
+        write_check_time(make_check_time_path(config, borg_repository_id, 'extract'))

borgmatic/borg/compact.py

@@ -9,7 +9,7 @@ logger = logging.getLogger(__name__)
 def compact_segments(
     dry_run,
     repository_path,
-    storage_config,
+    config,
     local_borg_version,
     global_arguments,
     local_path='borg',
@@ -19,12 +19,12 @@ def compact_segments(
     threshold=None,
 ):
     '''
-    Given dry-run flag, a local or remote repository path, a storage config dict, and the local
-    Borg version, compact the segments in a repository.
+    Given dry-run flag, a local or remote repository path, a configuration dict, and the local Borg
+    version, compact the segments in a repository.
     '''
-    umask = storage_config.get('umask', None)
-    lock_wait = storage_config.get('lock_wait', None)
-    extra_borg_options = storage_config.get('extra_borg_options', {}).get('compact', '')
+    umask = config.get('umask', None)
+    lock_wait = config.get('lock_wait', None)
+    extra_borg_options = config.get('extra_borg_options', {}).get('compact', '')
 
     full_command = (
         (local_path, 'compact')
@@ -49,5 +49,5 @@ def compact_segments(
         full_command,
         output_log_level=logging.INFO,
         borg_local_path=local_path,
-        extra_environment=environment.make_environment(storage_config),
+        extra_environment=environment.make_environment(config),
     )

borgmatic/borg/create.py

@@ -146,12 +146,12 @@ def ensure_files_readable(*filename_lists):
         open(file_object).close()
 
 
-def make_pattern_flags(location_config, pattern_filename=None):
+def make_pattern_flags(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.
+    Given a configuration 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.
     '''
-    pattern_filenames = tuple(location_config.get('patterns_from') or ()) + (
+    pattern_filenames = tuple(config.get('patterns_from') or ()) + (
         (pattern_filename,) if pattern_filename else ()
     )
 
@@ -162,12 +162,12 @@ def make_pattern_flags(location_config, pattern_filename=None):
     )
 
 
-def make_exclude_flags(location_config, exclude_filename=None):
+def make_exclude_flags(config, exclude_filename=None):
     '''
-    Given a location config dict with various exclude options, and a filename containing any exclude
+    Given a configuration dict with various exclude options, and a filename containing any exclude
     patterns, return the corresponding Borg flags as a tuple.
     '''
-    exclude_filenames = tuple(location_config.get('exclude_from') or ()) + (
+    exclude_filenames = tuple(config.get('exclude_from') or ()) + (
         (exclude_filename,) if exclude_filename else ()
     )
     exclude_from_flags = tuple(
@@ -175,17 +175,15 @@ def make_exclude_flags(location_config, exclude_filename=None):
             ('--exclude-from', exclude_filename) for exclude_filename in exclude_filenames
         )
     )
-    caches_flag = ('--exclude-caches',) if location_config.get('exclude_caches') else ()
+    caches_flag = ('--exclude-caches',) if config.get('exclude_caches') else ()
     if_present_flags = tuple(
         itertools.chain.from_iterable(
             ('--exclude-if-present', if_present)
-            for if_present in location_config.get('exclude_if_present', ())
+            for if_present in config.get('exclude_if_present', ())
         )
     )
-    keep_exclude_tags_flags = (
-        ('--keep-exclude-tags',) if location_config.get('keep_exclude_tags') else ()
-    )
-    exclude_nodump_flags = ('--exclude-nodump',) if location_config.get('exclude_nodump') else ()
+    keep_exclude_tags_flags = ('--keep-exclude-tags',) if config.get('keep_exclude_tags') else ()
+    exclude_nodump_flags = ('--exclude-nodump',) if config.get('exclude_nodump') else ()
 
     return (
         exclude_from_flags
@@ -280,17 +278,21 @@ def collect_special_file_paths(
     create_command, local_path, working_directory, borg_environment, skip_directories
 ):
     '''
-    Given a Borg create command as a tuple, a local Borg path, a working directory, and a dict of
+    Given a Borg create command as a tuple, a local Borg path, a working directory, a dict of
     environment variables to pass to Borg, and a sequence of parent directories to skip, collect the
     paths for any special files (character devices, block devices, and named pipes / FIFOs) that
     Borg would encounter during a create. These are all paths that could cause Borg to hang if its
     --read-special flag is used.
     '''
+    # Omit "--exclude-nodump" from the Borg dry run command, because that flag causes Borg to open
+    # files including any named pipe we've created.
     paths_output = execute_command_and_capture_output(
-        create_command + ('--dry-run', '--list'),
+        tuple(argument for argument in create_command if argument != '--exclude-nodump')
+        + ('--dry-run', '--list'),
         capture_stderr=True,
         working_directory=working_directory,
         extra_environment=borg_environment,
+        borg_local_path=local_path,
     )
 
     paths = tuple(
@@ -323,8 +325,7 @@ def check_all_source_directories_exist(source_directories):
 def create_archive(
     dry_run,
     repository_path,
-    location_config,
-    storage_config,
+    config,
     local_borg_version,
     global_arguments,
     local_path='borg',
@@ -336,70 +337,70 @@ def create_archive(
     stream_processes=None,
 ):
     '''
-    Given vebosity/dry-run flags, a local or remote repository path, a location config dict, and a
-    storage config dict, create a Borg archive and return Borg's JSON output (if any).
+    Given vebosity/dry-run flags, a local or remote repository path, and a configuration dict,
+    create a Borg archive and return Borg's JSON output (if any).
 
     If a sequence of stream processes is given (instances of subprocess.Popen), then execute the
     create command while also triggering the given processes to produce output.
     '''
     borgmatic.logger.add_custom_log_levels()
     borgmatic_source_directories = expand_directories(
-        collect_borgmatic_source_directories(location_config.get('borgmatic_source_directory'))
+        collect_borgmatic_source_directories(config.get('borgmatic_source_directory'))
     )
-    if location_config.get('source_directories_must_exist', False):
-        check_all_source_directories_exist(location_config.get('source_directories'))
+    if config.get('source_directories_must_exist', False):
+        check_all_source_directories_exist(config.get('source_directories'))
     sources = deduplicate_directories(
         map_directories_to_devices(
             expand_directories(
-                tuple(location_config.get('source_directories', ())) + borgmatic_source_directories
+                tuple(config.get('source_directories', ()))
+                + borgmatic_source_directories
+                + tuple(global_arguments.used_config_paths)
             )
         ),
         additional_directory_devices=map_directories_to_devices(
-            expand_directories(pattern_root_directories(location_config.get('patterns')))
+            expand_directories(pattern_root_directories(config.get('patterns')))
         ),
     )
 
-    ensure_files_readable(location_config.get('patterns_from'), location_config.get('exclude_from'))
+    ensure_files_readable(config.get('patterns_from'), config.get('exclude_from'))
 
     try:
-        working_directory = os.path.expanduser(location_config.get('working_directory'))
+        working_directory = os.path.expanduser(config.get('working_directory'))
     except TypeError:
         working_directory = None
 
     pattern_file = (
-        write_pattern_file(location_config.get('patterns'), sources)
-        if location_config.get('patterns') or location_config.get('patterns_from')
+        write_pattern_file(config.get('patterns'), sources)
+        if config.get('patterns') or config.get('patterns_from')
         else None
     )
-    exclude_file = write_pattern_file(
-        expand_home_directories(location_config.get('exclude_patterns'))
-    )
-    checkpoint_interval = storage_config.get('checkpoint_interval', None)
-    checkpoint_volume = storage_config.get('checkpoint_volume', None)
-    chunker_params = storage_config.get('chunker_params', None)
-    compression = storage_config.get('compression', None)
-    upload_rate_limit = storage_config.get('upload_rate_limit', None)
-    umask = storage_config.get('umask', None)
-    lock_wait = storage_config.get('lock_wait', None)
+    exclude_file = write_pattern_file(expand_home_directories(config.get('exclude_patterns')))
+    checkpoint_interval = config.get('checkpoint_interval', None)
+    checkpoint_volume = config.get('checkpoint_volume', None)
+    chunker_params = config.get('chunker_params', None)
+    compression = config.get('compression', None)
+    upload_rate_limit = config.get('upload_rate_limit', None)
+    umask = config.get('umask', None)
+    lock_wait = config.get('lock_wait', None)
     list_filter_flags = make_list_filter_flags(local_borg_version, dry_run)
-    files_cache = location_config.get('files_cache')
-    archive_name_format = storage_config.get('archive_name_format', DEFAULT_ARCHIVE_NAME_FORMAT)
-    extra_borg_options = storage_config.get('extra_borg_options', {}).get('create', '')
+    files_cache = config.get('files_cache')
+    archive_name_format = config.get('archive_name_format', DEFAULT_ARCHIVE_NAME_FORMAT)
+    extra_borg_options = config.get('extra_borg_options', {}).get('create', '')
 
     if feature.available(feature.Feature.ATIME, local_borg_version):
-        atime_flags = ('--atime',) if location_config.get('atime') is True else ()
+        atime_flags = ('--atime',) if config.get('atime') is True else ()
     else:
-        atime_flags = ('--noatime',) if location_config.get('atime') is False else ()
+        atime_flags = ('--noatime',) if config.get('atime') is False else ()
 
     if feature.available(feature.Feature.NOFLAGS, local_borg_version):
-        noflags_flags = ('--noflags',) if location_config.get('flags') is False else ()
+        noflags_flags = ('--noflags',) if config.get('flags') is False else ()
     else:
-        noflags_flags = ('--nobsdflags',) if location_config.get('flags') is False else ()
+        noflags_flags = ('--nobsdflags',) if config.get('flags') is False else ()
 
     if feature.available(feature.Feature.NUMERIC_IDS, local_borg_version):
-        numeric_ids_flags = ('--numeric-ids',) if location_config.get('numeric_ids') else ()
+        numeric_ids_flags = ('--numeric-ids',) if config.get('numeric_ids') else ()
     else:
-        numeric_ids_flags = ('--numeric-owner',) if location_config.get('numeric_ids') else ()
+        numeric_ids_flags = ('--numeric-owner',) if config.get('numeric_ids') else ()
 
     if feature.available(feature.Feature.UPLOAD_RATELIMIT, local_borg_version):
         upload_ratelimit_flags = (
@@ -410,7 +411,7 @@ def create_archive(
             ('--remote-ratelimit', str(upload_rate_limit)) if upload_rate_limit else ()
         )
 
-    if stream_processes and location_config.get('read_special') is False:
+    if stream_processes and config.get('read_special') is False:
         logger.warning(
             f'{repository_path}: Ignoring configured "read_special" value of false, as true is needed for database hooks.'
         )
@@ -418,23 +419,19 @@ def create_archive(
     create_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(config, pattern_file.name if pattern_file else None)
+        + make_exclude_flags(config, exclude_file.name if exclude_file else None)
         + (('--checkpoint-interval', str(checkpoint_interval)) if checkpoint_interval else ())
         + (('--checkpoint-volume', str(checkpoint_volume)) if checkpoint_volume else ())
         + (('--chunker-params', chunker_params) if chunker_params else ())
         + (('--compression', compression) if compression else ())
         + upload_ratelimit_flags
-        + (
-            ('--one-file-system',)
-            if location_config.get('one_file_system') or stream_processes
-            else ()
-        )
+        + (('--one-file-system',) if config.get('one_file_system') or stream_processes else ())
         + numeric_ids_flags
         + atime_flags
-        + (('--noctime',) if location_config.get('ctime') is False else ())
-        + (('--nobirthtime',) if location_config.get('birthtime') is False else ())
-        + (('--read-special',) if location_config.get('read_special') or stream_processes else ())
+        + (('--noctime',) if config.get('ctime') is False else ())
+        + (('--nobirthtime',) if config.get('birthtime') is False else ())
+        + (('--read-special',) if config.get('read_special') or stream_processes else ())
         + noflags_flags
         + (('--files-cache', files_cache) if files_cache else ())
         + (('--remote-path', remote_path) if remote_path else ())
@@ -465,11 +462,11 @@ def create_archive(
     # the terminal directly.
     output_file = DO_NOT_CAPTURE if progress else None
 
-    borg_environment = environment.make_environment(storage_config)
+    borg_environment = environment.make_environment(config)
 
     # If database hooks are enabled (as indicated by streaming processes), exclude files that might
     # cause Borg to hang. But skip this if the user has explicitly set the "read_special" to True.
-    if stream_processes and not location_config.get('read_special'):
+    if stream_processes and not config.get('read_special'):
         logger.debug(f'{repository_path}: Collecting special file paths')
         special_file_paths = collect_special_file_paths(
             create_command,
@@ -485,11 +482,11 @@ def create_archive(
             )
             exclude_file = write_pattern_file(
                 expand_home_directories(
-                    tuple(location_config.get('exclude_patterns') or ()) + special_file_paths
+                    tuple(config.get('exclude_patterns') or ()) + special_file_paths
                 ),
                 pattern_file=exclude_file,
             )
-            create_command += make_exclude_flags(location_config, exclude_file.name)
+            create_command += make_exclude_flags(config, exclude_file.name)
 
     create_command += (
         (('--info',) if logger.getEffectiveLevel() == logging.INFO and not json else ())
@@ -514,6 +511,7 @@ def create_archive(
             create_command,
             working_directory=working_directory,
             extra_environment=borg_environment,
+            borg_local_path=local_path,
         )
     else:
         execute_command(

borgmatic/borg/environment.py

@@ -11,21 +11,25 @@ OPTION_TO_ENVIRONMENT_VARIABLE = {
     'temporary_directory': 'TMPDIR',
 }
 
-DEFAULT_BOOL_OPTION_TO_ENVIRONMENT_VARIABLE = {
+DEFAULT_BOOL_OPTION_TO_DOWNCASE_ENVIRONMENT_VARIABLE = {
     'relocated_repo_access_is_ok': 'BORG_RELOCATED_REPO_ACCESS_IS_OK',
     'unknown_unencrypted_repo_access_is_ok': 'BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK',
 }
 
+DEFAULT_BOOL_OPTION_TO_UPPERCASE_ENVIRONMENT_VARIABLE = {
+    'check_i_know_what_i_am_doing': 'BORG_CHECK_I_KNOW_WHAT_I_AM_DOING',
+}
 
-def make_environment(storage_config):
+
+def make_environment(config):
     '''
-    Given a borgmatic storage configuration dict, return its options converted to a Borg environment
+    Given a borgmatic configuration dict, return its options converted to a Borg environment
     variable dict.
     '''
     environment = {}
 
     for option_name, environment_variable_name in OPTION_TO_ENVIRONMENT_VARIABLE.items():
-        value = storage_config.get(option_name)
+        value = config.get(option_name)
 
         if value:
             environment[environment_variable_name] = str(value)
@@ -33,8 +37,15 @@ def make_environment(storage_config):
     for (
         option_name,
         environment_variable_name,
-    ) in DEFAULT_BOOL_OPTION_TO_ENVIRONMENT_VARIABLE.items():
-        value = storage_config.get(option_name, False)
+    ) in DEFAULT_BOOL_OPTION_TO_DOWNCASE_ENVIRONMENT_VARIABLE.items():
+        value = config.get(option_name, False)
         environment[environment_variable_name] = 'yes' if value else 'no'
 
+    for (
+        option_name,
+        environment_variable_name,
+    ) in DEFAULT_BOOL_OPTION_TO_UPPERCASE_ENVIRONMENT_VARIABLE.items():
+        value = config.get(option_name, False)
+        environment[environment_variable_name] = 'YES' if value else 'NO'
+
     return environment

borgmatic/borg/export_tar.py

@@ -13,7 +13,7 @@ def export_tar_archive(
     archive,
     paths,
     destination_path,
-    storage_config,
+    config,
     local_borg_version,
     global_arguments,
     local_path='borg',
@@ -24,16 +24,16 @@ def export_tar_archive(
 ):
     '''
     Given a dry-run flag, a local or remote repository path, an archive name, zero or more paths to
-    export from the archive, a destination path to export to, a storage configuration dict, the
-    local Borg version, optional local and remote Borg paths, an optional filter program, whether to
-    include per-file details, and an optional number of path components to strip, export the archive
-    into the given destination path as a tar-formatted file.
+    export from the archive, a destination path to export to, a configuration dict, the local Borg
+    version, optional local and remote Borg paths, an optional filter program, whether to include
+    per-file details, and an optional number of path components to strip, export the archive into
+    the given destination path as a tar-formatted file.
 
     If the destination path is "-", then stream the output to stdout instead of to a file.
     '''
     borgmatic.logger.add_custom_log_levels()
-    umask = storage_config.get('umask', None)
-    lock_wait = storage_config.get('lock_wait', None)
+    umask = config.get('umask', None)
+    lock_wait = config.get('lock_wait', None)
 
     full_command = (
         (local_path, 'export-tar')
@@ -70,5 +70,5 @@ def export_tar_archive(
         output_file=DO_NOT_CAPTURE if destination_path == '-' else None,
         output_log_level=output_log_level,
         borg_local_path=local_path,
-        extra_environment=environment.make_environment(storage_config),
+        extra_environment=environment.make_environment(config),
     )

borgmatic/borg/extract.py

@@ -10,7 +10,7 @@ logger = logging.getLogger(__name__)
 
 
 def extract_last_archive_dry_run(
-    storage_config,
+    config,
     local_borg_version,
     global_arguments,
     repository_path,
@@ -32,7 +32,7 @@ def extract_last_archive_dry_run(
         last_archive_name = rlist.resolve_archive_name(
             repository_path,
             'latest',
-            storage_config,
+            config,
             local_borg_version,
             global_arguments,
             local_path,
@@ -43,7 +43,7 @@ def extract_last_archive_dry_run(
         return
 
     list_flag = ('--list',) if logger.isEnabledFor(logging.DEBUG) else ()
-    borg_environment = environment.make_environment(storage_config)
+    borg_environment = environment.make_environment(config)
     full_extract_command = (
         (local_path, 'extract', '--dry-run')
         + (('--remote-path', remote_path) if remote_path else ())
@@ -66,8 +66,7 @@ def extract_archive(
     repository,
     archive,
     paths,
-    location_config,
-    storage_config,
+    config,
     local_borg_version,
     global_arguments,
     local_path='borg',
@@ -80,22 +79,22 @@ def extract_archive(
     '''
     Given a dry-run flag, a local or remote repository path, an archive name, zero or more paths to
     restore from the archive, the local Borg version string, an argparse.Namespace of global
-    arguments, location/storage configuration dicts, optional local and remote Borg paths, and an
-    optional destination path to extract to, extract the archive into the current directory.
+    arguments, a configuration dict, optional local and remote Borg paths, and an optional
+    destination path to extract to, extract the archive into the current directory.
 
     If extract to stdout is True, then start the extraction streaming to stdout, and return that
     extract process as an instance of subprocess.Popen.
     '''
-    umask = storage_config.get('umask', None)
-    lock_wait = storage_config.get('lock_wait', None)
+    umask = config.get('umask', None)
+    lock_wait = config.get('lock_wait', None)
 
     if progress and extract_to_stdout:
         raise ValueError('progress and extract_to_stdout cannot both be set')
 
     if feature.available(feature.Feature.NUMERIC_IDS, local_borg_version):
-        numeric_ids_flags = ('--numeric-ids',) if location_config.get('numeric_ids') else ()
+        numeric_ids_flags = ('--numeric-ids',) if config.get('numeric_ids') else ()
     else:
-        numeric_ids_flags = ('--numeric-owner',) if location_config.get('numeric_ids') else ()
+        numeric_ids_flags = ('--numeric-owner',) if config.get('numeric_ids') else ()
 
     if strip_components == 'all':
         if not paths:
@@ -127,7 +126,7 @@ def extract_archive(
         + (tuple(paths) if paths else ())
     )
 
-    borg_environment = environment.make_environment(storage_config)
+    borg_environment = environment.make_environment(config)
 
     # The progress output isn't compatible with captured and logged output, as progress messes with
     # the terminal directly.

borgmatic/borg/info.py

@@ -9,7 +9,7 @@ logger = logging.getLogger(__name__)
 
 def display_archives_info(
     repository_path,
-    storage_config,
+    config,
     local_borg_version,
     info_arguments,
     global_arguments,
@@ -17,12 +17,12 @@ def display_archives_info(
     remote_path=None,
 ):
     '''
-    Given a local or remote repository path, a storage config dict, the local Borg version, global
+    Given a local or remote repository path, a configuration dict, the local Borg version, global
     arguments as an argparse.Namespace, and the arguments to the info action, display summary
     information for Borg archives in the repository or return JSON summary information.
     '''
     borgmatic.logger.add_custom_log_levels()
-    lock_wait = storage_config.get('lock_wait', None)
+    lock_wait = config.get('lock_wait', None)
 
     full_command = (
         (local_path, 'info')
@@ -50,8 +50,8 @@ def display_archives_info(
                 flags.make_match_archives_flags(
                     info_arguments.match_archives
                     or info_arguments.archive
-                    or storage_config.get('match_archives'),
-                    storage_config.get('archive_name_format'),
+                    or config.get('match_archives'),
+                    config.get('archive_name_format'),
                     local_borg_version,
                 )
             )
@@ -65,12 +65,13 @@ def display_archives_info(
     if info_arguments.json:
         return execute_command_and_capture_output(
             full_command,
-            extra_environment=environment.make_environment(storage_config),
+            extra_environment=environment.make_environment(config),
+            borg_local_path=local_path,
         )
     else:
         execute_command(
             full_command,
             output_log_level=logging.ANSWER,
             borg_local_path=local_path,
-            extra_environment=environment.make_environment(storage_config),
+            extra_environment=environment.make_environment(config),
         )

borgmatic/borg/list.py

@@ -14,7 +14,6 @@ ARCHIVE_FILTER_FLAGS_MOVED_TO_RLIST = ('prefix', 'match_archives', 'sort_by', 'f
 MAKE_FLAGS_EXCLUDES = (
     'repository',
     'archive',
-    'successful',
     'paths',
     'find_paths',
 ) + ARCHIVE_FILTER_FLAGS_MOVED_TO_RLIST
@@ -22,7 +21,7 @@ MAKE_FLAGS_EXCLUDES = (
 
 def make_list_command(
     repository_path,
-    storage_config,
+    config,
     local_borg_version,
     list_arguments,
     global_arguments,
@@ -30,11 +29,11 @@ def make_list_command(
     remote_path=None,
 ):
     '''
-    Given a local or remote repository path, a storage config dict, the arguments to the list
-    action, and local and remote Borg paths, return a command as a tuple to list archives or paths
-    within an archive.
+    Given a local or remote repository path, a configuration dict, the arguments to the list action,
+    and local and remote Borg paths, return a command as a tuple to list archives or paths within an
+    archive.
     '''
-    lock_wait = storage_config.get('lock_wait', None)
+    lock_wait = config.get('lock_wait', None)
 
     return (
         (local_path, 'list')
@@ -90,7 +89,7 @@ def make_find_paths(find_paths):
 def capture_archive_listing(
     repository_path,
     archive,
-    storage_config,
+    config,
     local_borg_version,
     global_arguments,
     list_path=None,
@@ -98,18 +97,18 @@ def capture_archive_listing(
     remote_path=None,
 ):
     '''
-    Given a local or remote repository path, an archive name, a storage config dict, the local Borg
+    Given a local or remote repository path, an archive name, a configuration dict, the local Borg
     version, global arguments as an argparse.Namespace, the archive path in which to list files, and
     local and remote Borg paths, capture the output of listing that archive and return it as a list
     of file paths.
     '''
-    borg_environment = environment.make_environment(storage_config)
+    borg_environment = environment.make_environment(config)
 
     return tuple(
         execute_command_and_capture_output(
             make_list_command(
                 repository_path,
-                storage_config,
+                config,
                 local_borg_version,
                 argparse.Namespace(
                     repository=repository_path,
@@ -124,6 +123,7 @@ def capture_archive_listing(
                 remote_path,
             ),
             extra_environment=borg_environment,
+            borg_local_path=local_path,
         )
         .strip('\n')
         .split('\n')
@@ -132,7 +132,7 @@ def capture_archive_listing(
 
 def list_archive(
     repository_path,
-    storage_config,
+    config,
     local_borg_version,
     list_arguments,
     global_arguments,
@@ -140,7 +140,7 @@ def list_archive(
     remote_path=None,
 ):
     '''
-    Given a local or remote repository path, a storage config dict, the local Borg version, global
+    Given a local or remote repository path, a configuration dict, the local Borg version, global
     arguments as an argparse.Namespace, the arguments to the list action as an argparse.Namespace,
     and local and remote Borg paths, display the output of listing the files of a Borg archive (or
     return JSON output). If list_arguments.find_paths are given, list the files by searching across
@@ -168,7 +168,7 @@ def list_archive(
         )
         return rlist.list_repository(
             repository_path,
-            storage_config,
+            config,
             local_borg_version,
             rlist_arguments,
             global_arguments,
@@ -188,7 +188,7 @@ def list_archive(
             'The --json flag on the list action is not supported when using the --archive/--find flags.'
         )
 
-    borg_environment = environment.make_environment(storage_config)
+    borg_environment = environment.make_environment(config)
 
     # If there are any paths to find (and there's not a single archive already selected), start by
     # getting a list of archives to search.
@@ -210,7 +210,7 @@ def list_archive(
             execute_command_and_capture_output(
                 rlist.make_rlist_command(
                     repository_path,
-                    storage_config,
+                    config,
                     local_borg_version,
                     rlist_arguments,
                     global_arguments,
@@ -218,6 +218,7 @@ def list_archive(
                     remote_path,
                 ),
                 extra_environment=borg_environment,
+                borg_local_path=local_path,
             )
             .strip('\n')
             .split('\n')
@@ -239,7 +240,7 @@ def list_archive(
 
         main_command = make_list_command(
             repository_path,
-            storage_config,
+            config,
             local_borg_version,
             archive_arguments,
             global_arguments,

borgmatic/borg/mount.py

@@ -9,11 +9,8 @@ logger = logging.getLogger(__name__)
 def mount_archive(
     repository_path,
     archive,
-    mount_point,
-    paths,
-    foreground,
-    options,
-    storage_config,
+    mount_arguments,
+    config,
     local_borg_version,
     global_arguments,
     local_path='borg',
@@ -25,8 +22,8 @@ def mount_archive(
     dict, the local Borg version, global arguments as an argparse.Namespace instance, and optional
     local and remote Borg paths, mount the archive onto the mount point.
     '''
-    umask = storage_config.get('umask', None)
-    lock_wait = storage_config.get('lock_wait', None)
+    umask = config.get('umask', None)
+    lock_wait = config.get('lock_wait', None)
 
     full_command = (
         (local_path, 'mount')
@@ -36,8 +33,11 @@ def mount_archive(
         + (('--lock-wait', str(lock_wait)) if lock_wait else ())
         + (('--info',) if logger.getEffectiveLevel() == logging.INFO else ())
         + (('--debug', '--show-rc') if logger.isEnabledFor(logging.DEBUG) else ())
-        + (('--foreground',) if foreground else ())
-        + (('-o', options) if options else ())
+        + flags.make_flags_from_arguments(
+            mount_arguments,
+            excludes=('repository', 'archive', 'mount_point', 'paths', 'options'),
+        )
+        + (('-o', mount_arguments.options) if mount_arguments.options else ())
         + (
             (
                 flags.make_repository_flags(repository_path, local_borg_version)
@@ -54,14 +54,14 @@ def mount_archive(
                 else flags.make_repository_flags(repository_path, local_borg_version)
             )
         )
-        + (mount_point,)
-        + (tuple(paths) if paths else ())
+        + (mount_arguments.mount_point,)
+        + (tuple(mount_arguments.paths) if mount_arguments.paths else ())
     )
 
-    borg_environment = environment.make_environment(storage_config)
+    borg_environment = environment.make_environment(config)
 
     # Don't capture the output when foreground mode is used so that ctrl-C can work properly.
-    if foreground:
+    if mount_arguments.foreground:
         execute_command(
             full_command,
             output_file=DO_NOT_CAPTURE,

borgmatic/borg/prune.py

@@ -7,9 +7,9 @@ from borgmatic.execute import execute_command
 logger = logging.getLogger(__name__)
 
 
-def make_prune_flags(storage_config, retention_config, local_borg_version):
+def make_prune_flags(config, local_borg_version):
     '''
-    Given a retention config dict mapping from option name to value, transform it into an sequence of
+    Given a configuration dict mapping from option name to value, transform it into an sequence of
     command-line flags.
 
     For example, given a retention config of:
@@ -23,12 +23,12 @@ def make_prune_flags(storage_config, retention_config, local_borg_version):
             ('--keep-monthly', '6'),
         )
     '''
-    config = retention_config.copy()
-    prefix = config.pop('prefix', None)
-
     flag_pairs = (
-        ('--' + option_name.replace('_', '-'), str(value)) for option_name, value in config.items()
+        ('--' + option_name.replace('_', '-'), str(value))
+        for option_name, value in config.items()
+        if option_name.startswith('keep_')
     )
+    prefix = config.get('prefix')
 
     return tuple(element for pair in flag_pairs for element in pair) + (
         (
@@ -39,8 +39,8 @@ def make_prune_flags(storage_config, retention_config, local_borg_version):
         if prefix
         else (
             flags.make_match_archives_flags(
-                storage_config.get('match_archives'),
-                storage_config.get('archive_name_format'),
+                config.get('match_archives'),
+                config.get('archive_name_format'),
                 local_borg_version,
             )
         )
@@ -50,42 +50,43 @@ def make_prune_flags(storage_config, retention_config, local_borg_version):
 def prune_archives(
     dry_run,
     repository_path,
-    storage_config,
-    retention_config,
+    config,
     local_borg_version,
+    prune_arguments,
     global_arguments,
     local_path='borg',
     remote_path=None,
-    stats=False,
-    list_archives=False,
 ):
     '''
-    Given dry-run flag, a local or remote repository path, a storage config dict, and a
-    retention config dict, prune Borg archives according to the retention policy specified in that
-    configuration.
+    Given dry-run flag, a local or remote repository path, and a configuration dict, prune Borg
+    archives according to the retention policy specified in that configuration.
     '''
     borgmatic.logger.add_custom_log_levels()
-    umask = storage_config.get('umask', None)
-    lock_wait = storage_config.get('lock_wait', None)
-    extra_borg_options = storage_config.get('extra_borg_options', {}).get('prune', '')
+    umask = config.get('umask', None)
+    lock_wait = config.get('lock_wait', None)
+    extra_borg_options = config.get('extra_borg_options', {}).get('prune', '')
 
     full_command = (
         (local_path, 'prune')
-        + make_prune_flags(storage_config, retention_config, local_borg_version)
+        + make_prune_flags(config, local_borg_version)
         + (('--remote-path', remote_path) if remote_path else ())
         + (('--umask', str(umask)) if umask else ())
         + (('--log-json',) if global_arguments.log_json else ())
         + (('--lock-wait', str(lock_wait)) if lock_wait else ())
-        + (('--stats',) if stats and not dry_run else ())
+        + (('--stats',) if prune_arguments.stats and not dry_run else ())
         + (('--info',) if logger.getEffectiveLevel() == logging.INFO else ())
-        + (('--list',) if list_archives else ())
+        + flags.make_flags_from_arguments(
+            prune_arguments,
+            excludes=('repository', 'stats', 'list_archives'),
+        )
+        + (('--list',) if prune_arguments.list_archives 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 ())
         + flags.make_repository_flags(repository_path, local_borg_version)
     )
 
-    if stats or list_archives:
+    if prune_arguments.stats or prune_arguments.list_archives:
         output_log_level = logging.ANSWER
     else:
         output_log_level = logging.INFO
@@ -94,5 +95,5 @@ def prune_archives(
         full_command,
         output_log_level=output_log_level,
         borg_local_path=local_path,
-        extra_environment=environment.make_environment(storage_config),
+        extra_environment=environment.make_environment(config),
     )

borgmatic/borg/rcreate.py

@@ -14,7 +14,7 @@ RINFO_REPOSITORY_NOT_FOUND_EXIT_CODE = 2
 def create_repository(
     dry_run,
     repository_path,
-    storage_config,
+    config,
     local_borg_version,
     global_arguments,
     encryption_mode,
@@ -27,15 +27,15 @@ def create_repository(
     remote_path=None,
 ):
     '''
-    Given a dry-run flag, a local or remote repository path, a storage configuration dict, the local
-    Borg version, a Borg encryption mode, the path to another repo whose key material should be
-    reused, whether the repository should be append-only, and the storage quota to use, create the
+    Given a dry-run flag, a local or remote repository path, a configuration dict, the local Borg
+    version, a Borg encryption mode, the path to another repo whose key material should be reused,
+    whether the repository should be append-only, and the storage quota to use, create the
     repository. If the repository already exists, then log and skip creation.
     '''
     try:
         rinfo.display_repository_info(
             repository_path,
-            storage_config,
+            config,
             local_borg_version,
             argparse.Namespace(json=True),
             global_arguments,
@@ -48,8 +48,8 @@ def create_repository(
         if error.returncode != RINFO_REPOSITORY_NOT_FOUND_EXIT_CODE:
             raise
 
-    lock_wait = storage_config.get('lock_wait')
-    extra_borg_options = storage_config.get('extra_borg_options', {}).get('rcreate', '')
+    lock_wait = config.get('lock_wait')
+    extra_borg_options = config.get('extra_borg_options', {}).get('rcreate', '')
 
     rcreate_command = (
         (local_path,)
@@ -82,5 +82,5 @@ def create_repository(
         rcreate_command,
         output_file=DO_NOT_CAPTURE,
         borg_local_path=local_path,
-        extra_environment=environment.make_environment(storage_config),
+        extra_environment=environment.make_environment(config),
     )

borgmatic/borg/rinfo.py

@@ -9,7 +9,7 @@ logger = logging.getLogger(__name__)
 
 def display_repository_info(
     repository_path,
-    storage_config,
+    config,
     local_borg_version,
     rinfo_arguments,
     global_arguments,
@@ -17,12 +17,12 @@ def display_repository_info(
     remote_path=None,
 ):
     '''
-    Given a local or remote repository path, a storage config dict, the local Borg version, the
+    Given a local or remote repository path, a configuration dict, the local Borg version, the
     arguments to the rinfo action, and global arguments as an argparse.Namespace, display summary
     information for the Borg repository or return JSON summary information.
     '''
     borgmatic.logger.add_custom_log_levels()
-    lock_wait = storage_config.get('lock_wait', None)
+    lock_wait = config.get('lock_wait', None)
 
     full_command = (
         (local_path,)
@@ -48,12 +48,13 @@ def display_repository_info(
         + flags.make_repository_flags(repository_path, local_borg_version)
     )
 
-    extra_environment = environment.make_environment(storage_config)
+    extra_environment = environment.make_environment(config)
 
     if rinfo_arguments.json:
         return execute_command_and_capture_output(
             full_command,
             extra_environment=extra_environment,
+            borg_local_path=local_path,
         )
     else:
         execute_command(

borgmatic/borg/rlist.py

@@ -10,14 +10,14 @@ logger = logging.getLogger(__name__)
 def resolve_archive_name(
     repository_path,
     archive,
-    storage_config,
+    config,
     local_borg_version,
     global_arguments,
     local_path='borg',
     remote_path=None,
 ):
     '''
-    Given a local or remote repository path, an archive name, a storage config dict, the local Borg
+    Given a local or remote repository path, an archive name, a configuration dict, the local Borg
     version, global arguments as an argparse.Namespace, a local Borg path, and a remote Borg path,
     return the archive name. But if the archive name is "latest", then instead introspect the
     repository for the latest archive and return its name.
@@ -34,7 +34,7 @@ def resolve_archive_name(
         )
         + flags.make_flags('remote-path', remote_path)
         + flags.make_flags('log-json', global_arguments.log_json)
-        + flags.make_flags('lock-wait', storage_config.get('lock_wait'))
+        + flags.make_flags('lock-wait', config.get('lock_wait'))
         + flags.make_flags('last', 1)
         + ('--short',)
         + flags.make_repository_flags(repository_path, local_borg_version)
@@ -42,7 +42,8 @@ def resolve_archive_name(
 
     output = execute_command_and_capture_output(
         full_command,
-        extra_environment=environment.make_environment(storage_config),
+        extra_environment=environment.make_environment(config),
+        borg_local_path=local_path,
     )
     try:
         latest_archive = output.strip().splitlines()[-1]
@@ -59,7 +60,7 @@ MAKE_FLAGS_EXCLUDES = ('repository', 'prefix', 'match_archives')
 
 def make_rlist_command(
     repository_path,
-    storage_config,
+    config,
     local_borg_version,
     rlist_arguments,
     global_arguments,
@@ -67,7 +68,7 @@ def make_rlist_command(
     remote_path=None,
 ):
     '''
-    Given a local or remote repository path, a storage config dict, the local Borg version, the
+    Given a local or remote repository path, a configuration dict, the local Borg version, the
     arguments to the rlist action, global arguments as an argparse.Namespace instance, and local and
     remote Borg paths, return a command as a tuple to list archives with a repository.
     '''
@@ -88,7 +89,7 @@ def make_rlist_command(
         )
         + flags.make_flags('remote-path', remote_path)
         + flags.make_flags('log-json', global_arguments.log_json)
-        + flags.make_flags('lock-wait', storage_config.get('lock_wait'))
+        + flags.make_flags('lock-wait', config.get('lock_wait'))
         + (
             (
                 flags.make_flags('match-archives', f'sh:{rlist_arguments.prefix}*')
@@ -98,8 +99,8 @@ def make_rlist_command(
             if rlist_arguments.prefix
             else (
                 flags.make_match_archives_flags(
-                    rlist_arguments.match_archives or storage_config.get('match_archives'),
-                    storage_config.get('archive_name_format'),
+                    rlist_arguments.match_archives or config.get('match_archives'),
+                    config.get('archive_name_format'),
                     local_borg_version,
                 )
             )
@@ -111,7 +112,7 @@ def make_rlist_command(
 
 def list_repository(
     repository_path,
-    storage_config,
+    config,
     local_borg_version,
     rlist_arguments,
     global_arguments,
@@ -119,17 +120,17 @@ def list_repository(
     remote_path=None,
 ):
     '''
-    Given a local or remote repository path, a storage config dict, the local Borg version, the
+    Given a local or remote repository path, a configuration dict, the local Borg version, the
     arguments to the list action, global arguments as an argparse.Namespace instance, and local and
     remote Borg paths, display the output of listing Borg archives in the given repository (or
     return JSON output).
     '''
     borgmatic.logger.add_custom_log_levels()
-    borg_environment = environment.make_environment(storage_config)
+    borg_environment = environment.make_environment(config)
 
     main_command = make_rlist_command(
         repository_path,
-        storage_config,
+        config,
         local_borg_version,
         rlist_arguments,
         global_arguments,
@@ -138,7 +139,9 @@ def list_repository(
     )
 
     if rlist_arguments.json:
-        return execute_command_and_capture_output(main_command, extra_environment=borg_environment)
+        return execute_command_and_capture_output(
+            main_command, extra_environment=borg_environment, borg_local_path=local_path
+        )
     else:
         execute_command(
             main_command,

borgmatic/borg/transfer.py

@@ -10,7 +10,7 @@ logger = logging.getLogger(__name__)
 def transfer_archives(
     dry_run,
     repository_path,
-    storage_config,
+    config,
     local_borg_version,
     transfer_arguments,
     global_arguments,
@@ -18,7 +18,7 @@ def transfer_archives(
     remote_path=None,
 ):
     '''
-    Given a dry-run flag, a local or remote repository path, a storage config dict, the local Borg
+    Given a dry-run flag, a local or remote repository path, a configuration dict, the local Borg
     version, the arguments to the transfer action, and global arguments as an argparse.Namespace
     instance, transfer archives to the given repository.
     '''
@@ -30,7 +30,7 @@ def transfer_archives(
         + (('--debug', '--show-rc') if logger.isEnabledFor(logging.DEBUG) else ())
         + flags.make_flags('remote-path', remote_path)
         + flags.make_flags('log-json', global_arguments.log_json)
-        + flags.make_flags('lock-wait', storage_config.get('lock_wait', None))
+        + flags.make_flags('lock-wait', config.get('lock_wait', None))
         + (
             flags.make_flags_from_arguments(
                 transfer_arguments,
@@ -40,8 +40,8 @@ def transfer_archives(
                 flags.make_match_archives_flags(
                     transfer_arguments.match_archives
                     or transfer_arguments.archive
-                    or storage_config.get('match_archives'),
-                    storage_config.get('archive_name_format'),
+                    or config.get('match_archives'),
+                    config.get('archive_name_format'),
                     local_borg_version,
                 )
             )
@@ -56,5 +56,5 @@ def transfer_archives(
         output_log_level=logging.ANSWER,
         output_file=DO_NOT_CAPTURE if transfer_arguments.progress else None,
         borg_local_path=local_path,
-        extra_environment=environment.make_environment(storage_config),
+        extra_environment=environment.make_environment(config),
     )

borgmatic/borg/version.py

@@ -6,9 +6,9 @@ from borgmatic.execute import execute_command_and_capture_output
 logger = logging.getLogger(__name__)
 
 
-def local_borg_version(storage_config, local_path='borg'):
+def local_borg_version(config, local_path='borg'):
     '''
-    Given a storage configuration dict and a local Borg binary path, return a version string for it.
+    Given a configuration dict and a local Borg binary path, return a version string for it.
 
     Raise OSError or CalledProcessError if there is a problem running Borg.
     Raise ValueError if the version cannot be parsed.
@@ -20,7 +20,8 @@ def local_borg_version(storage_config, local_path='borg'):
     )
     output = execute_command_and_capture_output(
         full_command,
-        extra_environment=environment.make_environment(storage_config),
+        extra_environment=environment.make_environment(config),
+        borg_local_path=local_path,
     )
 
     try:

borgmatic/commands/arguments.py

@@ -1,14 +1,17 @@
 import collections
-from argparse import Action, ArgumentParser
+import itertools
+import sys
+from argparse import ArgumentParser
 
 from borgmatic.config import collect
 
-SUBPARSER_ALIASES = {
+ACTION_ALIASES = {
     'rcreate': ['init', '-I'],
     'prune': ['-p'],
     'compact': [],
     'create': ['-C'],
     'check': ['-k'],
+    'config': [],
     'extract': ['-x'],
     'export-tar': [],
     'mount': ['-m'],
@@ -24,119 +27,220 @@ SUBPARSER_ALIASES = {
 }
 
 
-def parse_subparser_arguments(unparsed_arguments, subparsers):
+def get_subaction_parsers(action_parser):
     '''
-    Given a sequence of arguments and a dict from subparser name to argparse.ArgumentParser
-    instance, give each requested action's subparser a shot at parsing all arguments. This allows
-    common arguments like "--repository" to be shared across multiple subparsers.
+    Given an argparse.ArgumentParser instance, lookup the subactions in it and return a dict from
+    subaction name to subaction parser.
+    '''
+    if not action_parser._subparsers:
+        return {}
 
-    Return the result as a tuple of (a dict mapping from subparser name to a parsed namespace of
-    arguments, a list of remaining arguments not claimed by any subparser).
-    '''
-    arguments = collections.OrderedDict()
-    remaining_arguments = list(unparsed_arguments)
-    alias_to_subparser_name = {
-        alias: subparser_name
-        for subparser_name, aliases in SUBPARSER_ALIASES.items()
-        for alias in aliases
+    return {
+        subaction_name: subaction_parser
+        for group_action in action_parser._subparsers._group_actions
+        for subaction_name, subaction_parser in group_action.choices.items()
     }
 
-    # If the "borg" action is used, skip all other subparsers. This avoids confusion like
-    # "borg list" triggering borgmatic's own list action.
-    if 'borg' in unparsed_arguments:
-        subparsers = {'borg': subparsers['borg']}
 
-    for argument in remaining_arguments:
-        canonical_name = alias_to_subparser_name.get(argument, argument)
-        subparser = subparsers.get(canonical_name)
+def get_subactions_for_actions(action_parsers):
+    '''
+    Given a dict from action name to an argparse.ArgumentParser instance, make a map from action
+    name to the names of contained sub-actions.
+    '''
+    return {
+        action: tuple(
+            subaction_name
+            for group_action in action_parser._subparsers._group_actions
+            for subaction_name in group_action.choices.keys()
+        )
+        for action, action_parser in action_parsers.items()
+        if action_parser._subparsers
+    }
 
-        if not subparser:
-            continue
 
-        # If a parsed value happens to be the same as the name of a subparser, remove it from the
-        # remaining arguments. This prevents, for instance, "check --only extract" from triggering
-        # the "extract" subparser.
-        parsed, unused_remaining = subparser.parse_known_args(unparsed_arguments)
+def omit_values_colliding_with_action_names(unparsed_arguments, parsed_arguments):
+    '''
+    Given a sequence of string arguments and a dict from action name to parsed argparse.Namespace
+    arguments, return the string arguments with any values omitted that happen to be the same as
+    the name of a borgmatic action.
+
+    This prevents, for instance, "check --only extract" from triggering the "extract" action.
+    '''
+    remaining_arguments = list(unparsed_arguments)
+
+    for action_name, parsed in parsed_arguments.items():
         for value in vars(parsed).values():
             if isinstance(value, str):
-                if value in subparsers:
+                if value in ACTION_ALIASES.keys():
                     remaining_arguments.remove(value)
             elif isinstance(value, list):
                 for item in value:
-                    if item in subparsers:
+                    if item in ACTION_ALIASES.keys():
                         remaining_arguments.remove(item)
 
-        arguments[canonical_name] = parsed
+    return tuple(remaining_arguments)
 
-    # If no actions are explicitly requested, assume defaults.
-    if not arguments and '--help' not in unparsed_arguments and '-h' not in unparsed_arguments:
-        for subparser_name in ('create', 'prune', 'compact', 'check'):
-            subparser = subparsers[subparser_name]
-            parsed, unused_remaining = subparser.parse_known_args(unparsed_arguments)
-            arguments[subparser_name] = parsed
 
-    remaining_arguments = list(unparsed_arguments)
+def parse_and_record_action_arguments(
+    unparsed_arguments, parsed_arguments, action_parser, action_name, canonical_name=None
+):
+    '''
+    Given unparsed arguments as a sequence of strings, parsed arguments as a dict from action name
+    to parsed argparse.Namespace, a parser to parse with, an action name, and an optional canonical
+    action name (in case this the action name is an alias), parse the arguments and return a list of
+    any remaining string arguments that were not parsed. Also record the parsed argparse.Namespace
+    by setting it into the given parsed arguments. Return None if no parsing occurs because the
+    given action doesn't apply to the given unparsed arguments.
+    '''
+    filtered_arguments = omit_values_colliding_with_action_names(
+        unparsed_arguments, parsed_arguments
+    )
 
-    # Now ask each subparser, one by one, to greedily consume arguments.
-    for subparser_name, subparser in subparsers.items():
-        if subparser_name not in arguments.keys():
+    if action_name not in filtered_arguments:
+        return tuple(unparsed_arguments)
+
+    parsed, remaining = action_parser.parse_known_args(filtered_arguments)
+    parsed_arguments[canonical_name or action_name] = parsed
+
+    # Special case: If this is a "borg" action, greedily consume all arguments after (+1) the "borg"
+    # argument.
+    if action_name == 'borg':
+        borg_options_index = remaining.index('borg') + 1
+        parsed_arguments['borg'].options = remaining[borg_options_index:]
+        remaining = remaining[:borg_options_index]
+
+    return tuple(argument for argument in remaining if argument != action_name)
+
+
+def get_unparsable_arguments(remaining_action_arguments):
+    '''
+    Given a sequence of argument tuples (one per action parser that parsed arguments), determine the
+    remaining arguments that no action parsers have consumed.
+    '''
+    if not remaining_action_arguments:
+        return ()
+
+    return tuple(
+        argument
+        for argument in dict.fromkeys(
+            itertools.chain.from_iterable(remaining_action_arguments)
+        ).keys()
+        if all(argument in action_arguments for action_arguments in remaining_action_arguments)
+    )
+
+
+def parse_arguments_for_actions(unparsed_arguments, action_parsers, global_parser):
+    '''
+    Given a sequence of arguments, a dict from action name to argparse.ArgumentParser instance,
+    and the global parser as a argparse.ArgumentParser instance, give each requested action's
+    parser a shot at parsing all arguments. This allows common arguments like "--repository" to be
+    shared across multiple action parsers.
+
+    Return the result as a tuple of: (a dict mapping from action name to an argparse.Namespace of
+    parsed arguments, a tuple of argument tuples where each is the remaining arguments not claimed
+    by any action parser).
+    '''
+    arguments = collections.OrderedDict()
+    help_requested = bool('--help' in unparsed_arguments or '-h' in unparsed_arguments)
+    remaining_action_arguments = []
+    alias_to_action_name = {
+        alias: action_name for action_name, aliases in ACTION_ALIASES.items() for alias in aliases
+    }
+
+    # If the "borg" action is used, skip all other action parsers. This avoids confusion like
+    # "borg list" triggering borgmatic's own list action.
+    if 'borg' in unparsed_arguments:
+        action_parsers = {'borg': action_parsers['borg']}
+
+    # Ask each action parser, one by one, to parse arguments.
+    for argument in unparsed_arguments:
+        action_name = argument
+        canonical_name = alias_to_action_name.get(action_name, action_name)
+        action_parser = action_parsers.get(action_name)
+
+        if not action_parser:
             continue
 
-        subparser = subparsers[subparser_name]
-        unused_parsed, remaining_arguments = subparser.parse_known_args(remaining_arguments)
+        subaction_parsers = get_subaction_parsers(action_parser)
 
-    # Special case: If "borg" is present in the arguments, consume all arguments after (+1) the
-    # "borg" action.
-    if 'borg' in arguments:
-        borg_options_index = remaining_arguments.index('borg') + 1
-        arguments['borg'].options = remaining_arguments[borg_options_index:]
-        remaining_arguments = remaining_arguments[:borg_options_index]
+        # But first parse with subaction parsers, if any.
+        if subaction_parsers:
+            subactions_parsed = False
 
-    # Remove the subparser names themselves.
-    for subparser_name, subparser in subparsers.items():
-        if subparser_name in remaining_arguments:
-            remaining_arguments.remove(subparser_name)
+            for subaction_name, subaction_parser in subaction_parsers.items():
+                remaining_action_arguments.append(
+                    tuple(
+                        argument
+                        for argument in parse_and_record_action_arguments(
+                            unparsed_arguments,
+                            arguments,
+                            subaction_parser,
+                            subaction_name,
+                        )
+                        if argument != action_name
+                    )
+                )
 
-    return (arguments, remaining_arguments)
+                if subaction_name in arguments:
+                    subactions_parsed = True
 
-
-class Extend_action(Action):
-    '''
-    An argparse action to support Python 3.8's "extend" action in older versions of Python.
-    '''
-
-    def __call__(self, parser, namespace, values, option_string=None):
-        items = getattr(namespace, self.dest, None)
-
-        if items:
-            items.extend(values)
+            if not subactions_parsed:
+                if help_requested:
+                    action_parser.print_help()
+                    sys.exit(0)
+                else:
+                    raise ValueError(
+                        f"Missing sub-action after {action_name} action. Expected one of: {', '.join(get_subactions_for_actions(action_parsers)[action_name])}"
+                    )
+        # Otherwise, parse with the main action parser.
         else:
-            setattr(namespace, self.dest, list(values))
+            remaining_action_arguments.append(
+                parse_and_record_action_arguments(
+                    unparsed_arguments, arguments, action_parser, action_name, canonical_name
+                )
+            )
+
+    # If no actions were explicitly requested, assume defaults.
+    if not arguments and not help_requested:
+        for default_action_name in ('create', 'prune', 'compact', 'check'):
+            default_action_parser = action_parsers[default_action_name]
+            remaining_action_arguments.append(
+                parse_and_record_action_arguments(
+                    tuple(unparsed_arguments) + (default_action_name,),
+                    arguments,
+                    default_action_parser,
+                    default_action_name,
+                )
+            )
+
+    arguments['global'], remaining = global_parser.parse_known_args(unparsed_arguments)
+    remaining_action_arguments.append(remaining)
+
+    return (
+        arguments,
+        tuple(remaining_action_arguments) if arguments else unparsed_arguments,
+    )
 
 
 def make_parsers():
     '''
-    Build a top-level parser and its subparsers and return them as a tuple.
+    Build a global arguments parser, individual action parsers, and a combined parser containing
+    both. Return them as a tuple. The global parser is useful for parsing just global arguments
+    while ignoring actions, and the combined parser is handy for displaying help that includes
+    everything: global flags, a list of actions, etc.
     '''
     config_paths = collect.get_default_config_paths(expand_home=True)
     unexpanded_config_paths = collect.get_default_config_paths(expand_home=False)
 
     global_parser = ArgumentParser(add_help=False)
-    global_parser.register('action', 'extend', Extend_action)
     global_group = global_parser.add_argument_group('global arguments')
 
     global_group.add_argument(
         '-c',
         '--config',
-        nargs='*',
         dest='config_paths',
-        default=config_paths,
-        help=f"Configuration filenames or directories, defaults to: {' '.join(unexpanded_config_paths)}",
-    )
-    global_group.add_argument(
-        '--excludes',
-        dest='excludes_filename',
-        help='Deprecated in favor of exclude_patterns within configuration',
+        action='append',
+        help=f"Configuration filename or directory, can specify flag multiple times, defaults to: {' '.join(unexpanded_config_paths)}",
     )
     global_group.add_argument(
         '-n',
@@ -152,30 +256,30 @@ def make_parsers():
         '-v',
         '--verbosity',
         type=int,
-        choices=range(-1, 3),
+        choices=range(-2, 3),
         default=0,
-        help='Display verbose progress to the console (from only errors to very verbose: -1, 0, 1, or 2)',
+        help='Display verbose progress to the console (disabled, errors only, default, some, or lots: -2, -1, 0, 1, or 2)',
     )
     global_group.add_argument(
         '--syslog-verbosity',
         type=int,
-        choices=range(-1, 3),
+        choices=range(-2, 3),
         default=0,
-        help='Log verbose progress to syslog (from only errors to very verbose: -1, 0, 1, or 2). Ignored when console is interactive or --log-file is given',
+        help='Log verbose progress to syslog (disabled, errors only, default, some, or lots: -2, -1, 0, 1, or 2). Ignored when console is interactive or --log-file is given',
     )
     global_group.add_argument(
         '--log-file-verbosity',
         type=int,
-        choices=range(-1, 3),
+        choices=range(-2, 3),
         default=0,
-        help='Log verbose progress to log file (from only errors to very verbose: -1, 0, 1, or 2). Only used when --log-file is given',
+        help='Log verbose progress to log file (disabled, errors only, default, some, or lots: -2, -1, 0, 1, or 2). Only used when --log-file is given',
     )
     global_group.add_argument(
         '--monitoring-verbosity',
         type=int,
-        choices=range(-1, 3),
+        choices=range(-2, 3),
         default=0,
-        help='Log verbose progress to monitoring integrations that support logging (from only errors to very verbose: -1, 0, 1, or 2)',
+        help='Log verbose progress to monitoring integrations that support logging (from disabled, errors only, default, some, or lots: -2, -1, 0, 1, or 2)',
     )
     global_group.add_argument(
         '--log-file',
@@ -194,11 +298,10 @@ def make_parsers():
     )
     global_group.add_argument(
         '--override',
-        metavar='SECTION.OPTION=VALUE',
-        nargs='+',
+        metavar='OPTION.SUBOPTION=VALUE',
         dest='overrides',
-        action='extend',
-        help='One or more configuration file options to override with specified values',
+        action='append',
+        help='Configuration file option to override with specified value, can specify flag multiple times',
     )
     global_group.add_argument(
         '--no-environment-interpolation',
@@ -226,7 +329,7 @@ def make_parsers():
         help='Display installed version number of borgmatic and exit',
     )
 
-    top_level_parser = ArgumentParser(
+    global_plus_action_parser = ArgumentParser(
         description='''
             Simple, configuration-driven backup software for servers and workstations. If none of
             the action options are given, then borgmatic defaults to: create, prune, compact, and
@@ -235,14 +338,14 @@ def make_parsers():
         parents=[global_parser],
     )
 
-    subparsers = top_level_parser.add_subparsers(
+    action_parsers = global_plus_action_parser.add_subparsers(
         title='actions',
         metavar='',
         help='Specify zero or more actions. Defaults to create, prune, compact, and check. Use --help with action for details:',
     )
-    rcreate_parser = subparsers.add_parser(
+    rcreate_parser = action_parsers.add_parser(
         'rcreate',
-        aliases=SUBPARSER_ALIASES['rcreate'],
+        aliases=ACTION_ALIASES['rcreate'],
         help='Create a new, empty Borg repository',
         description='Create a new, empty Borg repository',
         add_help=False,
@@ -259,7 +362,7 @@ def make_parsers():
         '--source-repository',
         '--other-repo',
         metavar='KEY_REPOSITORY',
-        help='Path to an existing Borg repository whose key material should be reused (Borg 2.x+ only)',
+        help='Path to an existing Borg repository whose key material should be reused [Borg 2.x+ only]',
     )
     rcreate_group.add_argument(
         '--repository',
@@ -268,7 +371,7 @@ def make_parsers():
     rcreate_group.add_argument(
         '--copy-crypt-key',
         action='store_true',
-        help='Copy the crypt key used for authenticated encryption from the source repository, defaults to a new random key (Borg 2.x+ only)',
+        help='Copy the crypt key used for authenticated encryption from the source repository, defaults to a new random key [Borg 2.x+ only]',
     )
     rcreate_group.add_argument(
         '--append-only',
@@ -288,11 +391,11 @@ def make_parsers():
         '-h', '--help', action='help', help='Show this help message and exit'
     )
 
-    transfer_parser = subparsers.add_parser(
+    transfer_parser = action_parsers.add_parser(
         'transfer',
-        aliases=SUBPARSER_ALIASES['transfer'],
-        help='Transfer archives from one repository to another, optionally upgrading the transferred data (Borg 2.0+ only)',
-        description='Transfer archives from one repository to another, optionally upgrading the transferred data (Borg 2.0+ only)',
+        aliases=ACTION_ALIASES['transfer'],
+        help='Transfer archives from one repository to another, optionally upgrading the transferred data [Borg 2.0+ only]',
+        description='Transfer archives from one repository to another, optionally upgrading the transferred data [Borg 2.0+ only]',
         add_help=False,
     )
     transfer_group = transfer_parser.add_argument_group('transfer arguments')
@@ -337,13 +440,33 @@ def make_parsers():
     transfer_group.add_argument(
         '--last', metavar='N', help='Only transfer last N archives after other filters are applied'
     )
+    transfer_group.add_argument(
+        '--oldest',
+        metavar='TIMESPAN',
+        help='Transfer archives within a specified time range starting from the timestamp of the oldest archive (e.g. 7d or 12m) [Borg 2.x+ only]',
+    )
+    transfer_group.add_argument(
+        '--newest',
+        metavar='TIMESPAN',
+        help='Transfer archives within a time range that ends at timestamp of the newest archive and starts a specified time range ago (e.g. 7d or 12m) [Borg 2.x+ only]',
+    )
+    transfer_group.add_argument(
+        '--older',
+        metavar='TIMESPAN',
+        help='Transfer archives that are older than the specified time range (e.g. 7d or 12m) from the current time [Borg 2.x+ only]',
+    )
+    transfer_group.add_argument(
+        '--newer',
+        metavar='TIMESPAN',
+        help='Transfer archives that are newer than the specified time range (e.g. 7d or 12m) from the current time [Borg 2.x+ only]',
+    )
     transfer_group.add_argument(
         '-h', '--help', action='help', help='Show this help message and exit'
     )
 
-    prune_parser = subparsers.add_parser(
+    prune_parser = action_parsers.add_parser(
         'prune',
-        aliases=SUBPARSER_ALIASES['prune'],
+        aliases=ACTION_ALIASES['prune'],
         help='Prune archives according to the retention policy (with Borg 1.2+, run compact afterwards to actually free space)',
         description='Prune archives according to the retention policy (with Borg 1.2+, run compact afterwards to actually free space)',
         add_help=False,
@@ -363,13 +486,33 @@ def make_parsers():
     prune_group.add_argument(
         '--list', dest='list_archives', action='store_true', help='List archives kept/pruned'
     )
+    prune_group.add_argument(
+        '--oldest',
+        metavar='TIMESPAN',
+        help='Prune archives within a specified time range starting from the timestamp of the oldest archive (e.g. 7d or 12m) [Borg 2.x+ only]',
+    )
+    prune_group.add_argument(
+        '--newest',
+        metavar='TIMESPAN',
+        help='Prune archives within a time range that ends at timestamp of the newest archive and starts a specified time range ago (e.g. 7d or 12m) [Borg 2.x+ only]',
+    )
+    prune_group.add_argument(
+        '--older',
+        metavar='TIMESPAN',
+        help='Prune archives that are older than the specified time range (e.g. 7d or 12m) from the current time [Borg 2.x+ only]',
+    )
+    prune_group.add_argument(
+        '--newer',
+        metavar='TIMESPAN',
+        help='Prune archives that are newer than the specified time range (e.g. 7d or 12m) from the current time [Borg 2.x+ only]',
+    )
     prune_group.add_argument('-h', '--help', action='help', help='Show this help message and exit')
 
-    compact_parser = subparsers.add_parser(
+    compact_parser = action_parsers.add_parser(
         'compact',
-        aliases=SUBPARSER_ALIASES['compact'],
-        help='Compact segments to free space (Borg 1.2+, borgmatic 1.5.23+ only)',
-        description='Compact segments to free space (Borg 1.2+, borgmatic 1.5.23+ only)',
+        aliases=ACTION_ALIASES['compact'],
+        help='Compact segments to free space [Borg 1.2+, borgmatic 1.5.23+ only]',
+        description='Compact segments to free space [Borg 1.2+, borgmatic 1.5.23+ only]',
         add_help=False,
     )
     compact_group = compact_parser.add_argument_group('compact arguments')
@@ -389,7 +532,7 @@ def make_parsers():
         dest='cleanup_commits',
         default=False,
         action='store_true',
-        help='Cleanup commit-only 17-byte segment files left behind by Borg 1.1 (flag in Borg 1.2 only)',
+        help='Cleanup commit-only 17-byte segment files left behind by Borg 1.1 [flag in Borg 1.2 only]',
     )
     compact_group.add_argument(
         '--threshold',
@@ -401,9 +544,9 @@ def make_parsers():
         '-h', '--help', action='help', help='Show this help message and exit'
     )
 
-    create_parser = subparsers.add_parser(
+    create_parser = action_parsers.add_parser(
         'create',
-        aliases=SUBPARSER_ALIASES['create'],
+        aliases=ACTION_ALIASES['create'],
         help='Create an archive (actually perform a backup)',
         description='Create an archive (actually perform a backup)',
         add_help=False,
@@ -435,9 +578,9 @@ def make_parsers():
     )
     create_group.add_argument('-h', '--help', action='help', help='Show this help message and exit')
 
-    check_parser = subparsers.add_parser(
+    check_parser = action_parsers.add_parser(
         'check',
-        aliases=SUBPARSER_ALIASES['check'],
+        aliases=ACTION_ALIASES['check'],
         help='Check archives for consistency',
         description='Check archives for consistency',
         add_help=False,
@@ -477,9 +620,9 @@ def make_parsers():
     )
     check_group.add_argument('-h', '--help', action='help', help='Show this help message and exit')
 
-    extract_parser = subparsers.add_parser(
+    extract_parser = action_parsers.add_parser(
         'extract',
-        aliases=SUBPARSER_ALIASES['extract'],
+        aliases=ACTION_ALIASES['extract'],
         help='Extract files from a named archive to the current directory',
         description='Extract a named archive to the current directory',
         add_help=False,
@@ -496,9 +639,9 @@ def make_parsers():
         '--path',
         '--restore-path',
         metavar='PATH',
-        nargs='+',
         dest='paths',
-        help='Paths to extract from archive, defaults to the entire archive',
+        action='append',
+        help='Path to extract from archive, can specify flag multiple times, defaults to the entire archive',
     )
     extract_group.add_argument(
         '--destination',
@@ -523,9 +666,118 @@ def make_parsers():
         '-h', '--help', action='help', help='Show this help message and exit'
     )
 
-    export_tar_parser = subparsers.add_parser(
+    config_parser = action_parsers.add_parser(
+        'config',
+        aliases=ACTION_ALIASES['config'],
+        help='Perform configuration file related operations',
+        description='Perform configuration file related operations',
+        add_help=False,
+    )
+
+    config_group = config_parser.add_argument_group('config arguments')
+    config_group.add_argument('-h', '--help', action='help', help='Show this help message and exit')
+
+    config_parsers = config_parser.add_subparsers(
+        title='config sub-actions',
+    )
+
+    config_bootstrap_parser = config_parsers.add_parser(
+        'bootstrap',
+        help='Extract the borgmatic configuration files from a named archive',
+        description='Extract the borgmatic configuration files from a named archive',
+        add_help=False,
+    )
+    config_bootstrap_group = config_bootstrap_parser.add_argument_group(
+        'config bootstrap arguments'
+    )
+    config_bootstrap_group.add_argument(
+        '--repository',
+        help='Path of repository to extract config files from',
+        required=True,
+    )
+    config_bootstrap_group.add_argument(
+        '--borgmatic-source-directory',
+        help='Path that stores the config files used to create an archive and additional source files used for temporary internal state like borgmatic database dumps. Defaults to ~/.borgmatic',
+    )
+    config_bootstrap_group.add_argument(
+        '--archive',
+        help='Name of archive to extract config files from, defaults to "latest"',
+        default='latest',
+    )
+    config_bootstrap_group.add_argument(
+        '--destination',
+        metavar='PATH',
+        dest='destination',
+        help='Directory to extract config files into, defaults to /',
+        default='/',
+    )
+    config_bootstrap_group.add_argument(
+        '--strip-components',
+        type=lambda number: number if number == 'all' else int(number),
+        metavar='NUMBER',
+        help='Number of leading path components to remove from each extracted path or "all" to strip all leading path components. Skip paths with fewer elements',
+    )
+    config_bootstrap_group.add_argument(
+        '--progress',
+        dest='progress',
+        default=False,
+        action='store_true',
+        help='Display progress for each file as it is extracted',
+    )
+    config_bootstrap_group.add_argument(
+        '-h', '--help', action='help', help='Show this help message and exit'
+    )
+
+    config_generate_parser = config_parsers.add_parser(
+        'generate',
+        help='Generate a sample borgmatic configuration file',
+        description='Generate a sample borgmatic configuration file',
+        add_help=False,
+    )
+    config_generate_group = config_generate_parser.add_argument_group('config generate arguments')
+    config_generate_group.add_argument(
+        '-s',
+        '--source',
+        dest='source_filename',
+        help='Optional configuration file to merge into the generated configuration, useful for upgrading your configuration',
+    )
+    config_generate_group.add_argument(
+        '-d',
+        '--destination',
+        dest='destination_filename',
+        default=config_paths[0],
+        help=f'Destination configuration file, default: {unexpanded_config_paths[0]}',
+    )
+    config_generate_group.add_argument(
+        '--overwrite',
+        default=False,
+        action='store_true',
+        help='Whether to overwrite any existing destination file, defaults to false',
+    )
+    config_generate_group.add_argument(
+        '-h', '--help', action='help', help='Show this help message and exit'
+    )
+
+    config_validate_parser = config_parsers.add_parser(
+        'validate',
+        help='Validate borgmatic configuration files specified with --config (see borgmatic --help)',
+        description='Validate borgmatic configuration files specified with --config (see borgmatic --help)',
+        add_help=False,
+    )
+    config_validate_group = config_validate_parser.add_argument_group('config validate arguments')
+    config_validate_group.add_argument(
+        '-s',
+        '--show',
+        action='store_true',
+        help='Show the validated configuration after all include merging has occurred',
+    )
+    config_validate_group.add_argument(
+        '-h', '--help', action='help', help='Show this help message and exit'
+    )
+
+    export_tar_parser = action_parsers.add_parser(
         'export-tar',
-        aliases=SUBPARSER_ALIASES['export-tar'],
+        aliases=ACTION_ALIASES['export-tar'],
         help='Export an archive to a tar-formatted file or stream',
         description='Export an archive to a tar-formatted file or stream',
         add_help=False,
@@ -541,9 +793,9 @@ def make_parsers():
     export_tar_group.add_argument(
         '--path',
         metavar='PATH',
-        nargs='+',
         dest='paths',
-        help='Paths to export from archive, defaults to the entire archive',
+        action='append',
+        help='Path to export from archive, can specify flag multiple times, defaults to the entire archive',
     )
     export_tar_group.add_argument(
         '--destination',
@@ -569,9 +821,9 @@ def make_parsers():
         '-h', '--help', action='help', help='Show this help message and exit'
     )
 
-    mount_parser = subparsers.add_parser(
+    mount_parser = action_parsers.add_parser(
         'mount',
-        aliases=SUBPARSER_ALIASES['mount'],
+        aliases=ACTION_ALIASES['mount'],
         help='Mount files from a named archive as a FUSE filesystem',
         description='Mount a named archive as a FUSE filesystem',
         add_help=False,
@@ -592,9 +844,9 @@ def make_parsers():
     mount_group.add_argument(
         '--path',
         metavar='PATH',
-        nargs='+',
         dest='paths',
-        help='Paths to mount from archive, defaults to the entire archive',
+        action='append',
+        help='Path to mount from archive, can specify multiple times, defaults to the entire archive',
     )
     mount_group.add_argument(
         '--foreground',
@@ -603,12 +855,40 @@ def make_parsers():
         action='store_true',
         help='Stay in foreground until ctrl-C is pressed',
     )
+    mount_group.add_argument(
+        '--first',
+        metavar='N',
+        help='Mount first N archives after other filters are applied',
+    )
+    mount_group.add_argument(
+        '--last', metavar='N', help='Mount last N archives after other filters are applied'
+    )
+    mount_group.add_argument(
+        '--oldest',
+        metavar='TIMESPAN',
+        help='Mount archives within a specified time range starting from the timestamp of the oldest archive (e.g. 7d or 12m) [Borg 2.x+ only]',
+    )
+    mount_group.add_argument(
+        '--newest',
+        metavar='TIMESPAN',
+        help='Mount archives within a time range that ends at timestamp of the newest archive and starts a specified time range ago (e.g. 7d or 12m) [Borg 2.x+ only]',
+    )
+    mount_group.add_argument(
+        '--older',
+        metavar='TIMESPAN',
+        help='Mount archives that are older than the specified time range (e.g. 7d or 12m) from the current time [Borg 2.x+ only]',
+    )
+    mount_group.add_argument(
+        '--newer',
+        metavar='TIMESPAN',
+        help='Mount archives that are newer than the specified time range (e.g. 7d or 12m) from the current time [Borg 2.x+ only]',
+    )
     mount_group.add_argument('--options', dest='options', help='Extra Borg mount options')
     mount_group.add_argument('-h', '--help', action='help', help='Show this help message and exit')
 
-    umount_parser = subparsers.add_parser(
+    umount_parser = action_parsers.add_parser(
         'umount',
-        aliases=SUBPARSER_ALIASES['umount'],
+        aliases=ACTION_ALIASES['umount'],
         help='Unmount a FUSE filesystem that was mounted with "borgmatic mount"',
         description='Unmount a mounted FUSE filesystem',
         add_help=False,
@@ -623,9 +903,9 @@ def make_parsers():
     )
     umount_group.add_argument('-h', '--help', action='help', help='Show this help message and exit')
 
-    restore_parser = subparsers.add_parser(
+    restore_parser = action_parsers.add_parser(
         'restore',
-        aliases=SUBPARSER_ALIASES['restore'],
+        aliases=ACTION_ALIASES['restore'],
         help='Restore database dumps from a named archive',
         description='Restore database dumps from a named archive. (To extract files instead, use "borgmatic extract".)',
         add_help=False,
@@ -641,24 +921,44 @@ def make_parsers():
     restore_group.add_argument(
         '--database',
         metavar='NAME',
-        nargs='+',
         dest='databases',
-        help="Names of databases to restore from archive, defaults to all databases. Note that any databases to restore must be defined in borgmatic's configuration",
+        action='append',
+        help="Name of database to restore from archive, must be defined in borgmatic's configuration, can specify flag multiple times, defaults to all databases",
     )
     restore_group.add_argument(
         '--schema',
         metavar='NAME',
-        nargs='+',
         dest='schemas',
-        help='Names of schemas to restore from the database, defaults to all schemas. Schemas are only supported for PostgreSQL and MongoDB databases',
+        action='append',
+        help='Name of schema to restore from the database, can specify flag multiple times, defaults to all schemas. Schemas are only supported for PostgreSQL and MongoDB databases',
+    )
+    restore_group.add_argument(
+        '--hostname',
+        help='Database hostname to restore to. Defaults to the "restore_hostname" option in borgmatic\'s configuration',
+    )
+    restore_group.add_argument(
+        '--port',
+        help='Port to restore to. Defaults to the "restore_port" option in borgmatic\'s configuration',
+    )
+    restore_group.add_argument(
+        '--username',
+        help='Username with which to connect to the database. Defaults to the "restore_username" option in borgmatic\'s configuration',
+    )
+    restore_group.add_argument(
+        '--password',
+        help='Password with which to connect to the restore database. Defaults to the "restore_password" option in borgmatic\'s configuration',
+    )
+    restore_group.add_argument(
+        '--restore-path',
+        help='Path to restore SQLite database dumps to. Defaults to the "restore_path" option in borgmatic\'s configuration',
     )
     restore_group.add_argument(
         '-h', '--help', action='help', help='Show this help message and exit'
     )
 
-    rlist_parser = subparsers.add_parser(
+    rlist_parser = action_parsers.add_parser(
         'rlist',
-        aliases=SUBPARSER_ALIASES['rlist'],
+        aliases=ACTION_ALIASES['rlist'],
         help='List repository',
         description='List the archives in a repository',
         add_help=False,
@@ -694,11 +994,31 @@ def make_parsers():
     rlist_group.add_argument(
         '--last', metavar='N', help='List last N archives after other filters are applied'
     )
+    rlist_group.add_argument(
+        '--oldest',
+        metavar='TIMESPAN',
+        help='List archives within a specified time range starting from the timestamp of the oldest archive (e.g. 7d or 12m) [Borg 2.x+ only]',
+    )
+    rlist_group.add_argument(
+        '--newest',
+        metavar='TIMESPAN',
+        help='List archives within a time range that ends at timestamp of the newest archive and starts a specified time range ago (e.g. 7d or 12m) [Borg 2.x+ only]',
+    )
+    rlist_group.add_argument(
+        '--older',
+        metavar='TIMESPAN',
+        help='List archives that are older than the specified time range (e.g. 7d or 12m) from the current time [Borg 2.x+ only]',
+    )
+    rlist_group.add_argument(
+        '--newer',
+        metavar='TIMESPAN',
+        help='List archives that are newer than the specified time range (e.g. 7d or 12m) from the current time [Borg 2.x+ only]',
+    )
     rlist_group.add_argument('-h', '--help', action='help', help='Show this help message and exit')
 
-    list_parser = subparsers.add_parser(
+    list_parser = action_parsers.add_parser(
         'list',
-        aliases=SUBPARSER_ALIASES['list'],
+        aliases=ACTION_ALIASES['list'],
         help='List archive',
         description='List the files in an archive or search for a file across archives',
         add_help=False,
@@ -712,16 +1032,16 @@ def make_parsers():
     list_group.add_argument(
         '--path',
         metavar='PATH',
-        nargs='+',
         dest='paths',
-        help='Paths or patterns to list from a single selected archive (via "--archive"), defaults to listing the entire archive',
+        action='append',
+        help='Path or pattern to list from a single selected archive (via "--archive"), can specify flag multiple times, defaults to listing the entire archive',
     )
     list_group.add_argument(
         '--find',
         metavar='PATH',
-        nargs='+',
         dest='find_paths',
-        help='Partial paths or patterns to search for and list across multiple archives',
+        action='append',
+        help='Partial path or pattern to search for and list across multiple archives, can specify flag multiple times',
     )
     list_group.add_argument(
         '--short', default=False, action='store_true', help='Output only path names'
@@ -740,12 +1060,6 @@ def make_parsers():
         metavar='PATTERN',
         help='Only list archive names matching this pattern',
     )
-    list_group.add_argument(
-        '--successful',
-        default=True,
-        action='store_true',
-        help='Deprecated; no effect. Newer versions of Borg shows successful (non-checkpoint) archives by default.',
-    )
     list_group.add_argument(
         '--sort-by', metavar='KEYS', help='Comma-separated list of sorting keys'
     )
@@ -769,9 +1083,9 @@ def make_parsers():
     )
     list_group.add_argument('-h', '--help', action='help', help='Show this help message and exit')
 
-    rinfo_parser = subparsers.add_parser(
+    rinfo_parser = action_parsers.add_parser(
         'rinfo',
-        aliases=SUBPARSER_ALIASES['rinfo'],
+        aliases=ACTION_ALIASES['rinfo'],
         help='Show repository summary information such as disk space used',
         description='Show repository summary information such as disk space used',
         add_help=False,
@@ -786,9 +1100,9 @@ def make_parsers():
     )
     rinfo_group.add_argument('-h', '--help', action='help', help='Show this help message and exit')
 
-    info_parser = subparsers.add_parser(
+    info_parser = action_parsers.add_parser(
         'info',
-        aliases=SUBPARSER_ALIASES['info'],
+        aliases=ACTION_ALIASES['info'],
         help='Show archive summary information such as disk space used',
         description='Show archive summary information such as disk space used',
         add_help=False,
@@ -825,11 +1139,31 @@ def make_parsers():
     info_group.add_argument(
         '--last', metavar='N', help='Show info for last N archives after other filters are applied'
     )
+    info_group.add_argument(
+        '--oldest',
+        metavar='TIMESPAN',
+        help='Show info for archives within a specified time range starting from the timestamp of the oldest archive (e.g. 7d or 12m) [Borg 2.x+ only]',
+    )
+    info_group.add_argument(
+        '--newest',
+        metavar='TIMESPAN',
+        help='Show info for archives within a time range that ends at timestamp of the newest archive and starts a specified time range ago (e.g. 7d or 12m) [Borg 2.x+ only]',
+    )
+    info_group.add_argument(
+        '--older',
+        metavar='TIMESPAN',
+        help='Show info for archives that are older than the specified time range (e.g. 7d or 12m) from the current time [Borg 2.x+ only]',
+    )
+    info_group.add_argument(
+        '--newer',
+        metavar='TIMESPAN',
+        help='Show info for archives that are newer than the specified time range (e.g. 7d or 12m) from the current time [Borg 2.x+ only]',
+    )
     info_group.add_argument('-h', '--help', action='help', help='Show this help message and exit')
 
-    break_lock_parser = subparsers.add_parser(
+    break_lock_parser = action_parsers.add_parser(
         'break-lock',
-        aliases=SUBPARSER_ALIASES['break-lock'],
+        aliases=ACTION_ALIASES['break-lock'],
         help='Break the repository and cache locks left behind by Borg aborting',
         description='Break Borg repository and cache locks left behind by Borg aborting',
         add_help=False,
@@ -843,9 +1177,9 @@ def make_parsers():
         '-h', '--help', action='help', help='Show this help message and exit'
     )
 
-    borg_parser = subparsers.add_parser(
+    borg_parser = action_parsers.add_parser(
         'borg',
-        aliases=SUBPARSER_ALIASES['borg'],
+        aliases=ACTION_ALIASES['borg'],
         help='Run an arbitrary Borg command',
         description="Run an arbitrary Borg command based on borgmatic's configuration",
         add_help=False,
@@ -865,24 +1199,43 @@ def make_parsers():
     )
     borg_group.add_argument('-h', '--help', action='help', help='Show this help message and exit')
 
-    return top_level_parser, subparsers
+    return global_parser, action_parsers, global_plus_action_parser
 
 
 def parse_arguments(*unparsed_arguments):
     '''
     Given command-line arguments with which this script was invoked, parse the arguments and return
-    them as a dict mapping from subparser name (or "global") to an argparse.Namespace instance.
+    them as a dict mapping from action name (or "global") to an argparse.Namespace instance.
+
+    Raise ValueError if the arguments cannot be parsed.
+    Raise SystemExit with an error code of 0 if "--help" was requested.
     '''
-    top_level_parser, subparsers = make_parsers()
-
-    arguments, remaining_arguments = parse_subparser_arguments(
-        unparsed_arguments, subparsers.choices
+    global_parser, action_parsers, global_plus_action_parser = make_parsers()
+    arguments, remaining_action_arguments = parse_arguments_for_actions(
+        unparsed_arguments, action_parsers.choices, global_parser
     )
-    arguments['global'] = top_level_parser.parse_args(remaining_arguments)
 
-    if arguments['global'].excludes_filename:
+    if not arguments['global'].config_paths:
+        arguments['global'].config_paths = collect.get_default_config_paths(expand_home=True)
+
+    for action_name in ('bootstrap', 'generate', 'validate'):
+        if (
+            action_name in arguments.keys() and len(arguments.keys()) > 2
+        ):  # 2 = 1 for 'global' + 1 for the action
+            raise ValueError(
+                f'The {action_name} action cannot be combined with other actions. Please run it separately.'
+            )
+
+    unknown_arguments = get_unparsable_arguments(remaining_action_arguments)
+
+    if unknown_arguments:
+        if '--help' in unknown_arguments or '-h' in unknown_arguments:
+            global_plus_action_parser.print_help()
+            sys.exit(0)
+
+        global_plus_action_parser.print_usage()
         raise ValueError(
-            'The --excludes flag has been replaced with exclude_patterns in configuration.'
+            f"Unrecognized argument{'s' if len(unknown_arguments) > 1 else ''}: {' '.join(unknown_arguments)}"
         )
 
     if 'create' in arguments and arguments['create'].list_files and arguments['create'].progress:

borgmatic/commands/borgmatic.py

@@ -18,6 +18,9 @@ import borgmatic.actions.borg
 import borgmatic.actions.break_lock
 import borgmatic.actions.check
 import borgmatic.actions.compact
+import borgmatic.actions.config.bootstrap
+import borgmatic.actions.config.generate
+import borgmatic.actions.config.validate
 import borgmatic.actions.create
 import borgmatic.actions.export_tar
 import borgmatic.actions.extract
@@ -30,20 +33,19 @@ import borgmatic.actions.restore
 import borgmatic.actions.rinfo
 import borgmatic.actions.rlist
 import borgmatic.actions.transfer
-import borgmatic.commands.completion
+import borgmatic.commands.completion.bash
+import borgmatic.commands.completion.fish
 from borgmatic.borg import umount as borg_umount
 from borgmatic.borg import version as borg_version
 from borgmatic.commands.arguments import parse_arguments
-from borgmatic.config import checks, collect, convert, validate
+from borgmatic.config import checks, collect, validate
 from borgmatic.hooks import command, dispatch, monitor
-from borgmatic.logger import add_custom_log_levels, configure_logging, should_do_markup
+from borgmatic.logger import DISABLED, add_custom_log_levels, configure_logging, should_do_markup
 from borgmatic.signals import configure_signals
 from borgmatic.verbosity import verbosity_to_log_level
 
 logger = logging.getLogger(__name__)
 
-LEGACY_CONFIG_PATH = '/etc/borgmatic/config'
-
 
 def run_configuration(config_filename, config, arguments):
     '''
@@ -56,41 +58,38 @@ def run_configuration(config_filename, config, arguments):
       * JSON output strings from successfully executing any actions that produce JSON
       * logging.LogRecord instances containing errors from any actions or backup hooks that fail
     '''
-    (location, storage, retention, consistency, hooks) = (
-        config.get(section_name, {})
-        for section_name in ('location', 'storage', 'retention', 'consistency', 'hooks')
-    )
     global_arguments = arguments['global']
 
-    local_path = location.get('local_path', 'borg')
-    remote_path = location.get('remote_path')
-    retries = storage.get('retries', 0)
-    retry_wait = storage.get('retry_wait', 0)
+    local_path = config.get('local_path', 'borg')
+    remote_path = config.get('remote_path')
+    retries = config.get('retries', 0)
+    retry_wait = config.get('retry_wait', 0)
     encountered_error = None
     error_repository = ''
     using_primary_action = {'create', 'prune', 'compact', 'check'}.intersection(arguments)
     monitoring_log_level = verbosity_to_log_level(global_arguments.monitoring_verbosity)
+    monitoring_hooks_are_activated = using_primary_action and monitoring_log_level != DISABLED
 
     try:
-        local_borg_version = borg_version.local_borg_version(storage, local_path)
+        local_borg_version = borg_version.local_borg_version(config, local_path)
     except (OSError, CalledProcessError, ValueError) as error:
         yield from log_error_records(f'{config_filename}: Error getting local Borg version', error)
         return
 
     try:
-        if using_primary_action:
+        if monitoring_hooks_are_activated:
             dispatch.call_hooks(
                 'initialize_monitor',
-                hooks,
+                config,
                 config_filename,
                 monitor.MONITOR_HOOK_NAMES,
                 monitoring_log_level,
                 global_arguments.dry_run,
             )
-        if using_primary_action:
+
             dispatch.call_hooks(
                 'ping_monitor',
-                hooks,
+                config,
                 config_filename,
                 monitor.MONITOR_HOOK_NAMES,
                 monitor.State.START,
@@ -106,7 +105,7 @@ def run_configuration(config_filename, config, arguments):
 
     if not encountered_error:
         repo_queue = Queue()
-        for repo in location['repositories']:
+        for repo in config['repositories']:
             repo_queue.put(
                 (repo, 0),
             )
@@ -126,11 +125,7 @@ def run_configuration(config_filename, config, arguments):
                 yield from run_actions(
                     arguments=arguments,
                     config_filename=config_filename,
-                    location=location,
-                    storage=storage,
-                    retention=retention,
-                    consistency=consistency,
-                    hooks=hooks,
+                    config=config,
                     local_path=local_path,
                     remote_path=remote_path,
                     local_borg_version=local_borg_version,
@@ -165,11 +160,11 @@ def run_configuration(config_filename, config, arguments):
                 error_repository = repository['path']
 
     try:
-        if using_primary_action:
+        if monitoring_hooks_are_activated:
             # send logs irrespective of error
             dispatch.call_hooks(
                 'ping_monitor',
-                hooks,
+                config,
                 config_filename,
                 monitor.MONITOR_HOOK_NAMES,
                 monitor.State.LOG,
@@ -185,10 +180,10 @@ def run_configuration(config_filename, config, arguments):
 
     if not encountered_error:
         try:
-            if using_primary_action:
+            if monitoring_hooks_are_activated:
                 dispatch.call_hooks(
                     'ping_monitor',
-                    hooks,
+                    config,
                     config_filename,
                     monitor.MONITOR_HOOK_NAMES,
                     monitor.State.FINISH,
@@ -197,7 +192,7 @@ def run_configuration(config_filename, config, arguments):
                 )
                 dispatch.call_hooks(
                     'destroy_monitor',
-                    hooks,
+                    config,
                     config_filename,
                     monitor.MONITOR_HOOK_NAMES,
                     monitoring_log_level,
@@ -213,8 +208,8 @@ def run_configuration(config_filename, config, arguments):
     if encountered_error and using_primary_action:
         try:
             command.execute_hook(
-                hooks.get('on_error'),
-                hooks.get('umask'),
+                config.get('on_error'),
+                config.get('umask'),
                 config_filename,
                 'on-error',
                 global_arguments.dry_run,
@@ -224,7 +219,7 @@ def run_configuration(config_filename, config, arguments):
             )
             dispatch.call_hooks(
                 'ping_monitor',
-                hooks,
+                config,
                 config_filename,
                 monitor.MONITOR_HOOK_NAMES,
                 monitor.State.FAIL,
@@ -233,7 +228,7 @@ def run_configuration(config_filename, config, arguments):
             )
             dispatch.call_hooks(
                 'destroy_monitor',
-                hooks,
+                config,
                 config_filename,
                 monitor.MONITOR_HOOK_NAMES,
                 monitoring_log_level,
@@ -250,11 +245,7 @@ def run_actions(
     *,
     arguments,
     config_filename,
-    location,
-    storage,
-    retention,
-    consistency,
-    hooks,
+    config,
     local_path,
     remote_path,
     local_borg_version,
@@ -279,13 +270,13 @@ def run_actions(
     hook_context = {
         'repository': repository_path,
         # Deprecated: For backwards compatibility with borgmatic < 1.6.0.
-        'repositories': ','.join([repo['path'] for repo in location['repositories']]),
+        'repositories': ','.join([repo['path'] for repo in config['repositories']]),
         'log_file': global_arguments.log_file if global_arguments.log_file else '',
     }
 
     command.execute_hook(
-        hooks.get('before_actions'),
-        hooks.get('umask'),
+        config.get('before_actions'),
+        config.get('umask'),
         config_filename,
         'pre-actions',
         global_arguments.dry_run,
@@ -296,7 +287,7 @@ def run_actions(
         if action_name == 'rcreate':
             borgmatic.actions.rcreate.run_rcreate(
                 repository,
-                storage,
+                config,
                 local_borg_version,
                 action_arguments,
                 global_arguments,
@@ -306,7 +297,7 @@ def run_actions(
         elif action_name == 'transfer':
             borgmatic.actions.transfer.run_transfer(
                 repository,
-                storage,
+                config,
                 local_borg_version,
                 action_arguments,
                 global_arguments,
@@ -317,9 +308,7 @@ def run_actions(
             yield from borgmatic.actions.create.run_create(
                 config_filename,
                 repository,
-                location,
-                storage,
-                hooks,
+                config,
                 hook_context,
                 local_borg_version,
                 action_arguments,
@@ -332,9 +321,7 @@ def run_actions(
             borgmatic.actions.prune.run_prune(
                 config_filename,
                 repository,
-                storage,
-                retention,
-                hooks,
+                config,
                 hook_context,
                 local_borg_version,
                 action_arguments,
@@ -347,9 +334,7 @@ def run_actions(
             borgmatic.actions.compact.run_compact(
                 config_filename,
                 repository,
-                storage,
-                retention,
-                hooks,
+                config,
                 hook_context,
                 local_borg_version,
                 action_arguments,
@@ -359,14 +344,11 @@ def run_actions(
                 remote_path,
             )
         elif action_name == 'check':
-            if checks.repository_enabled_for_checks(repository, consistency):
+            if checks.repository_enabled_for_checks(repository, config):
                 borgmatic.actions.check.run_check(
                     config_filename,
                     repository,
-                    location,
-                    storage,
-                    consistency,
-                    hooks,
+                    config,
                     hook_context,
                     local_borg_version,
                     action_arguments,
@@ -378,9 +360,7 @@ def run_actions(
             borgmatic.actions.extract.run_extract(
                 config_filename,
                 repository,
-                location,
-                storage,
-                hooks,
+                config,
                 hook_context,
                 local_borg_version,
                 action_arguments,
@@ -391,7 +371,7 @@ def run_actions(
         elif action_name == 'export-tar':
             borgmatic.actions.export_tar.run_export_tar(
                 repository,
-                storage,
+                config,
                 local_borg_version,
                 action_arguments,
                 global_arguments,
@@ -401,7 +381,7 @@ def run_actions(
         elif action_name == 'mount':
             borgmatic.actions.mount.run_mount(
                 repository,
-                storage,
+                config,
                 local_borg_version,
                 action_arguments,
                 global_arguments,
@@ -411,9 +391,7 @@ def run_actions(
         elif action_name == 'restore':
             borgmatic.actions.restore.run_restore(
                 repository,
-                location,
-                storage,
-                hooks,
+                config,
                 local_borg_version,
                 action_arguments,
                 global_arguments,
@@ -423,7 +401,7 @@ def run_actions(
         elif action_name == 'rlist':
             yield from borgmatic.actions.rlist.run_rlist(
                 repository,
-                storage,
+                config,
                 local_borg_version,
                 action_arguments,
                 global_arguments,
@@ -433,7 +411,7 @@ def run_actions(
         elif action_name == 'list':
             yield from borgmatic.actions.list.run_list(
                 repository,
-                storage,
+                config,
                 local_borg_version,
                 action_arguments,
                 global_arguments,
@@ -443,7 +421,7 @@ def run_actions(
         elif action_name == 'rinfo':
             yield from borgmatic.actions.rinfo.run_rinfo(
                 repository,
-                storage,
+                config,
                 local_borg_version,
                 action_arguments,
                 global_arguments,
@@ -453,7 +431,7 @@ def run_actions(
         elif action_name == 'info':
             yield from borgmatic.actions.info.run_info(
                 repository,
-                storage,
+                config,
                 local_borg_version,
                 action_arguments,
                 global_arguments,
@@ -463,7 +441,7 @@ def run_actions(
         elif action_name == 'break-lock':
             borgmatic.actions.break_lock.run_break_lock(
                 repository,
-                storage,
+                config,
                 local_borg_version,
                 action_arguments,
                 global_arguments,
@@ -473,7 +451,7 @@ def run_actions(
         elif action_name == 'borg':
             borgmatic.actions.borg.run_borg(
                 repository,
-                storage,
+                config,
                 local_borg_version,
                 action_arguments,
                 global_arguments,
@@ -482,8 +460,8 @@ def run_actions(
             )
 
     command.execute_hook(
-        hooks.get('after_actions'),
-        hooks.get('umask'),
+        config.get('after_actions'),
+        config.get('umask'),
         config_filename,
         'post-actions',
         global_arguments.dry_run,
@@ -496,6 +474,9 @@ def load_configurations(config_filenames, overrides=None, resolve_env=True):
     Given a sequence of configuration filenames, load and validate each configuration file. Return
     the results as a tuple of: dict of configuration filename to corresponding parsed configuration,
     and sequence of logging.LogRecord instances containing any parse errors.
+
+    Log records are returned here instead of being logged directly because logging isn't yet
+    initialized at this point!
     '''
     # Dict mapping from config filename to corresponding parsed config dict.
     configs = collections.OrderedDict()
@@ -503,6 +484,17 @@ def load_configurations(config_filenames, overrides=None, resolve_env=True):
 
     # Parse and load each configuration file.
     for config_filename in config_filenames:
+        logs.extend(
+            [
+                logging.makeLogRecord(
+                    dict(
+                        levelno=logging.DEBUG,
+                        levelname='DEBUG',
+                        msg=f'{config_filename}: Loading configuration file',
+                    )
+                ),
+            ]
+        )
         try:
             configs[config_filename], parse_logs = validate.parse_configuration(
                 config_filename, validate.schema_filename(), overrides, resolve_env
@@ -552,6 +544,9 @@ def log_record(suppress_log=False, **kwargs):
     return record
 
 
+MAX_CAPTURED_OUTPUT_LENGTH = 1000
+
+
 def log_error_records(
     message, error=None, levelno=logging.CRITICAL, log_command_error_output=False
 ):
@@ -574,12 +569,18 @@ def log_error_records(
     except CalledProcessError as error:
         yield log_record(levelno=levelno, levelname=level_name, msg=message)
         if error.output:
+            try:
+                output = error.output.decode('utf-8')
+            except (UnicodeDecodeError, AttributeError):
+                output = error.output
+
             # Suppress these logs for now and save full error output for the log summary at the end.
             yield log_record(
                 levelno=levelno,
                 levelname=level_name,
-                msg=error.output,
-                suppress_log=not log_command_error_output,
+                msg=output[:MAX_CAPTURED_OUTPUT_LENGTH]
+                + ' ...' * (len(output) > MAX_CAPTURED_OUTPUT_LENGTH),
+                suppress_log=True,
             )
         yield log_record(levelno=levelno, levelname=level_name, msg=error)
     except (ValueError, OSError) as error:
@@ -596,12 +597,106 @@ def get_local_path(configs):
     Arbitrarily return the local path from the first configuration dict. Default to "borg" if not
     set.
     '''
-    return next(iter(configs.values())).get('location', {}).get('local_path', 'borg')
+    return next(iter(configs.values())).get('local_path', 'borg')
+
+
+def collect_highlander_action_summary_logs(configs, arguments, configuration_parse_errors):
+    '''
+    Given a dict of configuration filename to corresponding parsed configuration, parsed
+    command-line arguments as a dict from subparser name to a parsed namespace of arguments, and
+    whether any configuration files encountered errors during parsing, run a highlander action
+    specified in the arguments, if any, and yield a series of logging.LogRecord instances containing
+    summary information.
+
+    A highlander action is an action that cannot coexist with other actions on the borgmatic
+    command-line, and borgmatic exits after processing such an action.
+    '''
+    add_custom_log_levels()
+
+    if 'bootstrap' in arguments:
+        try:
+            # No configuration file is needed for bootstrap.
+            local_borg_version = borg_version.local_borg_version({}, 'borg')
+        except (OSError, CalledProcessError, ValueError) as error:
+            yield from log_error_records('Error getting local Borg version', error)
+            return
+
+        try:
+            borgmatic.actions.config.bootstrap.run_bootstrap(
+                arguments['bootstrap'], arguments['global'], local_borg_version
+            )
+            yield logging.makeLogRecord(
+                dict(
+                    levelno=logging.ANSWER,
+                    levelname='ANSWER',
+                    msg='Bootstrap successful',
+                )
+            )
+        except (
+            CalledProcessError,
+            ValueError,
+            OSError,
+        ) as error:
+            yield from log_error_records(error)
+
+        return
+
+    if 'generate' in arguments:
+        try:
+            borgmatic.actions.config.generate.run_generate(
+                arguments['generate'], arguments['global']
+            )
+            yield logging.makeLogRecord(
+                dict(
+                    levelno=logging.ANSWER,
+                    levelname='ANSWER',
+                    msg='Generate successful',
+                )
+            )
+        except (
+            CalledProcessError,
+            ValueError,
+            OSError,
+        ) as error:
+            yield from log_error_records(error)
+
+        return
+
+    if 'validate' in arguments:
+        if configuration_parse_errors:
+            yield logging.makeLogRecord(
+                dict(
+                    levelno=logging.CRITICAL,
+                    levelname='CRITICAL',
+                    msg='Configuration validation failed',
+                )
+            )
+
+            return
+
+        try:
+            borgmatic.actions.config.validate.run_validate(arguments['validate'], configs)
+
+            yield logging.makeLogRecord(
+                dict(
+                    levelno=logging.ANSWER,
+                    levelname='ANSWER',
+                    msg='All configuration files are valid',
+                )
+            )
+        except (
+            CalledProcessError,
+            ValueError,
+            OSError,
+        ) as error:
+            yield from log_error_records(error)
+
+        return
 
 
 def collect_configuration_run_summary_logs(configs, arguments):
     '''
-    Given a dict of configuration filename to corresponding parsed configuration, and parsed
+    Given a dict of configuration filename to corresponding parsed configuration and parsed
     command-line arguments as a dict from subparser name to a parsed namespace of arguments, run
     each configuration file and yield a series of logging.LogRecord instances containing summary
     information about each run.
@@ -635,10 +730,9 @@ def collect_configuration_run_summary_logs(configs, arguments):
     if 'create' in arguments:
         try:
             for config_filename, config in configs.items():
-                hooks = config.get('hooks', {})
                 command.execute_hook(
-                    hooks.get('before_everything'),
-                    hooks.get('umask'),
+                    config.get('before_everything'),
+                    config.get('umask'),
                     config_filename,
                     'pre-everything',
                     arguments['global'].dry_run,
@@ -683,10 +777,9 @@ def collect_configuration_run_summary_logs(configs, arguments):
     if 'create' in arguments:
         try:
             for config_filename, config in configs.items():
-                hooks = config.get('hooks', {})
                 command.execute_hook(
-                    hooks.get('after_everything'),
-                    hooks.get('umask'),
+                    config.get('after_everything'),
+                    config.get('umask'),
                     config_filename,
                     'post-everything',
                     arguments['global'].dry_run,
@@ -704,7 +797,7 @@ def exit_with_help_link():  # pragma: no cover
     sys.exit(1)
 
 
-def main():  # pragma: no cover
+def main(extra_summary_logs=[]):  # pragma: no cover
     configure_signals()
 
     try:
@@ -725,16 +818,20 @@ def main():  # pragma: no cover
         print(importlib_metadata.version('borgmatic'))
         sys.exit(0)
     if global_arguments.bash_completion:
-        print(borgmatic.commands.completion.bash_completion())
+        print(borgmatic.commands.completion.bash.bash_completion())
         sys.exit(0)
     if global_arguments.fish_completion:
-        print(borgmatic.commands.completion.fish_completion())
+        print(borgmatic.commands.completion.fish.fish_completion())
         sys.exit(0)
 
     config_filenames = tuple(collect.collect_config_filenames(global_arguments.config_paths))
+    global_arguments.used_config_paths = list(config_filenames)
     configs, parse_logs = load_configurations(
         config_filenames, global_arguments.overrides, global_arguments.resolve_env
     )
+    configuration_parse_errors = (
+        (max(log.levelno for log in parse_logs) >= logging.CRITICAL) if parse_logs else False
+    )
 
     any_json_flags = any(
         getattr(sub_arguments, 'json', False) for sub_arguments in arguments.values()
@@ -757,10 +854,18 @@ def main():  # pragma: no cover
         logger.critical(f'Error configuring logging: {error}')
         exit_with_help_link()
 
-    logger.debug('Ensuring legacy configuration is upgraded')
-    convert.guard_configuration_upgraded(LEGACY_CONFIG_PATH, config_filenames)
-
-    summary_logs = parse_logs + list(collect_configuration_run_summary_logs(configs, arguments))
+    summary_logs = (
+        extra_summary_logs
+        + parse_logs
+        + (
+            list(
+                collect_highlander_action_summary_logs(
+                    configs, arguments, configuration_parse_errors
+                )
+            )
+            or list(collect_configuration_run_summary_logs(configs, arguments))
+        )
+    )
     summary_logs_max_level = max(log.levelno for log in summary_logs)
 
     for message in ('', 'summary:'):

borgmatic/commands/completion/actions.py

@@ -0,0 +1,36 @@
+import borgmatic.commands.arguments
+
+
+def upgrade_message(language: str, upgrade_command: str, completion_file: str):
+    return f'''
+Your {language} completions script is from a different version of borgmatic than is
+currently installed. Please upgrade your script so your completions match the
+command-line flags in your installed borgmatic! Try this to upgrade:
+
+    {upgrade_command}
+    source {completion_file}
+'''
+
+
+def available_actions(subparsers, current_action=None):
+    '''
+    Given subparsers as an argparse._SubParsersAction instance and a current action name (if
+    any), return the actions names that can follow the current action on a command-line.
+
+    This takes into account which sub-actions that the current action supports. For instance, if
+    "bootstrap" is a sub-action for "config", then "bootstrap" should be able to follow a current
+    action of "config" but not "list".
+    '''
+    action_to_subactions = borgmatic.commands.arguments.get_subactions_for_actions(
+        subparsers.choices
+    )
+    current_subactions = action_to_subactions.get(current_action)
+
+    if current_subactions:
+        return current_subactions
+
+    all_subactions = set(
+        subaction for subactions in action_to_subactions.values() for subaction in subactions
+    )
+
+    return tuple(action for action in subparsers.choices.keys() if action not in all_subactions)

borgmatic/commands/completion/bash.py

@@ -0,0 +1,66 @@
+import borgmatic.commands.arguments
+import borgmatic.commands.completion.actions
+
+
+def parser_flags(parser):
+    '''
+    Given an argparse.ArgumentParser instance, return its argument flags in a space-separated
+    string.
+    '''
+    return ' '.join(option for action in parser._actions for option in action.option_strings)
+
+
+def bash_completion():
+    '''
+    Return a bash completion script for the borgmatic command. Produce this by introspecting
+    borgmatic's command-line argument parsers.
+    '''
+    (
+        unused_global_parser,
+        action_parsers,
+        global_plus_action_parser,
+    ) = borgmatic.commands.arguments.make_parsers()
+    global_flags = parser_flags(global_plus_action_parser)
+
+    # Avert your eyes.
+    return '\n'.join(
+        (
+            'check_version() {',
+            '    local this_script="$(cat "$BASH_SOURCE" 2> /dev/null)"',
+            '    local installed_script="$(borgmatic --bash-completion 2> /dev/null)"',
+            '    if [ "$this_script" != "$installed_script" ] && [ "$installed_script" != "" ];'
+            f'''        then cat << EOF\n{borgmatic.commands.completion.actions.upgrade_message(
+                    'bash',
+                    'sudo sh -c "borgmatic --bash-completion > $BASH_SOURCE"',
+                    '$BASH_SOURCE',
+                )}\nEOF''',
+            '    fi',
+            '}',
+            'complete_borgmatic() {',
+        )
+        + tuple(
+            '''    if [[ " ${COMP_WORDS[*]} " =~ " %s " ]]; then
+        COMPREPLY=($(compgen -W "%s %s %s" -- "${COMP_WORDS[COMP_CWORD]}"))
+        return 0
+    fi'''
+            % (
+                action,
+                parser_flags(action_parser),
+                ' '.join(
+                    borgmatic.commands.completion.actions.available_actions(action_parsers, action)
+                ),
+                global_flags,
+            )
+            for action, action_parser in reversed(action_parsers.choices.items())
+        )
+        + (
+            '    COMPREPLY=($(compgen -W "%s %s" -- "${COMP_WORDS[COMP_CWORD]}"))'  # noqa: FS003
+            % (
+                ' '.join(borgmatic.commands.completion.actions.available_actions(action_parsers)),
+                global_flags,
+            ),
+            '    (check_version &)',
+            '}',
+            '\ncomplete -o bashdefault -o default -F complete_borgmatic borgmatic',
+        )
+    )

borgmatic/commands/completion/fish.py

@@ -2,72 +2,8 @@ import shlex
 from argparse import Action
 from textwrap import dedent
 
-from borgmatic.commands import arguments
-
-
-def upgrade_message(language: str, upgrade_command: str, completion_file: str):
-    return f'''
-Your {language} completions script is from a different version of borgmatic than is
-currently installed. Please upgrade your script so your completions match the
-command-line flags in your installed borgmatic! Try this to upgrade:
-
-    {upgrade_command}
-    source {completion_file}
-'''
-
-
-def parser_flags(parser):
-    '''
-    Given an argparse.ArgumentParser instance, return its argument flags in a space-separated
-    string.
-    '''
-    return ' '.join(option for action in parser._actions for option in action.option_strings)
-
-
-def bash_completion():
-    '''
-    Return a bash completion script for the borgmatic command. Produce this by introspecting
-    borgmatic's command-line argument parsers.
-    '''
-    top_level_parser, subparsers = arguments.make_parsers()
-    global_flags = parser_flags(top_level_parser)
-    actions = ' '.join(subparsers.choices.keys())
-
-    # Avert your eyes.
-    return '\n'.join(
-        (
-            'check_version() {',
-            '    local this_script="$(cat "$BASH_SOURCE" 2> /dev/null)"',
-            '    local installed_script="$(borgmatic --bash-completion 2> /dev/null)"',
-            '    if [ "$this_script" != "$installed_script" ] && [ "$installed_script" != "" ];'
-            f'''        then cat << EOF\n{upgrade_message(
-                    'bash',
-                    'sudo sh -c "borgmatic --bash-completion > $BASH_SOURCE"',
-                    '$BASH_SOURCE',
-                )}\nEOF''',
-            '    fi',
-            '}',
-            'complete_borgmatic() {',
-        )
-        + tuple(
-            '''    if [[ " ${COMP_WORDS[*]} " =~ " %s " ]]; then
-        COMPREPLY=($(compgen -W "%s %s %s" -- "${COMP_WORDS[COMP_CWORD]}"))
-        return 0
-    fi'''
-            % (action, parser_flags(subparser), actions, global_flags)
-            for action, subparser in subparsers.choices.items()
-        )
-        + (
-            '    COMPREPLY=($(compgen -W "%s %s" -- "${COMP_WORDS[COMP_CWORD]}"))'  # noqa: FS003
-            % (actions, global_flags),
-            '    (check_version &)',
-            '}',
-            '\ncomplete -o bashdefault -o default -F complete_borgmatic borgmatic',
-        )
-    )
-
-
-# fish section
+import borgmatic.commands.arguments
+import borgmatic.commands.completion.actions
 
 
 def has_file_options(action: Action):
@@ -155,18 +91,22 @@ def fish_completion():
     Return a fish completion script for the borgmatic command. Produce this by introspecting
     borgmatic's command-line argument parsers.
     '''
-    top_level_parser, subparsers = arguments.make_parsers()
+    (
+        unused_global_parser,
+        action_parsers,
+        global_plus_action_parser,
+    ) = borgmatic.commands.arguments.make_parsers()
 
-    all_subparsers = ' '.join(action for action in subparsers.choices.keys())
+    all_action_parsers = ' '.join(action for action in action_parsers.choices.keys())
 
     exact_option_args = tuple(
         ' '.join(action.option_strings)
-        for subparser in subparsers.choices.values()
-        for action in subparser._actions
+        for action_parser in action_parsers.choices.values()
+        for action in action_parser._actions
         if has_exact_options(action)
     ) + tuple(
         ' '.join(action.option_strings)
-        for action in top_level_parser._actions
+        for action in global_plus_action_parser._actions
         if len(action.option_strings) > 0
         if has_exact_options(action)
     )
@@ -182,7 +122,7 @@ def fish_completion():
                         set this_script (cat $this_filename 2> /dev/null)
                         set installed_script (borgmatic --fish-completion 2> /dev/null)
                         if [ "$this_script" != "$installed_script" ] && [ "$installed_script" != "" ]
-                            echo "{upgrade_message(
+                            echo "{borgmatic.commands.completion.actions.upgrade_message(
                             'fish',
                             'borgmatic --fish-completion | sudo tee $this_filename',
                             '$this_filename',
@@ -208,29 +148,29 @@ def fish_completion():
                 return 1
             end
 
-            set --local subparser_condition "not __fish_seen_subcommand_from {all_subparsers}"
+            set --local action_parser_condition "not __fish_seen_subcommand_from {all_action_parsers}"
             set --local exact_option_condition "not __borgmatic_current_arg {' '.join(exact_option_args)}"
             '''
         )
-        + ('\n# subparser completions',)
+        + ('\n# action_parser completions',)
         + tuple(
-            f'''complete -c borgmatic -f -n "$subparser_condition" -n "$exact_option_condition" -a '{action_name}' -d {shlex.quote(subparser.description)}'''
-            for action_name, subparser in subparsers.choices.items()
+            f'''complete -c borgmatic -f -n "$action_parser_condition" -n "$exact_option_condition" -a '{action_name}' -d {shlex.quote(action_parser.description)}'''
+            for action_name, action_parser in action_parsers.choices.items()
         )
         + ('\n# global flags',)
         + tuple(
             # -n is checked in order, so put faster / more likely to be true checks first
             f'''complete -c borgmatic -f -n "$exact_option_condition" -a '{' '.join(action.option_strings)}' -d {shlex.quote(action.help)}{exact_options_completion(action)}'''
-            for action in top_level_parser._actions
+            for action in global_plus_action_parser._actions
             # ignore the noargs action, as this is an impossible completion for fish
             if len(action.option_strings) > 0
             if 'Deprecated' not in action.help
         )
-        + ('\n# subparser flags',)
+        + ('\n# action_parser flags',)
         + tuple(
             f'''complete -c borgmatic -f -n "$exact_option_condition" -a '{' '.join(action.option_strings)}' -d {shlex.quote(action.help)} -n "__fish_seen_subcommand_from {action_name}"{exact_options_completion(action)}'''
-            for action_name, subparser in subparsers.choices.items()
-            for action in subparser._actions
-            if 'Deprecated' not in action.help
+            for action_name, action_parser in action_parsers.choices.items()
+            for action in action_parser._actions
+            if 'Deprecated' not in (action.help or ())
         )
     )

borgmatic/commands/convert_config.py

@@ -1,102 +0,0 @@
-import os
-import sys
-import textwrap
-from argparse import ArgumentParser
-
-from ruamel import yaml
-
-from borgmatic.config import convert, generate, legacy, validate
-
-DEFAULT_SOURCE_CONFIG_FILENAME = '/etc/borgmatic/config'
-DEFAULT_SOURCE_EXCLUDES_FILENAME = '/etc/borgmatic/excludes'
-DEFAULT_DESTINATION_CONFIG_FILENAME = '/etc/borgmatic/config.yaml'
-
-
-def parse_arguments(*arguments):
-    '''
-    Given command-line arguments with which this script was invoked, parse the arguments and return
-    them as an ArgumentParser instance.
-    '''
-    parser = ArgumentParser(
-        description='''
-            Convert legacy INI-style borgmatic configuration and excludes files to a single YAML
-            configuration file. Note that this replaces any comments from the source files.
-        '''
-    )
-    parser.add_argument(
-        '-s',
-        '--source-config',
-        dest='source_config_filename',
-        default=DEFAULT_SOURCE_CONFIG_FILENAME,
-        help=f'Source INI-style configuration filename. Default: {DEFAULT_SOURCE_CONFIG_FILENAME}',
-    )
-    parser.add_argument(
-        '-e',
-        '--source-excludes',
-        dest='source_excludes_filename',
-        default=DEFAULT_SOURCE_EXCLUDES_FILENAME
-        if os.path.exists(DEFAULT_SOURCE_EXCLUDES_FILENAME)
-        else None,
-        help='Excludes filename',
-    )
-    parser.add_argument(
-        '-d',
-        '--destination-config',
-        dest='destination_config_filename',
-        default=DEFAULT_DESTINATION_CONFIG_FILENAME,
-        help=f'Destination YAML configuration filename. Default: {DEFAULT_DESTINATION_CONFIG_FILENAME}',
-    )
-
-    return parser.parse_args(arguments)
-
-
-TEXT_WRAP_CHARACTERS = 80
-
-
-def display_result(args):  # pragma: no cover
-    result_lines = textwrap.wrap(
-        f'Your borgmatic configuration has been upgraded. Please review the result in {args.destination_config_filename}.',
-        TEXT_WRAP_CHARACTERS,
-    )
-
-    excludes_phrase = (
-        f' and {args.source_excludes_filename}' if args.source_excludes_filename else ''
-    )
-    delete_lines = textwrap.wrap(
-        f'Once you are satisfied, you can safely delete {args.source_config_filename}{excludes_phrase}.',
-        TEXT_WRAP_CHARACTERS,
-    )
-
-    print('\n'.join(result_lines))
-    print()
-    print('\n'.join(delete_lines))
-
-
-def main():  # pragma: no cover
-    try:
-        args = parse_arguments(*sys.argv[1:])
-        schema = yaml.round_trip_load(open(validate.schema_filename()).read())
-        source_config = legacy.parse_configuration(
-            args.source_config_filename, legacy.CONFIG_FORMAT
-        )
-        source_config_file_mode = os.stat(args.source_config_filename).st_mode
-        source_excludes = (
-            open(args.source_excludes_filename).read().splitlines()
-            if args.source_excludes_filename
-            else []
-        )
-
-        destination_config = convert.convert_legacy_parsed_config(
-            source_config, source_excludes, schema
-        )
-
-        generate.write_configuration(
-            args.destination_config_filename,
-            generate.render_configuration(destination_config),
-            mode=source_config_file_mode,
-        )
-
-        display_result(args)
-    except (ValueError, OSError) as error:
-        print(error, file=sys.stderr)
-        sys.exit(1)

borgmatic/commands/generate_config.py

@@ -1,63 +1,17 @@
+import logging
 import sys
-from argparse import ArgumentParser
 
-from borgmatic.config import generate, validate
-
-DEFAULT_DESTINATION_CONFIG_FILENAME = '/etc/borgmatic/config.yaml'
+import borgmatic.commands.borgmatic
 
 
-def parse_arguments(*arguments):
-    '''
-    Given command-line arguments with which this script was invoked, parse the arguments and return
-    them as an ArgumentParser instance.
-    '''
-    parser = ArgumentParser(description='Generate a sample borgmatic YAML configuration file.')
-    parser.add_argument(
-        '-s',
-        '--source',
-        dest='source_filename',
-        help='Optional YAML configuration file to merge into the generated configuration, useful for upgrading your configuration',
-    )
-    parser.add_argument(
-        '-d',
-        '--destination',
-        dest='destination_filename',
-        default=DEFAULT_DESTINATION_CONFIG_FILENAME,
-        help=f'Destination YAML configuration file, default: {DEFAULT_DESTINATION_CONFIG_FILENAME}',
-    )
-    parser.add_argument(
-        '--overwrite',
-        default=False,
-        action='store_true',
-        help='Whether to overwrite any existing destination file, defaults to false',
-    )
-
-    return parser.parse_args(arguments)
-
-
-def main():  # pragma: no cover
-    try:
-        args = parse_arguments(*sys.argv[1:])
-
-        generate.generate_sample_configuration(
-            args.source_filename,
-            args.destination_filename,
-            validate.schema_filename(),
-            overwrite=args.overwrite,
+def main():
+    warning_log = logging.makeLogRecord(
+        dict(
+            levelno=logging.WARNING,
+            levelname='WARNING',
+            msg='generate-borgmatic-config is deprecated and will be removed from a future release. Please use "borgmatic config generate" instead.',
         )
+    )
 
-        print(f'Generated a sample configuration file at {args.destination_filename}.')
-        print()
-        if args.source_filename:
-            print(f'Merged in the contents of configuration file at {args.source_filename}.')
-            print('To review the changes made, run:')
-            print()
-            print(f'    diff --unified {args.source_filename} {args.destination_filename}')
-            print()
-        print('This includes all available configuration options with example values. The few')
-        print('required options are indicated. Please edit the file to suit your needs.')
-        print()
-        print('If you ever need help: https://torsion.org/borgmatic/#issues')
-    except (ValueError, OSError) as error:
-        print(error, file=sys.stderr)
-        sys.exit(1)
+    sys.argv = ['borgmatic', 'config', 'generate'] + sys.argv[1:]
+    borgmatic.commands.borgmatic.main([warning_log])

borgmatic/commands/validate_config.py

@@ -1,68 +1,17 @@
 import logging
 import sys
-from argparse import ArgumentParser
 
-import borgmatic.config.generate
-from borgmatic.config import collect, validate
-
-logger = logging.getLogger(__name__)
+import borgmatic.commands.borgmatic
 
 
-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=f'Configuration filenames or directories, defaults to: {config_paths}',
-    )
-    parser.add_argument(
-        '-s',
-        '--show',
-        action='store_true',
-        help='Show the validated configuration after all include merging has occurred',
+def main():
+    warning_log = logging.makeLogRecord(
+        dict(
+            levelno=logging.WARNING,
+            levelname='WARNING',
+            msg='validate-borgmatic-config is deprecated and will be removed from a future release. Please use "borgmatic config validate" instead.',
+        )
     )
 
-    return parser.parse_args(arguments)
-
-
-def main():  # pragma: no cover
-    arguments = parse_arguments(*sys.argv[1:])
-
-    logging.basicConfig(level=logging.INFO, format='%(message)s')
-
-    config_filenames = tuple(collect.collect_config_filenames(arguments.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:
-            config, parse_logs = validate.parse_configuration(
-                config_filename, validate.schema_filename()
-            )
-        except (ValueError, OSError, validate.Validation_error) as error:
-            logging.critical(f'{config_filename}: Error parsing configuration file')
-            logging.critical(error)
-            found_issues = True
-        else:
-            for log in parse_logs:
-                logger.handle(log)
-
-            if arguments.show:
-                print('---')
-                print(borgmatic.config.generate.render_configuration(config))
-
-    if found_issues:
-        sys.exit(1)
-
-    logger.info(f"All given configuration files are valid: {', '.join(config_filenames)}")
+    sys.argv = ['borgmatic', 'config', 'validate'] + sys.argv[1:]
+    borgmatic.commands.borgmatic.main([warning_log])

borgmatic/config/collect.py

@@ -24,9 +24,9 @@ def get_default_config_paths(expand_home=True):
 def collect_config_filenames(config_paths):
     '''
     Given a sequence of config paths, both filenames and directories, resolve that to an iterable
-    of files. Accomplish this by listing any given directories looking for contained config files
-    (ending with the ".yaml" or ".yml" extension). This is non-recursive, so any directories within the given
-    directories are ignored.
+    of absolute files. Accomplish this by listing any given directories looking for contained config
+    files (ending with the ".yaml" or ".yml" extension). This is non-recursive, so any directories
+    within the given directories are ignored.
 
     Return paths even if they don't exist on disk, so the user can find out about missing
     configuration paths. However, skip a default config path if it's missing, so the user doesn't
@@ -41,7 +41,7 @@ def collect_config_filenames(config_paths):
             continue
 
         if not os.path.isdir(path) or not exists:
-            yield path
+            yield os.path.abspath(path)
             continue
 
         if not os.access(path, os.R_OK):
@@ -51,4 +51,4 @@ def collect_config_filenames(config_paths):
             full_filename = os.path.join(path, filename)
             matching_filetype = full_filename.endswith('.yaml') or full_filename.endswith('.yml')
             if matching_filetype and not os.path.isdir(full_filename):
-                yield full_filename
+                yield os.path.abspath(full_filename)

borgmatic/config/convert.py

@@ -1,95 +0,0 @@
-import os
-
-from ruamel import yaml
-
-from borgmatic.config import generate
-
-
-def _convert_section(source_section_config, section_schema):
-    '''
-    Given a legacy Parsed_config instance for a single section, convert it to its corresponding
-    yaml.comments.CommentedMap representation in preparation for actual serialization to YAML.
-
-    Where integer types exist in the given section schema, convert their values to integers.
-    '''
-    destination_section_config = yaml.comments.CommentedMap(
-        [
-            (
-                option_name,
-                int(option_value)
-                if section_schema['properties'].get(option_name, {}).get('type') == 'integer'
-                else option_value,
-            )
-            for option_name, option_value in source_section_config.items()
-        ]
-    )
-
-    return destination_section_config
-
-
-def convert_legacy_parsed_config(source_config, source_excludes, schema):
-    '''
-    Given a legacy Parsed_config instance loaded from an INI-style config file and a list of exclude
-    patterns, convert them to a corresponding yaml.comments.CommentedMap representation in
-    preparation for serialization to a single YAML config file.
-
-    Additionally, use the given schema as a source of helpful comments to include within the
-    returned CommentedMap.
-    '''
-    destination_config = yaml.comments.CommentedMap(
-        [
-            (section_name, _convert_section(section_config, schema['properties'][section_name]))
-            for section_name, section_config in source_config._asdict().items()
-        ]
-    )
-
-    # Split space-separated values into actual lists, make "repository" into a list, and merge in
-    # excludes.
-    location = destination_config['location']
-    location['source_directories'] = source_config.location['source_directories'].split(' ')
-    location['repositories'] = [location.pop('repository')]
-    location['exclude_patterns'] = source_excludes
-
-    if source_config.consistency.get('checks'):
-        destination_config['consistency']['checks'] = source_config.consistency['checks'].split(' ')
-
-    # Add comments to each section, and then add comments to the fields in each section.
-    generate.add_comments_to_configuration_object(destination_config, schema)
-
-    for section_name, section_config in destination_config.items():
-        generate.add_comments_to_configuration_object(
-            section_config, schema['properties'][section_name], indent=generate.INDENT
-        )
-
-    return destination_config
-
-
-class Legacy_configuration_not_upgraded(FileNotFoundError):
-    def __init__(self):
-        super(Legacy_configuration_not_upgraded, self).__init__(
-            '''borgmatic changed its configuration file format in version 1.1.0 from INI-style
-to YAML. This better supports validation, and has a more natural way to express
-lists of values. To upgrade your existing configuration, run:
-
-    sudo upgrade-borgmatic-config
-
-That will generate a new YAML configuration file at /etc/borgmatic/config.yaml
-(by default) using the values from both your existing configuration and excludes
-files. The new version of borgmatic will consume the YAML configuration file
-instead of the old one.'''
-        )
-
-
-def guard_configuration_upgraded(source_config_filename, destination_config_filenames):
-    '''
-    If legacy source configuration exists but no destination upgraded configs do, raise
-    Legacy_configuration_not_upgraded.
-
-    The idea is that we want to alert the user about upgrading their config if they haven't already.
-    '''
-    destination_config_exists = any(
-        os.path.exists(filename) for filename in destination_config_filenames
-    )
-
-    if os.path.exists(source_config_filename) and not destination_config_exists:
-        raise Legacy_configuration_not_upgraded()

borgmatic/config/generate.py

@@ -11,7 +11,7 @@ INDENT = 4
 SEQUENCE_INDENT = 2
 
 
-def _insert_newline_before_comment(config, field_name):
+def insert_newline_before_comment(config, field_name):
     '''
     Using some ruamel.yaml black magic, insert a blank line in the config right before the given
     field and its comments.
@@ -21,10 +21,10 @@ def _insert_newline_before_comment(config, field_name):
     )
 
 
-def _schema_to_sample_configuration(schema, level=0, parent_is_sequence=False):
+def schema_to_sample_configuration(schema, level=0, parent_is_sequence=False):
     '''
     Given a loaded configuration schema, generate and return sample config for it. Include comments
-    for each section based on the schema "description".
+    for each option based on the schema "description".
     '''
     schema_type = schema.get('type')
     example = schema.get('example')
@@ -33,13 +33,13 @@ def _schema_to_sample_configuration(schema, level=0, parent_is_sequence=False):
 
     if schema_type == 'array':
         config = yaml.comments.CommentedSeq(
-            [_schema_to_sample_configuration(schema['items'], level, parent_is_sequence=True)]
+            [schema_to_sample_configuration(schema['items'], level, parent_is_sequence=True)]
         )
         add_comments_to_configuration_sequence(config, schema, indent=(level * INDENT))
     elif schema_type == 'object':
         config = yaml.comments.CommentedMap(
             [
-                (field_name, _schema_to_sample_configuration(sub_schema, level + 1))
+                (field_name, schema_to_sample_configuration(sub_schema, level + 1))
                 for field_name, sub_schema in schema['properties'].items()
             ]
         )
@@ -53,13 +53,13 @@ def _schema_to_sample_configuration(schema, level=0, parent_is_sequence=False):
     return config
 
 
-def _comment_out_line(line):
+def comment_out_line(line):
     # If it's already is commented out (or empty), there's nothing further to do!
     stripped_line = line.lstrip()
     if not stripped_line or stripped_line.startswith('#'):
         return line
 
-    # Comment out the names of optional sections, inserting the '#' after any indent for aesthetics.
+    # Comment out the names of optional options, inserting the '#' after any indent for aesthetics.
     matches = re.match(r'(\s*)', line)
     indent_spaces = matches.group(0) if matches else ''
     count_indent_spaces = len(indent_spaces)
@@ -67,7 +67,7 @@ def _comment_out_line(line):
     return '# '.join((indent_spaces, line[count_indent_spaces:]))
 
 
-def _comment_out_optional_configuration(rendered_config):
+def comment_out_optional_configuration(rendered_config):
     '''
     Post-process a rendered configuration string to comment out optional key/values, as determined
     by a sentinel in the comment before each key.
@@ -92,7 +92,7 @@ def _comment_out_optional_configuration(rendered_config):
         if not line.strip():
             optional = False
 
-        lines.append(_comment_out_line(line) if optional else line)
+        lines.append(comment_out_line(line) if optional else line)
 
     return '\n'.join(lines)
 
@@ -165,7 +165,6 @@ def add_comments_to_configuration_sequence(config, schema, indent=0):
         return
 
 
-REQUIRED_SECTION_NAMES = {'location', 'retention'}
 REQUIRED_KEYS = {'source_directories', 'repositories', 'keep_daily'}
 COMMENTED_OUT_SENTINEL = 'COMMENT_OUT'
 
@@ -185,7 +184,7 @@ def add_comments_to_configuration_object(config, schema, indent=0, skip_first=Fa
         # If this is an optional key, add an indicator to the comment flagging it to be commented
         # out from the sample configuration. This sentinel is consumed by downstream processing that
         # does the actual commenting out.
-        if field_name not in REQUIRED_SECTION_NAMES and field_name not in REQUIRED_KEYS:
+        if field_name not in REQUIRED_KEYS:
             description = (
                 '\n'.join((description, COMMENTED_OUT_SENTINEL))
                 if description
@@ -199,7 +198,7 @@ def add_comments_to_configuration_object(config, schema, indent=0, skip_first=Fa
         config.yaml_set_comment_before_after_key(key=field_name, before=description, indent=indent)
 
         if index > 0:
-            _insert_newline_before_comment(config, field_name)
+            insert_newline_before_comment(config, field_name)
 
 
 RUAMEL_YAML_COMMENTS_INDEX = 1
@@ -267,7 +266,7 @@ def merge_source_configuration_into_destination(destination_config, source_confi
 
 
 def generate_sample_configuration(
-    source_filename, destination_filename, schema_filename, overwrite=False
+    dry_run, source_filename, destination_filename, schema_filename, overwrite=False
 ):
     '''
     Given an optional source configuration filename, and a required destination configuration
@@ -284,11 +283,14 @@ def generate_sample_configuration(
         normalize.normalize(source_filename, source_config)
 
     destination_config = merge_source_configuration_into_destination(
-        _schema_to_sample_configuration(schema), source_config
+        schema_to_sample_configuration(schema), source_config
     )
 
+    if dry_run:
+        return
+
     write_configuration(
         destination_filename,
-        _comment_out_optional_configuration(render_configuration(destination_config)),
+        comment_out_optional_configuration(render_configuration(destination_config)),
         overwrite=overwrite,
     )

borgmatic/config/legacy.py

@@ -1,146 +0,0 @@
-from collections import OrderedDict, namedtuple
-from configparser import RawConfigParser
-
-Section_format = namedtuple('Section_format', ('name', 'options'))
-Config_option = namedtuple('Config_option', ('name', 'value_type', 'required'))
-
-
-def option(name, value_type=str, required=True):
-    '''
-    Given a config file option name, an expected type for its value, and whether it's required,
-    return a Config_option capturing that information.
-    '''
-    return Config_option(name, value_type, required)
-
-
-CONFIG_FORMAT = (
-    Section_format(
-        'location',
-        (
-            option('source_directories'),
-            option('one_file_system', value_type=bool, required=False),
-            option('remote_path', required=False),
-            option('repository'),
-        ),
-    ),
-    Section_format(
-        'storage',
-        (
-            option('encryption_passphrase', required=False),
-            option('compression', required=False),
-            option('umask', required=False),
-        ),
-    ),
-    Section_format(
-        'retention',
-        (
-            option('keep_within', required=False),
-            option('keep_hourly', int, required=False),
-            option('keep_daily', int, required=False),
-            option('keep_weekly', int, required=False),
-            option('keep_monthly', int, required=False),
-            option('keep_yearly', int, required=False),
-            option('prefix', required=False),
-        ),
-    ),
-    Section_format(
-        'consistency', (option('checks', required=False), option('check_last', required=False))
-    ),
-)
-
-
-def validate_configuration_format(parser, config_format):
-    '''
-    Given an open RawConfigParser and an expected config file format, validate that the parsed
-    configuration file has the expected sections, that any required options are present in those
-    sections, and that there aren't any unexpected options.
-
-    A section is required if any of its contained options are required.
-
-    Raise ValueError if anything is awry.
-    '''
-    section_names = set(parser.sections())
-    required_section_names = tuple(
-        section.name
-        for section in config_format
-        if any(option.required for option in section.options)
-    )
-
-    unknown_section_names = section_names - set(
-        section_format.name for section_format in config_format
-    )
-    if unknown_section_names:
-        raise ValueError(f"Unknown config sections found: {', '.join(unknown_section_names)}")
-
-    missing_section_names = set(required_section_names) - section_names
-    if missing_section_names:
-        raise ValueError(f"Missing config sections: {', '.join(missing_section_names)}")
-
-    for section_format in config_format:
-        if section_format.name not in section_names:
-            continue
-
-        option_names = parser.options(section_format.name)
-        expected_options = section_format.options
-
-        unexpected_option_names = set(option_names) - set(
-            option.name for option in expected_options
-        )
-
-        if unexpected_option_names:
-            raise ValueError(
-                f"Unexpected options found in config section {section_format.name}: {', '.join(sorted(unexpected_option_names))}",
-            )
-
-        missing_option_names = tuple(
-            option.name
-            for option in expected_options
-            if option.required
-            if option.name not in option_names
-        )
-
-        if missing_option_names:
-            raise ValueError(
-                f"Required options missing from config section {section_format.name}: {', '.join(missing_option_names)}",
-            )
-
-
-def parse_section_options(parser, section_format):
-    '''
-    Given an open RawConfigParser and an expected section format, return the option values from that
-    section as a dict mapping from option name to value. Omit those options that are not present in
-    the parsed options.
-
-    Raise ValueError if any option values cannot be coerced to the expected Python data type.
-    '''
-    type_getter = {str: parser.get, int: parser.getint, bool: parser.getboolean}
-
-    return OrderedDict(
-        (option.name, type_getter[option.value_type](section_format.name, option.name))
-        for option in section_format.options
-        if parser.has_option(section_format.name, option.name)
-    )
-
-
-def parse_configuration(config_filename, config_format):
-    '''
-    Given a config filename and an expected config file format, return the parsed configuration
-    as a namedtuple with one attribute for each parsed section.
-
-    Raise IOError if the file cannot be read, or ValueError if the format is not as expected.
-    '''
-    parser = RawConfigParser()
-    if not parser.read(config_filename):
-        raise ValueError(f'Configuration file cannot be opened: {config_filename}')
-
-    validate_configuration_format(parser, config_format)
-
-    # Describes a parsed configuration, where each attribute is the name of a configuration file
-    # section and each value is a dict of that section's parsed options.
-    Parsed_config = namedtuple(
-        'Parsed_config', (section_format.name for section_format in config_format)
-    )
-
-    return Parsed_config(
-        *(parse_section_options(parser, section_format) for section_format in config_format)
-    )

borgmatic/config/load.py

@@ -97,8 +97,8 @@ class Include_constructor(ruamel.yaml.SafeConstructor):
         ```
 
         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.
+        example, any "option" with sub-options in common.yaml will get merged into the corresponding
+        "option" with sub-options in the example configuration file.
         '''
         representer = ruamel.yaml.representer.SafeRepresenter()
 
@@ -116,7 +116,7 @@ def load_configuration(filename):
     '''
     Load the given configuration file and return its contents as a data structure of nested dicts
     and lists. Also, replace any "{constant}" strings with the value of the "constant" key in the
-    "constants" section of the configuration file.
+    "constants" option of the configuration file.
 
     Raise ruamel.yaml.error.YAMLError if something goes wrong parsing the YAML, or RecursionError
     if there are too many recursive includes.
@@ -223,8 +223,10 @@ def deep_merge_nodes(nodes):
     If a mapping or sequence node has a YAML "!retain" tag, then that node is not merged.
 
     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.
+    configuration file into another for reuse, such that a configuration option with sub-options
+    does not completely replace the corresponding option in a merged file.
+
+    Raise ValueError if a merge is implied using two incompatible types.
     '''
     # Map from original node key/value to the replacement merged node. DELETED_NODE as a replacement
     # node indications deletion.
@@ -239,6 +241,11 @@ def deep_merge_nodes(nodes):
 
             # 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:
+                if not type(a_value) is type(b_value):
+                    raise ValueError(
+                        f'Incompatible types found when trying to merge "{a_key.value}:" values across configuration files: {type(a_value).id} and {type(b_value).id}'
+                    )
+
                 # 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
 

borgmatic/config/normalize.py

@@ -2,67 +2,207 @@ import logging
 import os
 
 
+def normalize_sections(config_filename, config):
+    '''
+    Given a configuration filename and a configuration dict of its loaded contents, airlift any
+    options out of sections ("location:", etc.) to the global scope and delete those sections.
+    Return any log message warnings produced based on the normalization performed.
+
+    Raise ValueError if the "prefix" option is set in both "location" and "consistency" sections.
+    '''
+    location = config.get('location') or {}
+    storage = config.get('storage') or {}
+    consistency = config.get('consistency') or {}
+    hooks = config.get('hooks') or {}
+
+    if (
+        location.get('prefix')
+        and consistency.get('prefix')
+        and location.get('prefix') != consistency.get('prefix')
+    ):
+        raise ValueError(
+            'The retention prefix and the consistency prefix cannot have different values (unless one is not set).'
+        )
+
+    if storage.get('umask') and hooks.get('umask') and storage.get('umask') != hooks.get('umask'):
+        raise ValueError(
+            'The storage umask and the hooks umask cannot have different values (unless one is not set).'
+        )
+
+    any_section_upgraded = False
+
+    # Move any options from deprecated sections into the global scope.
+    for section_name in ('location', 'storage', 'retention', 'consistency', 'output', 'hooks'):
+        section_config = config.get(section_name)
+
+        if section_config:
+            any_section_upgraded = True
+            del config[section_name]
+            config.update(section_config)
+
+    if any_section_upgraded:
+        return [
+            logging.makeLogRecord(
+                dict(
+                    levelno=logging.WARNING,
+                    levelname='WARNING',
+                    msg=f'{config_filename}: Configuration sections (like location: and storage:) are deprecated and support will be removed from a future release. To prepare for this, move your options out of sections to the global scope.',
+                )
+            )
+        ]
+
+    return []
+
+
 def normalize(config_filename, config):
     '''
     Given a configuration filename and a configuration dict of its loaded contents, apply particular
     hard-coded rules to normalize the configuration to adhere to the current schema. Return any log
     message warnings produced based on the normalization performed.
+
+    Raise ValueError the configuration cannot be normalized.
     '''
-    logs = []
-    location = config.get('location') or {}
-    storage = config.get('storage') or {}
-    consistency = config.get('consistency') or {}
-    hooks = config.get('hooks') or {}
+    logs = normalize_sections(config_filename, config)
 
     # Upgrade exclude_if_present from a string to a list.
-    exclude_if_present = location.get('exclude_if_present')
+    exclude_if_present = config.get('exclude_if_present')
     if isinstance(exclude_if_present, str):
-        config['location']['exclude_if_present'] = [exclude_if_present]
+        logs.append(
+            logging.makeLogRecord(
+                dict(
+                    levelno=logging.WARNING,
+                    levelname='WARNING',
+                    msg=f'{config_filename}: The exclude_if_present option now expects a list value. String values for this option are deprecated and support will be removed from a future release.',
+                )
+            )
+        )
+        config['exclude_if_present'] = [exclude_if_present]
 
     # Upgrade various monitoring hooks from a string to a dict.
-    healthchecks = hooks.get('healthchecks')
+    healthchecks = config.get('healthchecks')
     if isinstance(healthchecks, str):
-        config['hooks']['healthchecks'] = {'ping_url': healthchecks}
+        logs.append(
+            logging.makeLogRecord(
+                dict(
+                    levelno=logging.WARNING,
+                    levelname='WARNING',
+                    msg=f'{config_filename}: The healthchecks hook now expects a mapping value. String values for this option are deprecated and support will be removed from a future release.',
+                )
+            )
+        )
+        config['healthchecks'] = {'ping_url': healthchecks}
 
-    cronitor = hooks.get('cronitor')
+    cronitor = config.get('cronitor')
     if isinstance(cronitor, str):
-        config['hooks']['cronitor'] = {'ping_url': cronitor}
+        logs.append(
+            logging.makeLogRecord(
+                dict(
+                    levelno=logging.WARNING,
+                    levelname='WARNING',
+                    msg=f'{config_filename}: The healthchecks hook now expects key/value pairs. String values for this option are deprecated and support will be removed from a future release.',
+                )
+            )
+        )
+        config['cronitor'] = {'ping_url': cronitor}
 
-    pagerduty = hooks.get('pagerduty')
+    pagerduty = config.get('pagerduty')
     if isinstance(pagerduty, str):
-        config['hooks']['pagerduty'] = {'integration_key': pagerduty}
+        logs.append(
+            logging.makeLogRecord(
+                dict(
+                    levelno=logging.WARNING,
+                    levelname='WARNING',
+                    msg=f'{config_filename}: The healthchecks hook now expects key/value pairs. String values for this option are deprecated and support will be removed from a future release.',
+                )
+            )
+        )
+        config['pagerduty'] = {'integration_key': pagerduty}
 
-    cronhub = hooks.get('cronhub')
+    cronhub = config.get('cronhub')
     if isinstance(cronhub, str):
-        config['hooks']['cronhub'] = {'ping_url': cronhub}
+        logs.append(
+            logging.makeLogRecord(
+                dict(
+                    levelno=logging.WARNING,
+                    levelname='WARNING',
+                    msg=f'{config_filename}: The healthchecks hook now expects key/value pairs. String values for this option are deprecated and support will be removed from a future release.',
+                )
+            )
+        )
+        config['cronhub'] = {'ping_url': cronhub}
 
     # Upgrade consistency checks from a list of strings to a list of dicts.
-    checks = consistency.get('checks')
+    checks = config.get('checks')
     if isinstance(checks, list) and len(checks) and isinstance(checks[0], str):
-        config['consistency']['checks'] = [{'name': check_type} for check_type in checks]
+        logs.append(
+            logging.makeLogRecord(
+                dict(
+                    levelno=logging.WARNING,
+                    levelname='WARNING',
+                    msg=f'{config_filename}: The checks option now expects a list of key/value pairs. Lists of strings for this option are deprecated and support will be removed from a future release.',
+                )
+            )
+        )
+        config['checks'] = [{'name': check_type} for check_type in checks]
 
     # Rename various configuration options.
-    numeric_owner = location.pop('numeric_owner', None)
+    numeric_owner = config.pop('numeric_owner', None)
     if numeric_owner is not None:
-        config['location']['numeric_ids'] = numeric_owner
+        logs.append(
+            logging.makeLogRecord(
+                dict(
+                    levelno=logging.WARNING,
+                    levelname='WARNING',
+                    msg=f'{config_filename}: The numeric_owner option has been renamed to numeric_ids. numeric_owner is deprecated and support will be removed from a future release.',
+                )
+            )
+        )
+        config['numeric_ids'] = numeric_owner
 
-    bsd_flags = location.pop('bsd_flags', None)
+    bsd_flags = config.pop('bsd_flags', None)
     if bsd_flags is not None:
-        config['location']['flags'] = bsd_flags
+        logs.append(
+            logging.makeLogRecord(
+                dict(
+                    levelno=logging.WARNING,
+                    levelname='WARNING',
+                    msg=f'{config_filename}: The bsd_flags option has been renamed to flags. bsd_flags is deprecated and support will be removed from a future release.',
+                )
+            )
+        )
+        config['flags'] = bsd_flags
 
-    remote_rate_limit = storage.pop('remote_rate_limit', None)
+    remote_rate_limit = config.pop('remote_rate_limit', None)
     if remote_rate_limit is not None:
-        config['storage']['upload_rate_limit'] = remote_rate_limit
+        logs.append(
+            logging.makeLogRecord(
+                dict(
+                    levelno=logging.WARNING,
+                    levelname='WARNING',
+                    msg=f'{config_filename}: The remote_rate_limit option has been renamed to upload_rate_limit. remote_rate_limit is deprecated and support will be removed from a future release.',
+                )
+            )
+        )
+        config['upload_rate_limit'] = remote_rate_limit
 
     # Upgrade remote repositories to ssh:// syntax, required in Borg 2.
-    repositories = location.get('repositories')
+    repositories = config.get('repositories')
     if repositories:
         if isinstance(repositories[0], str):
-            config['location']['repositories'] = [
-                {'path': repository} for repository in repositories
-            ]
-            repositories = config['location']['repositories']
-        config['location']['repositories'] = []
+            logs.append(
+                logging.makeLogRecord(
+                    dict(
+                        levelno=logging.WARNING,
+                        levelname='WARNING',
+                        msg=f'{config_filename}: The repositories option now expects a list of key/value pairs. Lists of strings for this option are deprecated and support will be removed from a future release.',
+                    )
+                )
+            )
+            config['repositories'] = [{'path': repository} for repository in repositories]
+            repositories = config['repositories']
+
+        config['repositories'] = []
+
         for repository_dict in repositories:
             repository_path = repository_dict['path']
             if '~' in repository_path:
@@ -71,7 +211,7 @@ def normalize(config_filename, config):
                         dict(
                             levelno=logging.WARNING,
                             levelname='WARNING',
-                            msg=f'{config_filename}: Repository paths containing "~" are deprecated in borgmatic and no longer work in Borg 2.x+.',
+                            msg=f'{config_filename}: Repository paths containing "~" are deprecated in borgmatic and support will be removed from a future release.',
                         )
                     )
                 )
@@ -80,14 +220,14 @@ def normalize(config_filename, config):
                     updated_repository_path = os.path.abspath(
                         repository_path.partition('file://')[-1]
                     )
-                    config['location']['repositories'].append(
+                    config['repositories'].append(
                         dict(
                             repository_dict,
                             path=updated_repository_path,
                         )
                     )
                 elif repository_path.startswith('ssh://'):
-                    config['location']['repositories'].append(repository_dict)
+                    config['repositories'].append(repository_dict)
                 else:
                     rewritten_repository_path = f"ssh://{repository_path.replace(':~', '/~').replace(':/', '/').replace(':', '/./')}"
                     logs.append(
@@ -95,17 +235,28 @@ def normalize(config_filename, config):
                             dict(
                                 levelno=logging.WARNING,
                                 levelname='WARNING',
-                                msg=f'{config_filename}: Remote repository paths without ssh:// syntax are deprecated. Interpreting "{repository_path}" as "{rewritten_repository_path}"',
+                                msg=f'{config_filename}: Remote repository paths without ssh:// syntax are deprecated and support will be removed from a future release. Interpreting "{repository_path}" as "{rewritten_repository_path}"',
                             )
                         )
                     )
-                    config['location']['repositories'].append(
+                    config['repositories'].append(
                         dict(
                             repository_dict,
                             path=rewritten_repository_path,
                         )
                     )
             else:
-                config['location']['repositories'].append(repository_dict)
+                config['repositories'].append(repository_dict)
+
+    if config.get('prefix'):
+        logs.append(
+            logging.makeLogRecord(
+                dict(
+                    levelno=logging.WARNING,
+                    levelname='WARNING',
+                    msg=f'{config_filename}: The prefix option is deprecated and support will be removed from a future release. Use archive_name_format or match_archives instead.',
+                )
+            )
+        )
 
     return logs

borgmatic/config/override.py

@@ -32,19 +32,33 @@ def convert_value_type(value):
     return ruamel.yaml.YAML(typ='safe').load(io.StringIO(value))
 
 
+LEGACY_SECTION_NAMES = {'location', 'storage', 'retention', 'consistency', 'output', 'hooks'}
+
+
+def strip_section_names(parsed_override_key):
+    '''
+    Given a parsed override key as a tuple of option and suboption names, strip out any initial
+    legacy section names, since configuration file normalization also strips them out.
+    '''
+    if parsed_override_key[0] in LEGACY_SECTION_NAMES:
+        return parsed_override_key[1:]
+
+    return parsed_override_key
+
+
 def parse_overrides(raw_overrides):
     '''
-    Given a sequence of configuration file override strings in the form of "section.option=value",
+    Given a sequence of configuration file override strings in the form of "option.suboption=value",
     parse and return a sequence of tuples (keys, values), where keys is a sequence of strings. For
     instance, given the following raw overrides:
 
-        ['section.my_option=value1', 'section.other_option=value2']
+        ['my_option.suboption=value1', 'other_option=value2']
 
     ... return this:
 
         (
-            (('section', 'my_option'), 'value1'),
-            (('section', 'other_option'), 'value2'),
+            (('my_option', 'suboption'), 'value1'),
+            (('other_option'), 'value2'),
         )
 
     Raise ValueError if an override can't be parsed.
@@ -59,13 +73,13 @@ def parse_overrides(raw_overrides):
             raw_keys, value = raw_override.split('=', 1)
             parsed_overrides.append(
                 (
-                    tuple(raw_keys.split('.')),
+                    strip_section_names(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"
+                f"Invalid override '{raw_override}'. Make sure you use the form: OPTION=VALUE or OPTION.SUBOPTION=VALUE"
             )
         except ruamel.yaml.error.YAMLError as error:
             raise ValueError(f"Invalid override '{raw_override}': {error.problem}")
@@ -76,7 +90,7 @@ def parse_overrides(raw_overrides):
 def apply_overrides(config, raw_overrides):
     '''
     Given a configuration dict and a sequence of configuration file override strings in the form of
-    "section.option=value", parse each override and set it the configuration dict.
+    "option.suboption=value", parse each override and set it the configuration dict.
     '''
     overrides = parse_overrides(raw_overrides)
 

borgmatic/config/validate.py

@@ -3,11 +3,6 @@ import os
 import jsonschema
 import ruamel.yaml
 
-try:
-    import importlib_metadata
-except ModuleNotFoundError:  # pragma: nocover
-    import importlib.metadata as importlib_metadata
-
 import borgmatic.config
 from borgmatic.config import environment, load, normalize, override
 
@@ -19,16 +14,10 @@ def schema_filename():
 
     Raise FileNotFoundError when the schema path does not exist.
     '''
-    try:
-        return next(
-            str(path.locate())
-            for path in importlib_metadata.files('borgmatic')
-            if path.match('config/schema.yaml')
-        )
-    except StopIteration:
-        # If the schema wasn't found in the package's files, this is probably a pip editable
-        # install, so try a different approach to get the schema.
-        return os.path.join(os.path.dirname(borgmatic.config.__file__), 'schema.yaml')
+    schema_path = os.path.join(os.path.dirname(borgmatic.config.__file__), 'schema.yaml')
+
+    with open(schema_path):
+        return schema_path
 
 
 def format_json_error_path_element(path_element):
@@ -82,18 +71,15 @@ 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.
     '''
-    location_repositories = parsed_configuration.get('location', {}).get('repositories')
-    check_repositories = parsed_configuration.get('consistency', {}).get('check_repositories', [])
+    repositories = parsed_configuration.get('repositories')
+    check_repositories = parsed_configuration.get('check_repositories', [])
     for repository in check_repositories:
         if not any(
-            repositories_match(repository, config_repository)
-            for config_repository in location_repositories
+            repositories_match(repository, config_repository) for config_repository in repositories
         ):
             raise Validation_error(
                 config_filename,
-                (
-                    f'Unknown repository in the "consistency" section\'s "check_repositories": {repository}',
-                ),
+                (f'Unknown repository in "check_repositories": {repository}',),
             )
 
 
@@ -101,11 +87,15 @@ def parse_configuration(config_filename, schema_filename, overrides=None, resolv
     '''
     Given the path to a config filename in YAML format, the path to a schema filename in a YAML
     rendition of JSON Schema format, a sequence of configuration file override strings in the form
-    of "section.option=value", return the parsed configuration as a data structure of nested dicts
+    of "option.suboption=value", return the parsed configuration as a data structure of nested dicts
     and lists corresponding to the schema. Example return value:
 
-       {'location': {'source_directories': ['/home', '/etc'], 'repository': 'hostname.borg'},
-       'retention': {'keep_daily': 7}, 'consistency': {'checks': ['repository', 'archives']}}
+        {
+            'source_directories': ['/home', '/etc'],
+            'repository': 'hostname.borg',
+            'keep_daily': 7,
+            'checks': ['repository', 'archives'],
+        }
 
     Also return a sequence of logging.LogRecord instances containing any warnings about the
     configuration.
@@ -185,7 +175,7 @@ def guard_configuration_contains_repository(repository, configurations):
         tuple(
             config_repository
             for config in configurations.values()
-            for config_repository in config['location']['repositories']
+            for config_repository in config['repositories']
             if repositories_match(config_repository, repository)
         )
     )
@@ -209,7 +199,7 @@ def guard_single_repository_selected(repository, configurations):
         tuple(
             config_repository
             for config in configurations.values()
-            for config_repository in config['location']['repositories']
+            for config_repository in config['repositories']
         )
     )
 

borgmatic/execute.py

@@ -241,13 +241,16 @@ def execute_command_and_capture_output(
     shell=False,
     extra_environment=None,
     working_directory=None,
+    borg_local_path=None,
 ):
     '''
     Execute the given command (a sequence of command/argument strings), capturing and returning its
     output (stdout). If capture stderr is True, then capture and return stderr in addition to
     stdout. If shell is True, execute the command within a shell. If an extra environment dict is
     given, then use it to augment the current environment, and pass the result into the command. If
-    a working directory is given, use that as the present working directory when running the command.
+    a working directory is given, use that as the present working directory when running the
+    command. If a Borg local path is given, and the command matches it (regardless of arguments),
+    treat exit code 1 as a warning instead of an error.
 
     Raise subprocesses.CalledProcessError if an error occurs while running the command.
     '''
@@ -264,7 +267,7 @@ def execute_command_and_capture_output(
             cwd=working_directory,
         )
     except subprocess.CalledProcessError as error:
-        if exit_code_indicates_error(command, error.returncode):
+        if exit_code_indicates_error(command, error.returncode, borg_local_path):
             raise
         output = error.output
 

borgmatic/hooks/cronhub.py

@@ -14,7 +14,7 @@ MONITOR_STATE_TO_CRONHUB = {
 
 
 def initialize_monitor(
-    ping_url, config_filename, monitoring_log_level, dry_run
+    ping_url, config, config_filename, monitoring_log_level, dry_run
 ):  # pragma: no cover
     '''
     No initialization is necessary for this monitor.
@@ -22,7 +22,7 @@ def initialize_monitor(
     pass
 
 
-def ping_monitor(hook_config, config_filename, state, monitoring_log_level, dry_run):
+def ping_monitor(hook_config, config, config_filename, state, monitoring_log_level, dry_run):
     '''
     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.
@@ -55,7 +55,7 @@ def ping_monitor(hook_config, config_filename, state, monitoring_log_level, dry_
 
 
 def destroy_monitor(
-    ping_url_or_uuid, config_filename, monitoring_log_level, dry_run
+    ping_url_or_uuid, config, config_filename, monitoring_log_level, dry_run
 ):  # pragma: no cover
     '''
     No destruction is necessary for this monitor.

borgmatic/hooks/cronitor.py

@@ -14,7 +14,7 @@ MONITOR_STATE_TO_CRONITOR = {
 
 
 def initialize_monitor(
-    ping_url, config_filename, monitoring_log_level, dry_run
+    ping_url, config, config_filename, monitoring_log_level, dry_run
 ):  # pragma: no cover
     '''
     No initialization is necessary for this monitor.
@@ -22,7 +22,7 @@ def initialize_monitor(
     pass
 
 
-def ping_monitor(hook_config, config_filename, state, monitoring_log_level, dry_run):
+def ping_monitor(hook_config, config, config_filename, state, monitoring_log_level, dry_run):
     '''
     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.
@@ -50,7 +50,7 @@ def ping_monitor(hook_config, config_filename, state, monitoring_log_level, dry_
 
 
 def destroy_monitor(
-    ping_url_or_uuid, config_filename, monitoring_log_level, dry_run
+    ping_url_or_uuid, config, config_filename, monitoring_log_level, dry_run
 ):  # pragma: no cover
     '''
     No destruction is necessary for this monitor.

borgmatic/hooks/dispatch.py

@@ -27,18 +27,17 @@ HOOK_NAME_TO_MODULE = {
 }
 
 
-def call_hook(function_name, hooks, log_prefix, hook_name, *args, **kwargs):
+def call_hook(function_name, config, log_prefix, hook_name, *args, **kwargs):
     '''
-    Given the hooks configuration dict and a prefix to use in log entries, call the requested
-    function of the Python module corresponding to the given hook name. Supply that call with the
-    configuration for this hook (if any), the log prefix, and any given args and kwargs. Return any
-    return value.
+    Given a configuration dict and a prefix to use in log entries, call the requested function of
+    the Python module corresponding to the given hook name. Supply that call with the configuration
+    for this hook (if any), the log prefix, and any given args and kwargs. Return any return value.
 
     Raise ValueError if the hook name is unknown.
     Raise AttributeError if the function name is not found in the module.
     Raise anything else that the called function raises.
     '''
-    config = hooks.get(hook_name, {})
+    hook_config = config.get(hook_name, {})
 
     try:
         module = HOOK_NAME_TO_MODULE[hook_name]
@@ -46,15 +45,15 @@ def call_hook(function_name, hooks, log_prefix, hook_name, *args, **kwargs):
         raise ValueError(f'Unknown hook name: {hook_name}')
 
     logger.debug(f'{log_prefix}: Calling {hook_name} hook function {function_name}')
-    return getattr(module, function_name)(config, log_prefix, *args, **kwargs)
+    return getattr(module, function_name)(hook_config, config, log_prefix, *args, **kwargs)
 
 
-def call_hooks(function_name, hooks, log_prefix, hook_names, *args, **kwargs):
+def call_hooks(function_name, config, log_prefix, hook_names, *args, **kwargs):
     '''
-    Given the hooks configuration dict and a prefix to use in log entries, call the requested
-    function of the Python module corresponding to each given hook name. Supply each call with the
-    configuration for that hook, the log prefix, and any given args and kwargs. Collect any return
-    values into a dict from hook name to return value.
+    Given a configuration dict and a prefix to use in log entries, call the requested function of
+    the Python module corresponding to each given hook name. Supply each call with the configuration
+    for that hook, the log prefix, and any given args and kwargs. Collect any return values into a
+    dict from hook name to return value.
 
     If the hook name is not present in the hooks configuration, then don't call the function for it
     and omit it from the return values.
@@ -64,23 +63,23 @@ def call_hooks(function_name, hooks, log_prefix, hook_names, *args, **kwargs):
     Raise anything else that a called function raises. An error stops calls to subsequent functions.
     '''
     return {
-        hook_name: call_hook(function_name, hooks, log_prefix, hook_name, *args, **kwargs)
+        hook_name: call_hook(function_name, config, log_prefix, hook_name, *args, **kwargs)
         for hook_name in hook_names
-        if hooks.get(hook_name)
+        if config.get(hook_name)
     }
 
 
-def call_hooks_even_if_unconfigured(function_name, hooks, log_prefix, hook_names, *args, **kwargs):
+def call_hooks_even_if_unconfigured(function_name, config, log_prefix, hook_names, *args, **kwargs):
     '''
-    Given the hooks configuration dict and a prefix to use in log entries, call the requested
-    function of the Python module corresponding to each given hook name. Supply each call with the
-    configuration for that hook, the log prefix, and any given args and kwargs. Collect any return
-    values into a dict from hook name to return value.
+    Given a configuration dict and a prefix to use in log entries, call the requested function of
+    the Python module corresponding to each given hook name. Supply each call with the configuration
+    for that hook, the log prefix, and any given args and kwargs. Collect any return values into a
+    dict from hook name to return value.
 
     Raise AttributeError if the function name is not found in the module.
     Raise anything else that a called function raises. An error stops calls to subsequent functions.
     '''
     return {
-        hook_name: call_hook(function_name, hooks, log_prefix, hook_name, *args, **kwargs)
+        hook_name: call_hook(function_name, config, log_prefix, hook_name, *args, **kwargs)
         for hook_name in hook_names
     }

borgmatic/hooks/healthchecks.py

@@ -70,7 +70,7 @@ def format_buffered_logs_for_payload():
     return payload
 
 
-def initialize_monitor(hook_config, config_filename, monitoring_log_level, dry_run):
+def initialize_monitor(hook_config, 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. But skip this if the
@@ -90,7 +90,7 @@ def initialize_monitor(hook_config, config_filename, monitoring_log_level, dry_r
     )
 
 
-def ping_monitor(hook_config, config_filename, state, monitoring_log_level, dry_run):
+def ping_monitor(hook_config, config, config_filename, state, monitoring_log_level, dry_run):
     '''
     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.
@@ -133,7 +133,7 @@ def ping_monitor(hook_config, config_filename, state, monitoring_log_level, dry_
             logger.warning(f'{config_filename}: Healthchecks error: {error}')
 
 
-def destroy_monitor(hook_config, config_filename, monitoring_log_level, dry_run):
+def destroy_monitor(hook_config, 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/mongodb.py

@@ -6,21 +6,20 @@ from borgmatic.hooks import dump
 logger = logging.getLogger(__name__)
 
 
-def make_dump_path(location_config):  # pragma: no cover
+def make_dump_path(config):  # pragma: no cover
     '''
-    Make the dump path from the given location configuration and the name of this hook.
+    Make the dump path from the given configuration dict and the name of this hook.
     '''
     return dump.make_database_dump_path(
-        location_config.get('borgmatic_source_directory'), 'mongodb_databases'
+        config.get('borgmatic_source_directory'), 'mongodb_databases'
     )
 
 
-def dump_databases(databases, log_prefix, location_config, dry_run):
+def dump_databases(databases, config, log_prefix, dry_run):
     '''
     Dump the given MongoDB databases to a named pipe. The databases are supplied as a sequence of
-    dicts, one dict describing each database as per the configuration schema. Use the given log
-    prefix in any log entries. Use the given location configuration dict to construct the
-    destination path.
+    dicts, one dict describing each database as per the configuration schema. Use the configuration
+    dict to construct the destination path and the given log prefix in any log entries.
 
     Return a sequence of subprocess.Popen instances for the dump processes ready to spew to a named
     pipe. But if this is a dry run, then don't actually dump anything and return an empty sequence.
@@ -33,7 +32,7 @@ def dump_databases(databases, log_prefix, location_config, dry_run):
     for database in databases:
         name = database['name']
         dump_filename = dump.make_database_dump_filename(
-            make_dump_path(location_config), name, database.get('hostname')
+            make_dump_path(config), name, database.get('hostname')
         )
         dump_format = database.get('format', 'archive')
 
@@ -82,47 +81,57 @@ def build_dump_command(database, dump_filename, dump_format):
     return command
 
 
-def remove_database_dumps(databases, log_prefix, location_config, dry_run):  # pragma: no cover
+def remove_database_dumps(databases, config, log_prefix, dry_run):  # pragma: no cover
     '''
     Remove all database dump files for this hook regardless of the given databases. Use the log
-    prefix in any log entries. Use the given location configuration dict to construct the
-    destination path. If this is a dry run, then don't actually remove anything.
+    prefix in any log entries. Use the given configuration dict to construct the destination path.
+    If this is a dry run, then don't actually remove anything.
     '''
-    dump.remove_database_dumps(make_dump_path(location_config), 'MongoDB', log_prefix, dry_run)
+    dump.remove_database_dumps(make_dump_path(config), 'MongoDB', log_prefix, dry_run)
 
 
-def make_database_dump_pattern(
-    databases, log_prefix, location_config, name=None
-):  # pragma: no cover
+def make_database_dump_pattern(databases, config, log_prefix, name=None):  # pragma: no cover
     '''
-    Given a sequence of configurations dicts, a prefix to log with, a location configuration dict,
+    Given a sequence of database configurations dicts, a configuration dict, a prefix to log with,
     and a database name to match, return the corresponding glob patterns to match the database dump
     in an archive.
     '''
-    return dump.make_database_dump_filename(make_dump_path(location_config), name, hostname='*')
+    return dump.make_database_dump_filename(make_dump_path(config), name, hostname='*')
 
 
-def restore_database_dump(database_config, log_prefix, location_config, dry_run, extract_process):
+def restore_database_dump(
+    databases_config, config, log_prefix, database_name, dry_run, extract_process, connection_params
+):
     '''
-    Restore the given MongoDB database from an extract stream. The database is supplied as a
-    one-element sequence containing a dict describing the database, as per the configuration schema.
-    Use the given log prefix in any log entries. If this is a dry run, then don't actually restore
-    anything. Trigger the given active extract process (an instance of subprocess.Popen) to produce
-    output to consume.
+    Restore the given MongoDB database from an extract stream. The databases are supplied as a
+    sequence containing one dict describing each database (as per the configuration schema), but
+    only the database corresponding to the given database name is restored. Use the configuration
+    dict to construct the destination path and the given log prefix in any log entries. If this is a
+    dry run, then don't actually restore anything. Trigger the given active extract process (an
+    instance of subprocess.Popen) to produce output to consume.
 
     If the extract process is None, then restore the dump from the filesystem rather than from an
     extract stream.
     '''
     dry_run_label = ' (dry run; not actually restoring anything)' if dry_run else ''
 
-    if len(database_config) != 1:
-        raise ValueError('The database configuration value is invalid')
+    try:
+        database = next(
+            database_config
+            for database_config in databases_config
+            if database_config.get('name') == database_name
+        )
+    except StopIteration:
+        raise ValueError(
+            f'A database named "{database_name}" could not be found in the configuration'
+        )
 
-    database = database_config[0]
     dump_filename = dump.make_database_dump_filename(
-        make_dump_path(location_config), database['name'], database.get('hostname')
+        make_dump_path(config), database['name'], database.get('hostname')
+    )
+    restore_command = build_restore_command(
+        extract_process, database, dump_filename, connection_params
     )
-    restore_command = build_restore_command(extract_process, database, dump_filename)
 
     logger.debug(f"{log_prefix}: Restoring MongoDB database {database['name']}{dry_run_label}")
     if dry_run:
@@ -138,10 +147,21 @@ def restore_database_dump(database_config, log_prefix, location_config, dry_run,
     )
 
 
-def build_restore_command(extract_process, database, dump_filename):
+def build_restore_command(extract_process, database, dump_filename, connection_params):
     '''
     Return the mongorestore command from a single database configuration.
     '''
+    hostname = connection_params['hostname'] or database.get(
+        'restore_hostname', database.get('hostname')
+    )
+    port = str(connection_params['port'] or database.get('restore_port', database.get('port', '')))
+    username = connection_params['username'] or database.get(
+        'restore_username', database.get('username')
+    )
+    password = connection_params['password'] or database.get(
+        'restore_password', database.get('password')
+    )
+
     command = ['mongorestore']
     if extract_process:
         command.append('--archive')
@@ -149,14 +169,14 @@ def build_restore_command(extract_process, database, dump_filename):
         command.extend(('--dir', dump_filename))
     if database['name'] != 'all':
         command.extend(('--drop', '--db', database['name']))
-    if 'hostname' in database:
-        command.extend(('--host', database['hostname']))
-    if 'port' in database:
-        command.extend(('--port', str(database['port'])))
-    if 'username' in database:
-        command.extend(('--username', database['username']))
-    if 'password' in database:
-        command.extend(('--password', database['password']))
+    if hostname:
+        command.extend(('--host', hostname))
+    if port:
+        command.extend(('--port', str(port)))
+    if username:
+        command.extend(('--username', username))
+    if password:
+        command.extend(('--password', password))
     if 'authentication_database' in database:
         command.extend(('--authenticationDatabase', database['authentication_database']))
     if 'restore_options' in database:

borgmatic/hooks/mysql.py

@@ -12,13 +12,11 @@ from borgmatic.hooks import dump
 logger = logging.getLogger(__name__)
 
 
-def make_dump_path(location_config):  # pragma: no cover
+def make_dump_path(config):  # pragma: no cover
     '''
-    Make the dump path from the given location configuration and the name of this hook.
+    Make the dump path from the given configuration dict and the name of this hook.
     '''
-    return dump.make_database_dump_path(
-        location_config.get('borgmatic_source_directory'), 'mysql_databases'
-    )
+    return dump.make_database_dump_path(config.get('borgmatic_source_directory'), 'mysql_databases')
 
 
 SYSTEM_DATABASE_NAMES = ('information_schema', 'mysql', 'performance_schema', 'sys')
@@ -106,12 +104,11 @@ def execute_dump_command(
     )
 
 
-def dump_databases(databases, log_prefix, location_config, dry_run):
+def dump_databases(databases, config, log_prefix, dry_run):
     '''
     Dump the given MySQL/MariaDB databases to a named pipe. The databases are supplied as a sequence
-    of dicts, one dict describing each database as per the configuration schema. Use the given log
-    prefix in any log entries. Use the given location configuration dict to construct the
-    destination path.
+    of dicts, one dict describing each database as per the configuration schema. Use the given
+    configuration dict to construct the destination path and the given log prefix in any log entries.
 
     Return a sequence of subprocess.Popen instances for the dump processes ready to spew to a named
     pipe. But if this is a dry run, then don't actually dump anything and return an empty sequence.
@@ -122,7 +119,7 @@ def dump_databases(databases, log_prefix, location_config, dry_run):
     logger.info(f'{log_prefix}: Dumping MySQL databases{dry_run_label}')
 
     for database in databases:
-        dump_path = make_dump_path(location_config)
+        dump_path = make_dump_path(config)
         extra_environment = {'MYSQL_PWD': database['password']} if 'password' in database else None
         dump_database_names = database_names_to_dump(
             database, extra_environment, log_prefix, dry_run
@@ -165,49 +162,67 @@ def dump_databases(databases, log_prefix, location_config, dry_run):
     return [process for process in processes if process]
 
 
-def remove_database_dumps(databases, log_prefix, location_config, dry_run):  # pragma: no cover
+def remove_database_dumps(databases, config, log_prefix, dry_run):  # pragma: no cover
     '''
-    Remove all database dump files for this hook regardless of the given databases. Use the log
-    prefix in any log entries. Use the given location configuration dict to construct the
-    destination path. If this is a dry run, then don't actually remove anything.
+    Remove all database dump files for this hook regardless of the given databases. Use the given
+    configuration dict to construct the destination path and the log prefix in any log entries. If
+    this is a dry run, then don't actually remove anything.
     '''
-    dump.remove_database_dumps(make_dump_path(location_config), 'MySQL', log_prefix, dry_run)
+    dump.remove_database_dumps(make_dump_path(config), 'MySQL', log_prefix, dry_run)
 
 
-def make_database_dump_pattern(
-    databases, log_prefix, location_config, name=None
-):  # pragma: no cover
+def make_database_dump_pattern(databases, config, log_prefix, name=None):  # pragma: no cover
     '''
-    Given a sequence of configurations dicts, a prefix to log with, a location configuration dict,
-    and a database name to match, return the corresponding glob patterns to match the database dump
-    in an archive.
+    Given a sequence of configurations dicts, a configuration dict, a prefix to log with, and a
+    database name to match, return the corresponding glob patterns to match the database dump in an
+    archive.
     '''
-    return dump.make_database_dump_filename(make_dump_path(location_config), name, hostname='*')
+    return dump.make_database_dump_filename(make_dump_path(config), name, hostname='*')
 
 
-def restore_database_dump(database_config, log_prefix, location_config, dry_run, extract_process):
+def restore_database_dump(
+    databases_config, config, log_prefix, database_name, dry_run, extract_process, connection_params
+):
     '''
-    Restore the given MySQL/MariaDB database from an extract stream. The database is supplied as a
-    one-element sequence containing a dict describing the database, as per the configuration schema.
-    Use the given log prefix in any log entries. If this is a dry run, then don't actually restore
-    anything. Trigger the given active extract process (an instance of subprocess.Popen) to produce
-    output to consume.
+    Restore the given MySQL/MariaDB database from an extract stream. The databases are supplied as a
+    sequence containing one dict describing each database (as per the configuration schema), but
+    only the database corresponding to the given database name is restored. Use the given log
+    prefix in any log entries. If this is a dry run, then don't actually restore anything. Trigger
+    the given active extract process (an instance of subprocess.Popen) to produce output to consume.
     '''
     dry_run_label = ' (dry run; not actually restoring anything)' if dry_run else ''
 
-    if len(database_config) != 1:
-        raise ValueError('The database configuration value is invalid')
+    try:
+        database = next(
+            database_config
+            for database_config in databases_config
+            if database_config.get('name') == database_name
+        )
+    except StopIteration:
+        raise ValueError(
+            f'A database named "{database_name}" could not be found in the configuration'
+        )
+
+    hostname = connection_params['hostname'] or database.get(
+        'restore_hostname', database.get('hostname')
+    )
+    port = str(connection_params['port'] or database.get('restore_port', database.get('port', '')))
+    username = connection_params['username'] or database.get(
+        'restore_username', database.get('username')
+    )
+    password = connection_params['password'] or database.get(
+        'restore_password', database.get('password')
+    )
 
-    database = database_config[0]
     restore_command = (
         ('mysql', '--batch')
         + (tuple(database['restore_options'].split(' ')) if 'restore_options' in database else ())
-        + (('--host', database['hostname']) if 'hostname' in database else ())
-        + (('--port', str(database['port'])) if 'port' in database else ())
-        + (('--protocol', 'tcp') if 'hostname' in database or 'port' in database else ())
-        + (('--user', database['username']) if 'username' in database else ())
+        + (('--host', hostname) if hostname else ())
+        + (('--port', str(port)) if port else ())
+        + (('--protocol', 'tcp') if hostname or port else ())
+        + (('--user', username) if username else ())
     )
-    extra_environment = {'MYSQL_PWD': database['password']} if 'password' in database else None
+    extra_environment = {'MYSQL_PWD': password} if password else None
 
     logger.debug(f"{log_prefix}: Restoring MySQL database {database['name']}{dry_run_label}")
     if dry_run:

borgmatic/hooks/ntfy.py

@@ -6,7 +6,7 @@ logger = logging.getLogger(__name__)
 
 
 def initialize_monitor(
-    ping_url, config_filename, monitoring_log_level, dry_run
+    ping_url, config, config_filename, monitoring_log_level, dry_run
 ):  # pragma: no cover
     '''
     No initialization is necessary for this monitor.
@@ -14,7 +14,7 @@ def initialize_monitor(
     pass
 
 
-def ping_monitor(hook_config, config_filename, state, monitoring_log_level, dry_run):
+def ping_monitor(hook_config, config, config_filename, state, monitoring_log_level, dry_run):
     '''
     Ping the configured Ntfy topic. Use the given configuration filename in any log entries.
     If this is a dry run, then don't actually ping anything.
@@ -75,7 +75,7 @@ def ping_monitor(hook_config, config_filename, state, monitoring_log_level, dry_
 
 
 def destroy_monitor(
-    ping_url_or_uuid, config_filename, monitoring_log_level, dry_run
+    ping_url_or_uuid, config, config_filename, monitoring_log_level, dry_run
 ):  # pragma: no cover
     '''
     No destruction is necessary for this monitor.

borgmatic/hooks/pagerduty.py

@@ -13,7 +13,7 @@ EVENTS_API_URL = 'https://events.pagerduty.com/v2/enqueue'
 
 
 def initialize_monitor(
-    integration_key, config_filename, monitoring_log_level, dry_run
+    integration_key, config, config_filename, monitoring_log_level, dry_run
 ):  # pragma: no cover
     '''
     No initialization is necessary for this monitor.
@@ -21,7 +21,7 @@ def initialize_monitor(
     pass
 
 
-def ping_monitor(hook_config, config_filename, state, monitoring_log_level, dry_run):
+def ping_monitor(hook_config, config, config_filename, state, monitoring_log_level, dry_run):
     '''
     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
@@ -75,7 +75,7 @@ def ping_monitor(hook_config, config_filename, state, monitoring_log_level, dry_
 
 
 def destroy_monitor(
-    ping_url_or_uuid, config_filename, monitoring_log_level, dry_run
+    ping_url_or_uuid, config, config_filename, monitoring_log_level, dry_run
 ):  # pragma: no cover
     '''
     No destruction is necessary for this monitor.

borgmatic/hooks/postgresql.py

@@ -14,22 +14,32 @@ from borgmatic.hooks import dump
 logger = logging.getLogger(__name__)
 
 
-def make_dump_path(location_config):  # pragma: no cover
+def make_dump_path(config):  # pragma: no cover
     '''
-    Make the dump path from the given location configuration and the name of this hook.
+    Make the dump path from the given configuration dict and the name of this hook.
     '''
     return dump.make_database_dump_path(
-        location_config.get('borgmatic_source_directory'), 'postgresql_databases'
+        config.get('borgmatic_source_directory'), 'postgresql_databases'
     )
 
 
-def make_extra_environment(database):
+def make_extra_environment(database, restore_connection_params=None):
     '''
     Make the extra_environment dict from the given database configuration.
+    If restore connection params are given, this is for a restore operation.
     '''
     extra = dict()
-    if 'password' in database:
-        extra['PGPASSWORD'] = database['password']
+
+    try:
+        if restore_connection_params:
+            extra['PGPASSWORD'] = restore_connection_params.get('password') or database.get(
+                'restore_password', database['password']
+            )
+        else:
+            extra['PGPASSWORD'] = database['password']
+    except (AttributeError, KeyError):
+        pass
+
     extra['PGSSLMODE'] = database.get('ssl_mode', 'disable')
     if 'ssl_cert' in database:
         extra['PGSSLCERT'] = database['ssl_cert']
@@ -82,12 +92,12 @@ def database_names_to_dump(database, extra_environment, log_prefix, dry_run):
     )
 
 
-def dump_databases(databases, log_prefix, location_config, dry_run):
+def dump_databases(databases, config, log_prefix, dry_run):
     '''
     Dump the given PostgreSQL databases to a named pipe. The databases are supplied as a sequence of
-    dicts, one dict describing each database as per the configuration schema. Use the given log
-    prefix in any log entries. Use the given location configuration dict to construct the
-    destination path.
+    dicts, one dict describing each database as per the configuration schema. Use the given
+    configuration dict to construct the destination path and the given log prefix in any log
+    entries.
 
     Return a sequence of subprocess.Popen instances for the dump processes ready to spew to a named
     pipe. But if this is a dry run, then don't actually dump anything and return an empty sequence.
@@ -101,7 +111,7 @@ def dump_databases(databases, log_prefix, location_config, dry_run):
 
     for database in databases:
         extra_environment = make_extra_environment(database)
-        dump_path = make_dump_path(location_config)
+        dump_path = make_dump_path(config)
         dump_database_names = database_names_to_dump(
             database, extra_environment, log_prefix, dry_run
         )
@@ -135,6 +145,7 @@ def dump_databases(databases, log_prefix, location_config, dry_run):
                 + (('--host', database['hostname']) if 'hostname' in database else ())
                 + (('--port', str(database['port'])) if 'port' in database else ())
                 + (('--username', database['username']) if 'username' in database else ())
+                + (('--no-owner',) if database.get('no_owner', False) else ())
                 + (('--format', dump_format) if dump_format else ())
                 + (('--file', dump_filename) if dump_format == 'directory' else ())
                 + (tuple(database['options'].split(' ')) if 'options' in database else ())
@@ -172,54 +183,73 @@ def dump_databases(databases, log_prefix, location_config, dry_run):
     return processes
 
 
-def remove_database_dumps(databases, log_prefix, location_config, dry_run):  # pragma: no cover
+def remove_database_dumps(databases, config, log_prefix, dry_run):  # pragma: no cover
     '''
-    Remove all database dump files for this hook regardless of the given databases. Use the log
-    prefix in any log entries. Use the given location configuration dict to construct the
-    destination path. If this is a dry run, then don't actually remove anything.
+    Remove all database dump files for this hook regardless of the given databases. Use the given
+    configuration dict to construct the destination path and the log prefix in any log entries. If
+    this is a dry run, then don't actually remove anything.
     '''
-    dump.remove_database_dumps(make_dump_path(location_config), 'PostgreSQL', log_prefix, dry_run)
+    dump.remove_database_dumps(make_dump_path(config), 'PostgreSQL', log_prefix, dry_run)
 
 
-def make_database_dump_pattern(
-    databases, log_prefix, location_config, name=None
-):  # pragma: no cover
+def make_database_dump_pattern(databases, config, log_prefix, name=None):  # pragma: no cover
     '''
-    Given a sequence of configurations dicts, a prefix to log with, a location configuration dict,
-    and a database name to match, return the corresponding glob patterns to match the database dump
-    in an archive.
+    Given a sequence of configurations dicts, a configuration dict, a prefix to log with, and a
+    database name to match, return the corresponding glob patterns to match the database dump in an
+    archive.
     '''
-    return dump.make_database_dump_filename(make_dump_path(location_config), name, hostname='*')
+    return dump.make_database_dump_filename(make_dump_path(config), name, hostname='*')
 
 
-def restore_database_dump(database_config, log_prefix, location_config, dry_run, extract_process):
+def restore_database_dump(
+    databases_config, config, log_prefix, database_name, dry_run, extract_process, connection_params
+):
     '''
-    Restore the given PostgreSQL database from an extract stream. The database is supplied as a
-    one-element sequence containing a dict describing the database, as per the configuration schema.
-    Use the given log prefix in any log entries. If this is a dry run, then don't actually restore
-    anything. Trigger the given active extract process (an instance of subprocess.Popen) to produce
-    output to consume.
+    Restore the given PostgreSQL database from an extract stream. The databases are supplied as a
+    sequence containing one dict describing each database (as per the configuration schema), but
+    only the database corresponding to the given database name is restored. Use the given
+    configuration dict to construct the destination path and the given log prefix in any log
+    entries. If this is a dry run, then don't actually restore anything. Trigger the given active
+    extract process (an instance of subprocess.Popen) to produce output to consume.
 
     If the extract process is None, then restore the dump from the filesystem rather than from an
     extract stream.
+
+    Use the given connection parameters to connect to the database. The connection parameters are
+    hostname, port, username, and password.
     '''
     dry_run_label = ' (dry run; not actually restoring anything)' if dry_run else ''
 
-    if len(database_config) != 1:
-        raise ValueError('The database configuration value is invalid')
+    try:
+        database = next(
+            database_config
+            for database_config in databases_config
+            if database_config.get('name') == database_name
+        )
+    except StopIteration:
+        raise ValueError(
+            f'A database named "{database_name}" could not be found in the configuration'
+        )
+
+    hostname = connection_params['hostname'] or database.get(
+        'restore_hostname', database.get('hostname')
+    )
+    port = str(connection_params['port'] or database.get('restore_port', database.get('port', '')))
+    username = connection_params['username'] or database.get(
+        'restore_username', database.get('username')
+    )
 
-    database = database_config[0]
     all_databases = bool(database['name'] == 'all')
     dump_filename = dump.make_database_dump_filename(
-        make_dump_path(location_config), database['name'], database.get('hostname')
+        make_dump_path(config), database['name'], database.get('hostname')
     )
     psql_command = shlex.split(database.get('psql_command') or 'psql')
     analyze_command = (
         tuple(psql_command)
         + ('--no-password', '--no-psqlrc', '--quiet')
-        + (('--host', database['hostname']) if 'hostname' in database else ())
-        + (('--port', str(database['port'])) if 'port' in database else ())
-        + (('--username', database['username']) if 'username' in database else ())
+        + (('--host', hostname) if hostname else ())
+        + (('--port', port) if port else ())
+        + (('--username', username) if username else ())
         + (('--dbname', database['name']) if not all_databases else ())
         + (tuple(database['analyze_options'].split(' ')) if 'analyze_options' in database else ())
         + ('--command', 'ANALYZE')
@@ -231,19 +261,22 @@ def restore_database_dump(database_config, log_prefix, location_config, dry_run,
         + ('--no-password',)
         + (('--no-psqlrc',) if use_psql_command else ('--if-exists', '--exit-on-error', '--clean'))
         + (('--dbname', database['name']) if not all_databases else ())
-        + (('--host', database['hostname']) if 'hostname' in database else ())
-        + (('--port', str(database['port'])) if 'port' in database else ())
-        + (('--username', database['username']) if 'username' in database else ())
+        + (('--host', hostname) if hostname else ())
+        + (('--port', port) if port else ())
+        + (('--username', username) if username else ())
+        + (('--no-owner',) if database.get('no_owner', False) else ())
         + (tuple(database['restore_options'].split(' ')) if 'restore_options' in database else ())
         + (() if extract_process else (dump_filename,))
         + tuple(
             itertools.chain.from_iterable(('--schema', schema) for schema in database['schemas'])
-            if database['schemas']
+            if database.get('schemas')
             else ()
         )
     )
 
-    extra_environment = make_extra_environment(database)
+    extra_environment = make_extra_environment(
+        database, restore_connection_params=connection_params
+    )
 
     logger.debug(f"{log_prefix}: Restoring PostgreSQL database {database['name']}{dry_run_label}")
     if dry_run:

borgmatic/hooks/sqlite.py

@@ -7,21 +7,21 @@ from borgmatic.hooks import dump
 logger = logging.getLogger(__name__)
 
 
-def make_dump_path(location_config):  # pragma: no cover
+def make_dump_path(config):  # pragma: no cover
     '''
-    Make the dump path from the given location configuration and the name of this hook.
+    Make the dump path from the given configuration dict and the name of this hook.
     '''
     return dump.make_database_dump_path(
-        location_config.get('borgmatic_source_directory'), 'sqlite_databases'
+        config.get('borgmatic_source_directory'), 'sqlite_databases'
     )
 
 
-def dump_databases(databases, log_prefix, location_config, dry_run):
+def dump_databases(databases, config, log_prefix, dry_run):
     '''
     Dump the given SQLite3 databases to a file. The databases are supplied as a sequence of
-    configuration dicts, as per the configuration schema. Use the given log prefix in any log
-    entries. Use the given location configuration dict to construct the destination path. If this
-    is a dry run, then don't actually dump anything.
+    configuration dicts, as per the configuration schema. Use the given configuration dict to
+    construct the destination path and the given log prefix in any log entries. If this is a dry
+    run, then don't actually dump anything.
     '''
     dry_run_label = ' (dry run; not actually dumping anything)' if dry_run else ''
     processes = []
@@ -38,7 +38,7 @@ def dump_databases(databases, log_prefix, location_config, dry_run):
                 f'{log_prefix}: No SQLite database at {database_path}; An empty database will be created and dumped'
             )
 
-        dump_path = make_dump_path(location_config)
+        dump_path = make_dump_path(config)
         dump_filename = dump.make_database_dump_filename(dump_path, database['name'])
         if os.path.exists(dump_filename):
             logger.warning(
@@ -65,40 +65,50 @@ def dump_databases(databases, log_prefix, location_config, dry_run):
     return processes
 
 
-def remove_database_dumps(databases, log_prefix, location_config, dry_run):  # pragma: no cover
+def remove_database_dumps(databases, config, log_prefix, dry_run):  # pragma: no cover
     '''
     Remove the given SQLite3 database dumps from the filesystem. The databases are supplied as a
-    sequence of configuration dicts, as per the configuration schema. Use the given log prefix in
-    any log entries. Use the given location configuration dict to construct the destination path.
-    If this is a dry run, then don't actually remove anything.
+    sequence of configuration dicts, as per the configuration schema. Use the given configuration
+    dict to construct the destination path and the given log prefix in any log entries. If this is a
+    dry run, then don't actually remove anything.
     '''
-    dump.remove_database_dumps(make_dump_path(location_config), 'SQLite', log_prefix, dry_run)
+    dump.remove_database_dumps(make_dump_path(config), 'SQLite', log_prefix, dry_run)
 
 
-def make_database_dump_pattern(
-    databases, log_prefix, location_config, name=None
-):  # pragma: no cover
+def make_database_dump_pattern(databases, config, log_prefix, name=None):  # pragma: no cover
     '''
     Make a pattern that matches the given SQLite3 databases. The databases are supplied as a
     sequence of configuration dicts, as per the configuration schema.
     '''
-    return dump.make_database_dump_filename(make_dump_path(location_config), name)
+    return dump.make_database_dump_filename(make_dump_path(config), name)
 
 
-def restore_database_dump(database_config, log_prefix, location_config, dry_run, extract_process):
+def restore_database_dump(
+    databases_config, config, log_prefix, database_name, dry_run, extract_process, connection_params
+):
     '''
-    Restore the given SQLite3 database from an extract stream. The database is supplied as a
-    one-element sequence containing a dict describing the database, as per the configuration schema.
-    Use the given log prefix in any log entries. If this is a dry run, then don't actually restore
-    anything. Trigger the given active extract process (an instance of subprocess.Popen) to produce
-    output to consume.
+    Restore the given SQLite3 database from an extract stream. The databases are supplied as a
+    sequence containing one dict describing each database (as per the configuration schema), but
+    only the database corresponding to the given database name is restored. Use the given log prefix
+    in any log entries. If this is a dry run, then don't actually restore anything. Trigger the
+    given active extract process (an instance of subprocess.Popen) to produce output to consume.
     '''
     dry_run_label = ' (dry run; not actually restoring anything)' if dry_run else ''
 
-    if len(database_config) != 1:
-        raise ValueError('The database configuration value is invalid')
+    try:
+        database = next(
+            database_config
+            for database_config in databases_config
+            if database_config.get('name') == database_name
+        )
+    except StopIteration:
+        raise ValueError(
+            f'A database named "{database_name}" could not be found in the configuration'
+        )
 
-    database_path = database_config[0]['path']
+    database_path = connection_params['restore_path'] or database.get(
+        'restore_path', database.get('path')
+    )
 
     logger.debug(f'{log_prefix}: Restoring SQLite database at {database_path}{dry_run_label}')
     if dry_run:

borgmatic/logger.py

@@ -141,6 +141,7 @@ def add_logging_level(level_name, level_number):
 
 
 ANSWER = logging.WARN - 5
+DISABLED = logging.CRITICAL + 10
 
 
 def add_custom_log_levels():  # pragma: no cover
@@ -148,6 +149,7 @@ def add_custom_log_levels():  # pragma: no cover
     Add a custom log level between WARN and INFO for user-requested answers.
     '''
     add_logging_level('ANSWER', ANSWER)
+    add_logging_level('DISABLED', DISABLED)
 
 
 def configure_logging(
@@ -175,10 +177,12 @@ def configure_logging(
 
     # Log certain log levels to console stderr and others to stdout. This supports use cases like
     # grepping (non-error) output.
+    console_disabled = logging.NullHandler()
     console_error_handler = logging.StreamHandler(sys.stderr)
     console_standard_handler = logging.StreamHandler(sys.stdout)
     console_handler = Multi_stream_handler(
         {
+            logging.DISABLED: console_disabled,
             logging.CRITICAL: console_error_handler,
             logging.ERROR: console_error_handler,
             logging.WARN: console_error_handler,
@@ -191,7 +195,7 @@ def configure_logging(
     console_handler.setLevel(console_log_level)
 
     syslog_path = None
-    if log_file is None:
+    if log_file is None and syslog_log_level != logging.DISABLED:
         if os.path.exists('/dev/log'):
             syslog_path = '/dev/log'
         elif os.path.exists('/var/run/syslog'):
@@ -206,7 +210,7 @@ def configure_logging(
         )
         syslog_handler.setLevel(syslog_log_level)
         handlers = (console_handler, syslog_handler)
-    elif log_file:
+    elif log_file and log_file_log_level != logging.DISABLED:
         file_handler = logging.handlers.WatchedFileHandler(log_file)
         file_handler.setFormatter(
             logging.Formatter(

borgmatic/verbosity.py

@@ -2,6 +2,7 @@ import logging
 
 import borgmatic.logger
 
+VERBOSITY_DISABLED = -2
 VERBOSITY_ERROR = -1
 VERBOSITY_ANSWER = 0
 VERBOSITY_SOME = 1
@@ -15,6 +16,7 @@ def verbosity_to_log_level(verbosity):
     borgmatic.logger.add_custom_log_levels()
 
     return {
+        VERBOSITY_DISABLED: logging.DISABLED,
         VERBOSITY_ERROR: logging.ERROR,
         VERBOSITY_ANSWER: logging.ANSWER,
         VERBOSITY_SOME: logging.INFO,

docs/Dockerfile

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

docs/_data/borgmatic.js

@@ -0,0 +1,5 @@
+module.exports = function() {
+    return {
+        environment: process.env.NODE_ENV || "development"
+    };
+};

docs/_includes/components/suggestion-link.html

@@ -1,5 +1,5 @@
 <h2>Improve this documentation</h2>
 
 <p>Have an idea on how to make this documentation even better? Use our <a
-href="https://projects.torsion.org/borgmatic-collective/borgmatic/issues">issue tracker</a> to send your
-feedback!</p>
+href="https://torsion.org/borgmatic/#support-and-contributing">issue
+tracker</a> to send your feedback!</p>

docs/_includes/layouts/main.njk

@@ -11,7 +11,7 @@ headerClass: elv-header-default
             {% set navPages = collections.all | eleventyNavigation %}
             {% macro renderNavListItem(entry) -%}
             <li{% if entry.url == page.url %} class="elv-toc-active"{% endif %}>
-              <a {% if entry.url %}href="https://torsion.org/borgmatic/docs{{ entry.url | url }}"{% endif %}>{{ entry.title }}</a>
+              <a {% if entry.url %}href="{% if borgmatic.environment == "production" %}https://torsion.org/borgmatic/docs{% else %}http://localhost:8080/docs{% endif %}{{ entry.url | url }}"{% endif %}>{{ entry.title }}</a>
             {%- if entry.children.length -%}
               <ul>
                 {%- for child in entry.children %}{{ renderNavListItem(child) }}{% endfor -%}

docs/docker-compose.yaml

@@ -9,7 +9,7 @@ services:
       dockerfile: docs/Dockerfile
       context: ..
       args:
-        ENVIRONMENT: dev
+        ENVIRONMENT: development
   message:
     image: alpine
     container_name: message
@@ -17,6 +17,6 @@ services:
       - sh
       - -c
       - |
-        echo "You can view dev docs at http://localhost:8080"
+        echo; echo "You can view dev docs at http://localhost:8080"; echo
     depends_on:
       - docs

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

@@ -21,13 +21,34 @@ running backups, and specify `after_backup` hooks to perform cleanup steps
 afterwards. Here's an example:
 
 ```yaml
-hooks:
-    before_backup:
-        - mount /some/filesystem
-    after_backup:
-        - umount /some/filesystem
+before_backup:
+    - mount /some/filesystem
+after_backup:
+    - umount /some/filesystem
 ```
 
+If your command contains a special YAML character such as a colon, you may
+need to quote the entire string (or use a [multiline
+string](https://yaml-multiline.info/)) to avoid an error:
+
+```yaml
+before_backup:
+    - "echo Backup: start"
+```
+
+There are additional hooks that run before/after other actions as well. For
+instance, `before_prune` runs before a `prune` action for a repository, while
+`after_prune` runs after it.
+
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+these options in the `hooks:` section of your configuration.
+
+<span class="minilink minilink-addedin">New in version 1.7.0</span> The
+`before_actions` and `after_actions` hooks run before/after all the actions
+(like `create`, `prune`, etc.) for each repository. These hooks are a good
+place to run per-repository steps like mounting/unmounting a remote
+filesystem.
+
 <span class="minilink minilink-addedin">New in version 1.6.0</span> The
 `before_backup` and `after_backup` hooks each run once per repository in a
 configuration file. `before_backup` hooks runs right before the `create`
@@ -36,16 +57,6 @@ 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 for a repository, while
-`after_prune` runs after it.
-
-<span class="minilink minilink-addedin">New in version 1.7.0</span> The
-`before_actions` and `after_actions` hooks run before/after all the actions
-(like `create`, `prune`, etc.) for each repository. These hooks are a good
-place to run per-repository steps like mounting/unmounting a remote
-filesystem.
-
 
 ## Variable interpolation
 
@@ -54,11 +65,13 @@ 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}"
+after_prune:
+    - record-prune.sh "{configuration_filename}" "{repository}"
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `hooks:` section of your configuration.
+
 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
@@ -82,13 +95,15 @@ You can also use `before_everything` and `after_everything` hooks to perform
 global setup or cleanup:
 
 ```yaml
-hooks:
-    before_everything:
-        - set-up-stuff-globally
-    after_everything:
-        - clean-up-stuff-globally
+before_everything:
+    - set-up-stuff-globally
+after_everything:
+    - clean-up-stuff-globally
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+these options in the `hooks:` section of your configuration.
+
 `before_everything` hooks collected from all borgmatic configuration files run
 once before all configuration files (prior to all actions), but only if there
 is a `create` action. An error encountered during a `before_everything` hook
@@ -99,6 +114,7 @@ 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
@@ -106,6 +122,7 @@ a backup or running a backup hook. See the [monitoring and alerting
 documentation](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/)
 for more information.
 
+
 ## Hook output
 
 Any output produced by your hooks shows up both at the console and in syslog
@@ -113,6 +130,7 @@ Any output produced by your hooks shows up both at the console and in syslog
 href="https://torsion.org/borgmatic/docs/how-to/inspect-your-backups/">inspecting
 your backups</a>.
 
+
 ## Security
 
 An important security note about hooks: borgmatic executes all hook commands

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

@@ -44,14 +44,16 @@ file](https://torsion.org/borgmatic/docs/how-to/make-per-application-backups/),
 say at `/etc/borgmatic.d/removable.yaml`:
 
 ```yaml
-location:
-    source_directories:
-        - /home
+source_directories:
+    - /home
 
-    repositories:
-        - path: /mnt/removable/backup.borg
+repositories:
+    - path: /mnt/removable/backup.borg
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+these options in the `location:` section of your configuration.
+
 <span class="minilink minilink-addedin">Prior to version 1.7.10</span> Omit
 the `path:` portion of the `repositories` list.
 
@@ -60,11 +62,13 @@ the external `findmnt` utility to see whether the drive is mounted before
 proceeding.
 
 ```yaml
-hooks:
-    before_backup:
-      - findmnt /mnt/removable > /dev/null || exit 75
+before_backup:
+    - findmnt /mnt/removable > /dev/null || exit 75
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put this
+option in the `hooks:` section of your configuration.
+
 What this does is check if the `findmnt` command errors when probing for a
 particular mount point. If it does error, then it returns exit code 75 to
 borgmatic. borgmatic logs the soft failure, skips all further actions in that
@@ -77,27 +81,21 @@ optionally using `before_actions` instead.
 You can imagine a similar check for the sometimes-online server case:
 
 ```yaml
-location:
-    source_directories:
-        - /home
+source_directories:
+    - /home
 
-    repositories:
-        - path: ssh://me@buddys-server.org/./backup.borg
+repositories:
+    - path: ssh://me@buddys-server.org/./backup.borg
 
-hooks:
-    before_backup:
-      - ping -q -c 1 buddys-server.org > /dev/null || exit 75
+before_backup:
+    - ping -q -c 1 buddys-server.org > /dev/null || exit 75
 ```
 
-<span class="minilink minilink-addedin">Prior to version 1.7.10</span> Omit
-the `path:` portion of the `repositories` list.
-
 Or to only run backups if the battery level is high enough:
 
 ```yaml
-hooks:
-    before_backup:
-      - is_battery_percent_at_least.sh 25
+before_backup:
+    - is_battery_percent_at_least.sh 25
 ```
 
 (Writing the battery script is left as an exercise to the reader.)

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

@@ -18,31 +18,32 @@ prior to running backups. For example, here is everything you need to dump and
 backup a couple of local PostgreSQL databases and a MySQL/MariaDB database.
 
 ```yaml
-hooks:
-    postgresql_databases:
-        - name: users
-        - name: orders
-    mysql_databases:
-        - name: posts
+postgresql_databases:
+    - name: users
+    - name: orders
+mysql_databases:
+    - name: posts
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+these and other database options in the `hooks:` section of your
+configuration.
+
 <span class="minilink minilink-addedin">New in version 1.5.22</span> You can
 also dump MongoDB databases. For example:
 
 ```yaml
-hooks:
-    mongodb_databases:
-        - name: messages
+mongodb_databases:
+    - name: messages
 ```
 
 <span class="minilink minilink-addedin">New in version 1.7.9</span>
 Additionally, you can dump SQLite databases. For example:
 
 ```yaml
-hooks:
-    sqlite_databases:
-        - name: mydb
-          path: /var/lib/sqlite3/mydb.sqlite
+sqlite_databases:
+    - name: mydb
+      path: /var/lib/sqlite3/mydb.sqlite
 ```
 
 As part of each backup, borgmatic streams a database dump for each configured
@@ -54,7 +55,7 @@ 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
-in the `location` section of borgmatic's configuration.
+in borgmatic's configuration.
 
 Also note that using a database hook implicitly enables both the
 `read_special` and `one_file_system` configuration settings (even if they're
@@ -64,35 +65,34 @@ See Limitations below for more on this.
 Here's a more involved example that connects to remote databases:
 
 ```yaml
-hooks:
-    postgresql_databases:
-        - name: users
-          hostname: database1.example.org
-        - name: orders
-          hostname: database2.example.org
-          port: 5433
-          username: postgres
-          password: trustsome1
-          format: tar
-          options: "--role=someone"
-    mysql_databases:
-        - name: posts
-          hostname: database3.example.org
-          port: 3307
-          username: root
-          password: trustsome1
-          options: "--skip-comments"
-    mongodb_databases:
-        - name: messages
-          hostname: database4.example.org
-          port: 27018
-          username: dbuser
-          password: trustsome1
-          authentication_database: mongousers
-          options: "--ssl"
-    sqlite_databases:
-        - name: mydb
-          path: /var/lib/sqlite3/mydb.sqlite
+postgresql_databases:
+    - name: users
+      hostname: database1.example.org
+    - name: orders
+      hostname: database2.example.org
+      port: 5433
+      username: postgres
+      password: trustsome1
+      format: tar
+      options: "--role=someone"
+mysql_databases:
+    - name: posts
+      hostname: database3.example.org
+      port: 3307
+      username: root
+      password: trustsome1
+      options: "--skip-comments"
+mongodb_databases:
+    - name: messages
+      hostname: database4.example.org
+      port: 27018
+      username: dbuser
+      password: trustsome1
+      authentication_database: mongousers
+      options: "--ssl"
+sqlite_databases:
+    - name: mydb
+      path: /var/lib/sqlite3/mydb.sqlite
 ```
 
 See your [borgmatic configuration
@@ -106,13 +106,12 @@ listing databases, restoring databases, etc.).
 If you want to dump all databases on a host, use `all` for the database name:
 
 ```yaml
-hooks:
-    postgresql_databases:
-        - name: all
-    mysql_databases:
-        - name: all
-    mongodb_databases:
-        - name: all
+postgresql_databases:
+    - name: all
+mysql_databases:
+    - name: all
+mongodb_databases:
+    - name: all
 ```
 
 Note that you may need to use a `username` of the `postgres` superuser for
@@ -120,6 +119,9 @@ this to work with PostgreSQL.
 
 The SQLite hook in particular does not consider "all" a special database name.
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+these options in the `hooks:` section of your configuration.
+
 <span class="minilink minilink-addedin">New in version 1.7.6</span> With
 PostgreSQL and MySQL, you can optionally dump "all" databases to separate
 files instead of one combined dump file, allowing more convenient restores of
@@ -127,13 +129,12 @@ individual databases. Enable this by specifying your desired database dump
 `format`:
 
 ```yaml
-hooks:
-    postgresql_databases:
-        - name: all
-          format: custom
-    mysql_databases:
-        - name: all
-          format: sql
+postgresql_databases:
+    - name: all
+      format: custom
+mysql_databases:
+    - name: all
+      format: sql
 ```
 
 ### Containers
@@ -143,15 +144,17 @@ problem—configure borgmatic to connect to the container's name on its exposed
 port. For instance:
 
 ```yaml
-hooks:
-    postgresql_databases:
-        - name: users
-          hostname: your-database-container-name
-          port: 5433
-          username: postgres
-          password: trustsome1
+postgresql_databases:
+    - name: users
+      hostname: your-database-container-name
+      port: 5433
+      username: postgres
+      password: trustsome1
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+these options in the `hooks:` section of your configuration.
+
 But what if borgmatic is running on the host? You can still connect to a
 database container if its ports are properly exposed to the host. For
 instance, when running the database container, you can specify `--publish
@@ -179,8 +182,7 @@ hooks:
           password: trustsome1
 ```
 
-You can alter the ports in these examples to suit your particular database
-system.
+Alter the ports in these examples to suit your particular database system.
 
 
 ### No source directories
@@ -189,12 +191,14 @@ system.
 would like to backup databases only and not source directories, you can omit
 `source_directories` entirely.
 
-In older versions of borgmatic, instead specify an empty `source_directories`
-value, as it is a mandatory option prior to version 1.7.1:
+<span class="minilink minilink-addedin">Prior to version 1.7.1</span> In older
+versions of borgmatic, instead specify an empty `source_directories` value, as
+it is a mandatory option there:
 
 ```yaml
 location:
     source_directories: []
+
 hooks:
     mysql_databases:
         - name: all
@@ -291,7 +295,7 @@ restore one of them, use the `--database` flag to select one or more
 databases. For instance:
 
 ```bash
-borgmatic restore --archive host-2023-... --database users
+borgmatic restore --archive host-2023-... --database users --database orders
 ```
 
 <span class="minilink minilink-addedin">New in version 1.7.6</span> You can
@@ -348,17 +352,19 @@ borgmatic's own configuration file. So include your configuration file in
 backups to avoid getting caught without a way to restore a database.
 3. borgmatic does not currently support backing up or restoring multiple
 databases that share the exact same name on different hosts.
-4. Because database hooks implicitly enable the `read_special` configuration
-setting to support dump and restore streaming, you'll need to ensure that any
-special files are excluded from backups (named pipes, block devices,
-character devices, and sockets) to prevent hanging. Try a command like
-`find /your/source/path -type b -or -type c -or -type p -or -type s` to find
-such files. Common directories to exclude are `/dev` and `/run`, but that may
-not be exhaustive. <span class="minilink minilink-addedin">New in version
+4. Because database hooks implicitly enable the `read_special` configuration,
+any special files are excluded from backups (named pipes, block devices,
+character devices, and sockets) to prevent hanging. Try a command like `find
+/your/source/path -type b -or -type c -or -type p -or -type s` to find such
+files. Common directories to exclude are `/dev` and `/run`, but that may not
+be exhaustive. <span class="minilink minilink-addedin">New in version
 1.7.3</span> When database hooks are enabled, borgmatic automatically excludes
-special files that may cause Borg to hang, so you no longer need to manually
-exclude them. (This includes symlinks with special files as a destination.) You
-can override/prevent this behavior by explicitly setting `read_special` to true.
+special files (and symlinks to special files) that may cause Borg to hang, so
+generally you no longer need to manually exclude them. There are potential
+edge cases though in which applications on your system create new special files
+*after* borgmatic constructs its exclude list, resulting in Borg hangs. If that
+occurs, you can resort to the manual excludes described above. And to opt out
+of the auto-exclude feature entirely, explicitly set `read_special` to true.
 
 
 ### Manual restoration
@@ -408,6 +414,12 @@ authenticated. For instance, with PostgreSQL, check your
 [pg_hba.conf](https://www.postgresql.org/docs/current/auth-pg-hba-conf.html)
 file for that configuration.
 
+Additionally, MySQL/MariaDB may be picking up some of your credentials from a
+defaults file like `~/.my.cnf`. If that's the case, then it's possible
+MySQL/MariaDB ends up using, say, a username from borgmatic's configuration
+and a password from `~/.my.cnf`. This may result in authentication errors if
+this combination of credentials is not what you intend.
+
 
 ### MySQL table lock errors
 
@@ -418,10 +430,9 @@ You can add any additional flags to the `options:` in your database
 configuration. Here's an example:
 
 ```yaml
-hooks:
-    mysql_databases:
-        - name: posts
-          options: "--single-transaction --quick"
+mysql_databases:
+    - name: posts
+      options: "--single-transaction --quick"
 ```
 
 ### borgmatic hangs during backup

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

@@ -65,19 +65,20 @@ configure borgmatic to run repository checks only. Configure this in the
 `consistency` section of borgmatic configuration:
 
 ```yaml
-consistency:
-    checks:
-        - name: repository
+checks:
+    - name: repository
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `consistency:` section of your configuration.
+
 <span class="minilink minilink-addedin">Prior to version 1.6.2</span> The
 `checks` option was a plain list of strings without the `name:` part, and
 borgmatic ran each configured check every time checks were run. For example:
 
 ```yaml
-consistency:
-    checks:
-        - repository
+checks:
+    - repository
 ```
 
 
@@ -103,14 +104,16 @@ optionally configure checks to run on a periodic basis rather than every time
 borgmatic runs checks. For instance:
 
 ```yaml
-consistency:
-    checks:
-        - name: repository
-          frequency: 2 weeks
-        - name: archives
-          frequency: 1 month
+checks:
+    - name: repository
+      frequency: 2 weeks
+    - name: archives
+      frequency: 1 month
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `consistency:` section of your configuration.
+
 This tells borgmatic to run the `repository` consistency check at most once
 every two weeks for a given repository and the `archives` check at most once a
 month. The `frequency` value is a number followed by a unit of time, e.g. "3
@@ -137,6 +140,23 @@ If you want to temporarily ignore your configured frequencies, you can invoke
 `borgmatic check --force` to run checks unconditionally.
 
 
+### Running only checks
+
+<span class="minilink minilink-addedin">New in version 1.7.1</span> If you
+would like to only run consistency checks without creating backups (for
+instance with the `check` action on the command-line), you can omit
+the `source_directories` option entirely.
+
+<span class="minilink minilink-addedin">Prior to version 1.7.1</span> In older
+versions of borgmatic, instead specify an empty `source_directories` value, as
+it is a mandatory option there:
+
+```yaml
+location:
+    source_directories: []
+```
+
+
 ### Disabling checks
 
 If that's still too slow, you can disable consistency checks entirely,
@@ -145,18 +165,19 @@ either for a single repository or for all repositories.
 Disabling all consistency checks looks like this:
 
 ```yaml
-consistency:
-    checks:
-        - name: disabled
+checks:
+    - name: disabled
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `consistency:` section of your configuration.
+
 <span class="minilink minilink-addedin">Prior to version 1.6.2</span> `checks`
 was a plain list of strings without the `name:` part. For instance:
 
 ```yaml
-consistency:
-    checks:
-        - disabled
+checks:
+    - disabled
 ```
 
 If you have multiple repositories in your borgmatic configuration file,
@@ -164,9 +185,8 @@ you can keep running consistency checks, but only against a subset of the
 repositories:
 
 ```yaml
-consistency:
-    check_repositories:
-        - path/of/repository_to_check.borg
+check_repositories:
+    - path/of/repository_to_check.borg
 ```
 
 Finally, you can override your configuration file's consistency checks, and

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

@@ -7,7 +7,7 @@ eleventyNavigation:
 ---
 ## Source code
 
-To get set up to hack on borgmatic, first clone it via HTTPS or SSH:
+To get set up to develop on borgmatic, first clone it via HTTPS or SSH:
 
 ```bash
 git clone https://projects.torsion.org/borgmatic-collective/borgmatic.git
@@ -21,8 +21,8 @@ git clone ssh://git@projects.torsion.org:3022/borgmatic-collective/borgmatic.git
 
 Then, install borgmatic
 "[editable](https://pip.pypa.io/en/stable/cli/pip_install/#editable-installs)"
-so that you can run borgmatic commands while you're hacking on them to
-make sure your changes work.
+so that you can run borgmatic actions during development to make sure your
+changes work.
 
 ```bash
 cd borgmatic

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

@@ -65,7 +65,7 @@ everything from an archive. To do that, tack on one or more `--path` values.
 For instance:
 
 ```bash
-borgmatic extract --archive latest --path path/1 path/2
+borgmatic extract --archive latest --path path/1 --path path/2
 ```
 
 Note that the specified restore paths should not have a leading slash. Like a

docs/how-to/index.md

@@ -1,5 +1,6 @@
 ---
 eleventyNavigation:
   key: How-to guides
+  order: 1
 permalink: false
 ---

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

@@ -24,6 +24,15 @@ Or, for even more progress and debug spew:
 borgmatic --verbosity 2
 ```
 
+The full set of verbosity levels are:
+
+ * `-2`: disable output entirely <span class="minilink minilink-addedin">New in borgmatic 1.7.14</span>
+ * `-1`: only show errors
+ * `0`: default output
+ * `1`: some additional output (informational level)
+ * `2`: lots of additional output (debug level)
+
+
 ## Backup summary
 
 If you're less concerned with progress during a backup, and you only want to
@@ -51,7 +60,7 @@ with `--format`. Refer to the [borg list --format
 documentation](https://borgbackup.readthedocs.io/en/stable/usage/list.html#the-format-specifier-syntax)
 for available values.
 
-*(No borgmatic `list` or `info` actions? Upgrade borgmatic!)*
+(No borgmatic `list` or `info` actions? Upgrade borgmatic!)
 
 <span class="minilink minilink-addedin">New in borgmatic version 1.7.0</span>
 There are also `rlist` and `rinfo` actions for displaying repository

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

@@ -12,18 +12,20 @@ it. borgmatic supports this in its configuration by specifying multiple backup
 repositories. Here's an example:
 
 ```yaml
-location:
-    # List of source directories to backup.
-    source_directories:
-        - /home
-        - /etc
+# List of source directories to backup.
+source_directories:
+    - /home
+    - /etc
 
-    # Paths of local or remote repositories to backup to.
-    repositories:
-        - path: ssh://k8pDxu32@k8pDxu32.repo.borgbase.com/./repo
-        - path: /var/lib/backups/local.borg
+# Paths of local or remote repositories to backup to.
+repositories:
+    - path: ssh://k8pDxu32@k8pDxu32.repo.borgbase.com/./repo
+    - path: /var/lib/backups/local.borg
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+these options in the `location:` section of your configuration.
+
 <span class="minilink minilink-addedin">Prior to version 1.7.10</span> Omit
 the `path:` portion of the `repositories` list.
 

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

@@ -20,18 +20,22 @@ instance, for applications:
 
 ```bash
 sudo mkdir /etc/borgmatic.d
-sudo generate-borgmatic-config --destination /etc/borgmatic.d/app1.yaml
-sudo generate-borgmatic-config --destination /etc/borgmatic.d/app2.yaml
+sudo borgmatic config generate --destination /etc/borgmatic.d/app1.yaml
+sudo borgmatic config generate --destination /etc/borgmatic.d/app2.yaml
 ```
 
 Or, for repositories:
 
 ```bash
 sudo mkdir /etc/borgmatic.d
-sudo generate-borgmatic-config --destination /etc/borgmatic.d/repo1.yaml
-sudo generate-borgmatic-config --destination /etc/borgmatic.d/repo2.yaml
+sudo borgmatic config generate --destination /etc/borgmatic.d/repo1.yaml
+sudo borgmatic config generate --destination /etc/borgmatic.d/repo2.yaml
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.7.15</span> The
+command to generate configuration files was `generate-borgmatic-config`
+instead of `borgmatic config generate`.
+
 When you set up multiple configuration files like this, borgmatic will run
 each one in turn from a single borgmatic invocation. This includes, by
 default, the traditional `/etc/borgmatic/config.yaml` as well.
@@ -70,14 +74,15 @@ and borgmatic uses that format to name any new archive it creates. For
 instance:
 
 ```yaml
-storage:
-    ...
-    archive_name_format: home-directories-{now}
+archive_name_format: home-directories-{now}
 ```
 
-This means that when borgmatic creates an archive, its name will start with
-the string `home-directories-` and end with a timestamp for its creation time.
-If `archive_name_format` is unspecified, the default is
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `storage:` section of your configuration.
+
+This example means that when borgmatic creates an archive, its name will start
+with the string `home-directories-` and end with a timestamp for its creation
+time. If `archive_name_format` is unspecified, the default is
 `{hostname}-{now:%Y-%m-%dT%H:%M:%S.%f}`, meaning your system hostname plus a
 timestamp in a particular format.
 
@@ -99,11 +104,12 @@ to filter archives when running supported actions.
 For instance, let's say that you have this in your configuration:
 
 ```yaml
-storage:
-    ...
-    archive_name_format: {hostname}-user-data-{now}
+archive_name_format: {hostname}-user-data-{now}
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `storage:` section of your configuration.
+
 borgmatic considers `{now}` an emphemeral data placeholder that will probably
 change per archive, while `{hostname}` won't. So it turns the example value
 into `{hostname}-user-data-*` and applies it to filter down the set of
@@ -119,10 +125,8 @@ If this behavior isn't quite smart enough for your needs, you can use the
 filtering archives. For example:
 
 ```yaml
-storage:
-    ...
-    archive_name_format: {hostname}-user-data-{now}
-    match_archives: sh:myhost-user-data-*        
+archive_name_format: {hostname}-user-data-{now}
+match_archives: sh:myhost-user-data-*        
 ```
 
 For Borg 1.x, use a shell pattern for the `match_archives` value and see the
@@ -152,23 +156,28 @@ them. To achieve this, you can put fragments of common configuration options
 into a file, and then include or inline that file into one or more borgmatic
 configuration files.
 
-Let's say that you want to include common retention configuration across all
+Let's say that you want to include common consistency check configuration across all
 of your configuration files. You could do that in each configuration file with
 the following:
 
 ```yaml
-location:
-   ...
+repositories:
+    - path: repo.borg
 
-retention:
-    !include /etc/borgmatic/common_retention.yaml
+checks:
+    !include /etc/borgmatic/common_checks.yaml
 ```
 
-And then the contents of `common_retention.yaml` could be:
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> These
+options were organized into sections like `location:` and `consistency:`.
+
+The contents of `common_checks.yaml` could be:
 
 ```yaml
-keep_hourly: 24
-keep_daily: 7
+- name: repository
+  frequency: 3 weeks
+- name: archives
+  frequency: 2 weeks
 ```
 
 To prevent borgmatic from trying to load these configuration fragments by
@@ -180,18 +189,18 @@ 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
+Note that this form of include must be a value rather than an option name. For
 example, this will not work:
 
 ```yaml
-location:
-   ...
+repositories:
+    - path: repo.borg
 
 # Don't do this. It won't work!
-!include /etc/borgmatic/common_retention.yaml
+!include /etc/borgmatic/common_checks.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 option name *and* its values, keep reading!
 
 
 ## Include merging
@@ -199,45 +208,43 @@ But if you do want to merge in a YAML key *and* its values, keep reading!
 If you need to get even fancier and merge in common configuration 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
-retention and consistency options via a single include:
+retention and consistency checks options via a single include:
 
 ```yaml
-<<: !include /etc/borgmatic/common.yaml
+repositories:
+   - path: repo.borg
 
-location:
-   ...
+<<: !include /etc/borgmatic/common.yaml
 ```
 
 This is what `common.yaml` might look like:
 
 ```yaml
-retention:
-    keep_hourly: 24
-    keep_daily: 7
+keep_hourly: 24
+keep_daily: 7
 
-consistency:
-    checks:
-        - name: repository
+checks:
+    - name: repository
+      frequency: 3 weeks
+    - name: archives
+      frequency: 2 weeks
 ```
 
-Once this include gets merged in, the resulting configuration would have all
-of the `location` options from the original configuration file *and* the
-`retention` and `consistency` options from the include.
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> These
+options were organized into sections like `retention:` and `consistency:`.
 
-Prior to borgmatic version 1.6.0, when there's a section collision between the
-local file and the merged include, the local file's section takes precedence.
-So if the `retention` section appears in both the local file and the include
-file, the included `retention` is ignored in favor of the local `retention`.
-But see below about deep merge in version 1.6.0+.
+Once this include gets merged in, the resulting configuration would have all
+of the options from the original configuration file *and* the options from the
+include.
 
 Note that this `<<` include merging syntax is only for merging in mappings
 (configuration options and their values). But if you'd like to include a
-single value directly, please see the section above about standard includes.
+single value directly, please see the above about standard includes.
 
 Additionally, there is a limitation preventing multiple `<<` include merges
-per section. So for instance, that means you can do one `<<` merge at the
-global level, another `<<` within each configuration section, etc. (This is a
-YAML limitation.)
+per file or option value. So for instance, that means you can do one `<<`
+merge at the global level, another `<<` within each nested option value, etc.
+(This is a YAML limitation.)
 
 
 ### Deep merge
@@ -248,29 +255,30 @@ at all levels in the two configuration files. This allows you to include
 common configuration—up to full borgmatic configuration files—while overriding
 only the parts you want to customize.
 
-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:
+For instance, here's an example of a main configuration file that pulls in
+options via an include and then overrides one of them locally:
 
 ```yaml
 <<: !include /etc/borgmatic/common.yaml
 
-location:
-   ...
+constants:
+    hostname: myhostname
 
-retention:
-    keep_daily: 5
+repositories:
+    - path: repo.borg
 ```
 
 This is what `common.yaml` might look like:
 
 ```yaml
-retention:
-    keep_hourly: 24
-    keep_daily: 7
+constants:
+    prefix: myprefix
+    hostname: otherhost
 ```
 
 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`.
+`prefix` value of `myprefix` and an overridden `hostname` value of
+`myhostname`.
 
 When there's an option collision between the local file and the merged
 include, the local file's option takes precedence.
@@ -288,21 +296,22 @@ configuration file, you can omit it with an `!omit` tag. For instance:
 ```yaml
 <<: !include /etc/borgmatic/common.yaml
 
-location:
-   source_directories:
-     - !omit /home
-     - /var
+source_directories:
+    - !omit /home
+    - /var
 ```
 
 And `common.yaml` like this:
 
 ```yaml
-location:
-   source_directories:
-     - /home
-     - /etc
+source_directories:
+    - /home
+    - /etc
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `location:` section of your configuration.
+
 Once this include gets merged in, the resulting configuration will have a
 `source_directories` value of `/etc` and `/var`—with `/home` omitted.
 
@@ -315,16 +324,15 @@ an example of some things not to do:
 ```yaml
 <<: !include /etc/borgmatic/common.yaml
 
-location:
-   source_directories:
-     # Do not do this! It will not work. "!omit" belongs before "/home".
-     - /home !omit
+source_directories:
+    # Do not do this! It will not work. "!omit" belongs before "/home".
+    - /home !omit
 
-   # Do not do this either! "!omit" only works on scalar list items.
-   repositories: !omit
-     # Also do not do this for the same reason! This is a list item, but it's
-     # not a scalar.
-     - !omit path: repo.borg
+# Do not do this either! "!omit" only works on scalar list items.
+repositories: !omit
+    # Also do not do this for the same reason! This is a list item, but it's
+    # not a scalar.
+    - !omit path: repo.borg
 ```
 
 Additionally, the `!omit` tag only works in a configuration file that also
@@ -338,8 +346,8 @@ includes.
 ### Shallow merge
 
 Even though deep merging is generally pretty handy for included files,
-sometimes you want specific sections in the local file to take precedence over
-included sections—without any merging occurring for them.
+sometimes you want specific options in the local file to take precedence over
+included options—without any merging occurring for them.
 
 <span class="minilink minilink-addedin">New in version 1.7.12</span> That's
 where the `!retain` tag comes in. Whenever you're merging an included file
@@ -353,37 +361,38 @@ on the `retention` mapping:
 ```yaml
 <<: !include /etc/borgmatic/common.yaml
 
-location:
-   repositories:
-     - path: repo.borg
+repositories:
+    - path: repo.borg
 
-retention: !retain
-    keep_daily: 5
+checks: !retain
+    - name: repository
 ```
 
 And `common.yaml` like this:
 
 ```yaml
-location:
-   repositories:
-     - path: common.borg
+repositories:
+    - path: common.borg
 
-retention:
-    keep_hourly: 24
-    keep_daily: 7
+checks:
+    - name: archives
 ```
 
-Once this include gets merged in, the resulting configuration will have a
-`keep_daily` value of `5` and nothing else in the `retention` section. That's
-because the `!retain` tag says to retain the local version of `retention` and
-ignore any values coming in from the include. But because the `repositories`
-list doesn't have a `!retain` tag, it still gets merged together to contain
-both `common.borg` and `repo.borg`.
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> These
+options were organized into sections like `location:` and `consistency:`.
 
-The `!retain` tag can only be placed on mappings and lists, and it goes right
-after the name of the option (and its colon) on the same line. The effects of
-`!retain` are recursive, meaning that if you place a `!retain` tag on a
-top-level mapping, even deeply nested values within it will not be merged.
+Once this include gets merged in, the resulting configuration will have a
+`checks` value with a name of `repository` and no other values. That's because
+the `!retain` tag says to retain the local version of `checks` and ignore any
+values coming in from the include. But because the `repositories` list doesn't
+have a `!retain` tag, it still gets merged together to contain both
+`common.borg` and `repo.borg`.
+
+The `!retain` tag can only be placed on mappings (keys/values) and lists, and
+it goes right after the name of the option (and its colon) on the same line.
+The effects of `!retain` are recursive, meaning that if you place a `!retain`
+tag on a top-level mapping, even deeply nested values within it will not be
+merged.
 
 Additionally, the `!retain` tag only works in a configuration file that also
 performs a merge include with `<<: !include`. It doesn't make sense within,
@@ -395,9 +404,16 @@ includes.
 
 ## Debugging includes
 
-<span class="minilink minilink-addedin">New in version 1.7.12</span> If you'd
+<span class="minilink minilink-addedin">New in version 1.7.15</span> If you'd
 like to see what the loaded configuration looks like after includes get merged
-in, run `validate-borgmatic-config` on your configuration file:
+in, run the `validate` action on your configuration file:
+
+```bash
+sudo borgmatic config validate --show
+```
+
+<span class="minilink minilink-addedin">In version 1.7.12 through
+1.7.14</span> Use this command instead:
 
 ```bash
 sudo validate-borgmatic-config --show
@@ -423,43 +439,41 @@ Whatever the reason, you can override borgmatic configuration options at the
 command-line via the `--override` flag. Here's an example:
 
 ```bash
-borgmatic create --override location.remote_path=/usr/local/bin/borg1
+borgmatic create --override remote_path=/usr/local/bin/borg1
 ```
 
 What this does is load your configuration files, and for each one, disregard
-the configured value for the `remote_path` option in the `location` section,
-and use the value of `/usr/local/bin/borg1` instead.
+the configured value for the `remote_path` option, and use the value of
+`/usr/local/bin/borg1` instead.
 
-You can even override multiple values at once. For instance:
+You can even override nested values or multiple values at once. For instance:
 
 ```bash
-borgmatic create --override section.option1=value1 section.option2=value2
+borgmatic create --override parent_option.option1=value1 --override parent_option.option2=value2
 ```
 
-This will accomplish the same thing:
-
-```bash
-borgmatic create --override section.option1=value1 --override section.option2=value2
-```
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Don't
+forget to specify the section that an option is in. That looks like a prefix
+on the option name, e.g. `location.repositories`.
 
 Note that each value is parsed as an actual YAML string, so you can even set
 list values by using brackets. For instance:
 
 ```bash
-borgmatic create --override location.repositories=[test1.borg,test2.borg]
+borgmatic create --override repositories=[test1.borg,test2.borg]
 ```
 
 Or even a single list element:
 
 ```bash
-borgmatic create --override location.repositories=[/root/test.borg]
+borgmatic create --override repositories=[/root/test.borg]
 ```
 
 If your override value contains special YAML characters like colons, then
 you'll need quotes for it to parse correctly:
 
 ```bash
-borgmatic create --override location.repositories="['user@server:test.borg']"
+borgmatic create --override repositories="['user@server:test.borg']"
 ```
 
 There is not currently a way to override a single element of a list without
@@ -475,7 +489,9 @@ indentation and a leading dash.)
 Be sure to quote your overrides if they contain spaces or other characters
 that your shell may interpret.
 
-An alternate to command-line overrides is passing in your values via [environment variables](https://torsion.org/borgmatic/docs/how-to/provide-your-passwords/).
+An alternate to command-line overrides is passing in your values via
+[environment
+variables](https://torsion.org/borgmatic/docs/how-to/provide-your-passwords/).
 
 
 ## Constant interpolation
@@ -495,16 +511,19 @@ constants:
     user: foo
     archive_prefix: bar
 
-location:
-    source_directories:
-        - /home/{user}/.config
-        - /home/{user}/.ssh
-    ...
+source_directories:
+    - /home/{user}/.config
+    - /home/{user}/.ssh
 
-storage:
-    archive_name_format: '{archive_prefix}-{now}'
+...
+
+archive_name_format: '{archive_prefix}-{now}'
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Don't
+forget to specify the section (like `location:` or `storage:`) that any option
+is in.
+
 In this example, when borgmatic runs, all instances of `{user}` get replaced
 with `foo` and all instances of `{archive-prefix}` get replaced with `bar-`.
 (And in this particular example, `{now}` doesn't get replaced with anything,
@@ -512,14 +531,13 @@ but gets passed directly to Borg.) After substitution, the logical result
 looks something like this:
 
 ```yaml
-location:
-    source_directories:
-        - /home/foo/.config
-        - /home/foo/.ssh
-    ...
+source_directories:
+    - /home/foo/.config
+    - /home/foo/.ssh
 
-storage:
-    archive_name_format: 'bar-{now}'
+...
+
+archive_name_format: 'bar-{now}'
 ```
 
 An alternate to constants is passing in your values via [environment

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

@@ -89,19 +89,20 @@ notifications or take other actions, so you can get alerted as soon as
 something goes wrong. Here's a not-so-useful example:
 
 ```yaml
-hooks:
-    on_error:
-        - echo "Error while creating a backup or running a backup hook."
+on_error:
+    - echo "Error while creating a backup or running a backup hook."
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `hooks:` section of your configuration.
+
 The `on_error` hook supports interpolating particular runtime variables into
 the hook command. Here's an example that assumes you provide a separate shell
 script to handle the alerting:
 
 ```yaml
-hooks:
-    on_error:
-        - send-text-message.sh "{configuration_filename}" "{repository}"
+on_error:
+    - send-text-message.sh "{configuration_filename}" "{repository}"
 ```
 
 In this example, when the error occurs, borgmatic interpolates runtime values
@@ -135,11 +136,13 @@ URL" for your project. Here's an example:
 
 
 ```yaml
-hooks:
-    healthchecks:
-        ping_url: https://hc-ping.com/addffa72-da17-40ae-be9c-ff591afb942a
+healthchecks:
+    ping_url: https://hc-ping.com/addffa72-da17-40ae-be9c-ff591afb942a
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `hooks:` section of your configuration.
+
 With this hook in place, borgmatic pings your Healthchecks project when a
 backup begins, ends, or errors. Specifically, after the <a
 href="https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/">`before_backup`
@@ -179,11 +182,13 @@ API URL" for your monitor. Here's an example:
 
 
 ```yaml
-hooks:
-    cronitor:
-        ping_url: https://cronitor.link/d3x0c1
+cronitor:
+    ping_url: https://cronitor.link/d3x0c1
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `hooks:` section of your configuration.
+
 With this hook in place, borgmatic pings your Cronitor monitor when a backup
 begins, ends, or errors. Specifically, after the <a
 href="https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/">`before_backup`
@@ -208,11 +213,13 @@ URL" for your monitor. Here's an example:
 
 
 ```yaml
-hooks:
-    cronhub:
-        ping_url: https://cronhub.io/start/1f5e3410-254c-11e8-b61d-55875966d031
+cronhub:
+    ping_url: https://cronhub.io/start/1f5e3410-254c-11e8-b61d-55875966d031
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `hooks:` section of your configuration.
+
 With this hook in place, borgmatic pings your Cronhub monitor when a backup
 begins, ends, or errors. Specifically, after the <a
 href="https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/">`before_backup`
@@ -251,11 +258,13 @@ Here's an example:
 
 
 ```yaml
-hooks:
-    pagerduty:
-        integration_key: a177cad45bd374409f78906a810a3074
+pagerduty:
+    integration_key: a177cad45bd374409f78906a810a3074
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `hooks:` section of your configuration.
+
 With this hook in place, borgmatic creates a PagerDuty event for your service
 whenever backups fail. Specifically, if an error occurs during a `create`,
 `prune`, `compact`, or `check` action, borgmatic sends an event to PagerDuty
@@ -291,31 +300,34 @@ An example configuration is shown here, with all the available options, includin
 [tags](https://ntfy.sh/docs/publish/#tags-emojis):
 
 ```yaml
-hooks:
-    ntfy:
-        topic: my-unique-topic
-        server: https://ntfy.my-domain.com
-        start:
-            title: A Borgmatic backup started
-            message: Watch this space...
-            tags: borgmatic
-            priority: min
-        finish:
-            title: A Borgmatic backup completed successfully
-            message: Nice!
-            tags: borgmatic,+1
-            priority: min
-        fail:
-            title: A Borgmatic backup failed
-            message: You should probably fix it
-            tags: borgmatic,-1,skull
-            priority: max
-        states:
-            - start
-            - finish
-            - fail
+ntfy:
+    topic: my-unique-topic
+    server: https://ntfy.my-domain.com
+    start:
+        title: A Borgmatic backup started
+        message: Watch this space...
+        tags: borgmatic
+        priority: min
+    finish:
+        title: A Borgmatic backup completed successfully
+        message: Nice!
+        tags: borgmatic,+1
+        priority: min
+    fail:
+        title: A Borgmatic backup failed
+        message: You should probably fix it
+        tags: borgmatic,-1,skull
+        priority: max
+    states:
+        - start
+        - finish
+        - fail
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+the `ntfy:` option in the `hooks:` section of your configuration.
+
+
 ## Scripting borgmatic
 
 To consume the output of borgmatic in other software, you can include an

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

@@ -20,10 +20,12 @@ pull your repository passphrase, your database passwords, or any other option
 values from environment variables. For instance:
 
 ```yaml
-storage:
-    encryption_passphrase: ${MY_PASSPHRASE}
+encryption_passphrase: ${MY_PASSPHRASE}
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `storage:` section of your configuration.
+
 This uses the `MY_PASSPHRASE` environment variable as your encryption
 passphrase. Note that the `{` `}` brackets are required. `$MY_PASSPHRASE` by
 itself will not work.
@@ -38,12 +40,14 @@ configuration](https://torsion.org/borgmatic/docs/how-to/backup-your-databases/)
 the same approach applies. For example:
 
 ```yaml
-hooks:
-    postgresql_databases:
-        - name: users
-          password: ${MY_DATABASE_PASSWORD}
+postgresql_databases:
+    - name: users
+      password: ${MY_DATABASE_PASSWORD}
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
+this option in the `hooks:` section of your configuration.
+
 This uses the `MY_DATABASE_PASSWORD` environment variable as your database
 password.
 
@@ -53,8 +57,7 @@ password.
 If you'd like to set a default for your environment variables, you can do so with the following syntax:
 
 ```yaml
-storage:
-    encryption_passphrase: ${MY_PASSPHRASE:-defaultpass}
+encryption_passphrase: ${MY_PASSPHRASE:-defaultpass}
 ```
 
 Here, "`defaultpass`" is the default passphrase if the `MY_PASSPHRASE`
@@ -72,8 +75,7 @@ can escape it with a backslash. For instance, if your password is literally
 `${A}@!`:
 
 ```yaml
-storage:
-    encryption_passphrase: \${A}@!
+encryption_passphrase: \${A}@!
 ```
 
 ### Related features

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

@@ -7,7 +7,7 @@ eleventyNavigation:
 ---
 ## Running Borg with borgmatic
 
-Borg has several commands (and options) that borgmatic does not currently
+Borg has several commands and options that borgmatic does not currently
 support. Sometimes though, as a borgmatic user, you may find yourself wanting
 to take advantage of these off-the-beaten-path Borg features. You could of
 course drop down to running Borg directly. But then you'd give up all the
@@ -17,11 +17,11 @@ request](https://torsion.org/borgmatic/#contributing) to add the feature. But
 what if you need it *now*?
 
 That's where borgmatic's support for running "arbitrary" Borg commands comes
-in. Running Borg commands with borgmatic takes advantage of the following, all
-based on your borgmatic configuration files or command-line arguments:
+in. Running these Borg commands with borgmatic can take advantage of the
+following, all based on your borgmatic configuration files or command-line
+arguments:
 
- * configured repositories (automatically runs your Borg command once for each
-   one)
+ * configured repositories, running your Borg command once for each one
  * local and remote Borg binary paths
  * SSH settings and Borg environment variables
  * lock wait settings
@@ -37,20 +37,18 @@ you run Borg with borgmatic is via the `borg` action. Here's a simple example:
 borgmatic borg break-lock
 ```
 
-(No `borg` action in borgmatic? Time to upgrade!)
+This runs Borg's `break-lock` command once with each configured borgmatic
+repository, passing the repository path in as a Borg-supported environment
+variable named `BORG_REPO`. (The native `borgmatic break-lock` action should
+be preferred though for most uses.)
 
-This runs Borg's `break-lock` command once on each configured borgmatic
-repository. Notice how the repository isn't present in the specified Borg
-options, as that part is provided by borgmatic.
-
-You can also specify Borg options for relevant commands:
+You can also specify Borg options for relevant commands. For instance:
 
 ```bash
 borgmatic borg rlist --short
 ```
 
 This runs Borg's `rlist` command once on each configured borgmatic repository.
-(The native `borgmatic rlist` action should be preferred for most use.)
 
 What if you only want to run Borg on a single configured borgmatic repository
 when you've got several configured? Not a problem. The `--repository` argument
@@ -60,10 +58,61 @@ lets you specify the repository to use, either by its path or its label:
 borgmatic borg --repository repo.borg break-lock
 ```
 
-And what about a single archive?
+And if you need to specify where the repository goes in the command because
+there are positional arguments after it:
 
 ```bash
-borgmatic borg --archive your-archive-name rlist
+borgmatic borg debug dump-manifest :: root
+```
+
+The `::` is a Borg placeholder that means: Substitute the repository passed in
+by environment variable here.
+
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span>borgmatic
+attempted to inject the repository name directly into your Borg arguments in
+the right place (which didn't always work). So your command-line in these
+older versions didn't support the `::`
+
+
+### Specifying an archive
+
+For borg commands that expect an archive name, you have a few approaches.
+Here's one:
+
+```bash
+borgmatic borg --archive latest list '::$ARCHIVE'
+```
+
+The single quotes are necessary in order to pass in a literal `$ARCHIVE`
+string instead of trying to resolve it from borgmatic's shell where it's not
+yet set.
+
+Or if you don't need borgmatic to resolve an archive name like `latest`, you
+can just do:
+
+```bash
+borgmatic borg list ::your-actual-archive-name
+```
+
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span>borgmatic
+provided the archive name implicitly along with the repository, attempting to
+inject it into your Borg arguments in the right place (which didn't always
+work). So your command-line in these older versions of borgmatic looked more
+like:
+
+```bash
+borgmatic borg --archive latest list
+```
+
+<span class="minilink minilink-addedin">With Borg version 2.x</span> Either of
+these will list an archive:
+
+```bash
+borgmatic borg --archive latest list '$ARCHIVE'
+```
+
+```bash
+borgmatic borg list your-actual-archive-name
 ```
 
 ### Limitations
@@ -71,14 +120,10 @@ borgmatic borg --archive your-archive-name rlist
 borgmatic's `borg` action is not without limitations:
 
  * The Borg command you want to run (`create`, `list`, etc.) *must* come first
-   after the `borg` action. If you have any other Borg options to specify,
-   provide them after. For instance, `borgmatic borg list --progress` will work,
-   but `borgmatic borg --progress list` will not.
- * borgmatic supplies the repository/archive name to Borg for you (based on
-   your borgmatic configuration or the `borgmatic borg --repository`/`--archive`
-   arguments), so do not specify the repository/archive otherwise.
- * The `borg` action will not currently work for any Borg commands like `borg
-   serve` that do not accept a repository/archive name.
+   after the `borg` action (and any borgmatic-specific arguments). If you have
+   other Borg options to specify, provide them after. For instance,
+   `borgmatic borg list --progress ...` will work, but
+   `borgmatic borg --progress list ...` will not.
  * Do not specify any global borgmatic arguments to the right of the `borg`
    action. (They will be passed to Borg instead of borgmatic.) If you have
    global borgmatic arguments, specify them *before* the `borg` action.
@@ -88,10 +133,18 @@ borgmatic's `borg` action is not without limitations:
    borgmatic action. In this case, only the Borg command is run.
  * Unlike normal borgmatic actions that support JSON, the `borg` action will
    not disable certain borgmatic logs to avoid interfering with JSON output.
- * Unlike other borgmatic actions, the `borg` action captures (and logs) all
-   output, so interactive prompts and flags like `--progress` will not work as
-   expected. <span class="minilink minilink-addedin">New in version
-   1.7.13</span> borgmatic now runs the `borg` action without capturing output,
+ * <span class="minilink minilink-addedin">Prior to version 1.8.0</span>
+   borgmatic implicitly injected the repository/archive arguments on the Borg
+   command-line for you (based on your borgmatic configuration or the
+   `borgmatic borg --repository`/`--archive` arguments)—which meant you
+   couldn't specify the repository/archive directly in the Borg command. Also,
+   in these older versions of borgmatic, the `borg` action didn't work for any
+   Borg commands like `borg serve` that do not accept a repository/archive
+   name.
+ * <span class="minilink minilink-addedin">Prior to version 1.7.13</span> Unlike
+   other borgmatic actions, the `borg` action captured (and logged) all output,
+   so interactive prompts and flags like `--progress` dit not work as expected.
+   In new versions, borgmatic runs the `borg` action without capturing output,
    so interactive prompts work.
 
 In general, this `borgmatic borg` feature should be considered an escape

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

@@ -89,7 +89,7 @@ installing borgmatic:
  * [Fedora official](https://bodhi.fedoraproject.org/updates/?search=borgmatic)
  * [Fedora unofficial](https://copr.fedorainfracloud.org/coprs/heffer/borgmatic/)
  * [Gentoo](https://packages.gentoo.org/packages/app-backup/borgmatic)
- * [Arch Linux](https://www.archlinux.org/packages/community/any/borgmatic/)
+ * [Arch Linux](https://archlinux.org/packages/extra/any/borgmatic/)
  * [Alpine Linux](https://pkgs.alpinelinux.org/packages?name=borgmatic)
  * [OpenBSD](https://openports.pl/path/sysutils/borgmatic)
  * [openSUSE](https://software.opensuse.org/package/borgmatic)
@@ -104,42 +104,50 @@ installing borgmatic:
 
 Need somewhere to store your encrypted off-site backups? The following hosting
 providers include specific support for Borg/borgmatic—and fund borgmatic
-development and hosting when you use these links to sign up. (These are
-referral links, but without any tracking scripts or cookies.)
+development and hosting when you use these referral links to sign up:
 
 <ul>
  <li class="referral"><a href="https://www.borgbase.com/?utm_source=borgmatic">BorgBase</a>: Borg hosting service with support for monitoring, 2FA, and append-only repos</li>
+ <li class="referral"><a href="https://hetzner.cloud/?ref=v9dOJ98Ic9I8">Hetzner</a>: A "storage box" that includes support for Borg</li>
 </ul>
 
-Additionally, [rsync.net](https://www.rsync.net/products/borg.html) and
-[Hetzner](https://www.hetzner.com/storage/storage-box) have compatible storage
-offerings, but do not currently fund borgmatic development or hosting.
+Additionally, rsync.net has a compatible storage offering, but does not fund
+borgmatic development or hosting.
 
 
 ## Configuration
 
 After you install borgmatic, generate a sample configuration file:
 
+```bash
+sudo borgmatic config generate
+```
+
+<span class="minilink minilink-addedin">Prior to version 1.7.15</span>
+Generate a configuration file with this command instead:
+
 ```bash
 sudo generate-borgmatic-config
 ```
 
-If that command is not found, then it may be installed in a location that's
-not in your system `PATH` (see above). Try looking in `~/.local/bin/`.
+If neither command is found, then borgmatic may be installed in a location
+that's not in your system `PATH` (see above). Try looking in `~/.local/bin/`.
 
-This generates a sample configuration file at `/etc/borgmatic/config.yaml` by
-default. If you'd like to use another path, use the `--destination` flag, for
-instance: `--destination ~/.config/borgmatic/config.yaml`.
+The command generates a sample configuration file at
+`/etc/borgmatic/config.yaml` by default. If you'd like to use another path,
+use the `--destination` flag, for instance: `--destination
+~/.config/borgmatic/config.yaml`.
 
 You should edit the configuration file to suit your needs, as the generated
 values are only representative. All options are optional except where
-indicated, so feel free to ignore anything you don't need.
+indicated, so feel free to ignore anything you don't need. Be sure to use
+spaces rather than tabs for indentation; YAML does not allow tabs.
 
-Note that the configuration file is organized into distinct sections, each
-with a section name like `location:` or `storage:`. So take care that if you
-uncomment a particular option, also uncomment its containing section name, or
-else borgmatic won't recognize the option. Also be sure to use spaces rather
-than tabs for indentation; YAML does not allow tabs.
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> The
+configuration file was organized into distinct sections, each with a section
+name like `location:` or `storage:`. So in older versions of borgmatic, take
+care that if you uncomment a particular option, also uncomment its containing
+section name—or else borgmatic won't recognize the option.
 
 You can get the same sample configuration file from the [configuration
 reference](https://torsion.org/borgmatic/docs/reference/configuration/), the
@@ -177,6 +185,13 @@ redundant](https://torsion.org/borgmatic/docs/how-to/make-backups-redundant/).
 If you'd like to validate that your borgmatic configuration is valid, the
 following command is available for that:
 
+```bash
+sudo borgmatic config validate
+```
+
+<span class="minilink minilink-addedin">Prior to version 1.7.15</span>
+Validate a configuration file with this command instead:
+
 ```bash
 sudo validate-borgmatic-config
 ```

docs/how-to/upgrade.md

@@ -29,29 +29,33 @@ configuration options. This is completely optional. If you prefer, you can add
 new configuration options manually.
 
 If you do want to upgrade your configuration file to include new options, use
-the `generate-borgmatic-config` script with its optional `--source` flag that
+the `borgmatic config generate` action with its optional `--source` flag that
 takes the path to your original configuration file. If provided with this
-path, `generate-borgmatic-config` merges your original configuration into the
+path, `borgmatic config generate` merges your original configuration into the
 generated configuration file, so you get all the newest options and comments.
 
 Here's an example:
 
 ```bash
-generate-borgmatic-config --source config.yaml --destination config-new.yaml
+borgmatic config generate --source config.yaml --destination config-new.yaml
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.7.15</span> The
+command to generate configuration files was `generate-borgmatic-config`
+instead of `borgmatic config generate`.
+
 New options start as commented out, so you can edit the file and decide
 whether you want to use each one.
 
 There are a few caveats to this process. First, when generating the new
-configuration file, `generate-borgmatic-config` replaces any comments you've
+configuration file, `borgmatic config generate` replaces any comments you've
 written in your original configuration file with the newest generated
 comments. Second, the script adds back any options you had originally deleted,
 although it does so with the options commented out. And finally, any YAML
 includes you've used in the source configuration get flattened out into a
 single generated file.
 
-As a safety measure, `generate-borgmatic-config` refuses to modify
+As a safety measure, `borgmatic config generate` refuses to modify
 configuration files in-place. So it's up to you to review the generated file
 and, if desired, replace your original configuration file with it.
 
@@ -61,21 +65,22 @@ and, if desired, replace your original configuration file with it.
 borgmatic changed its configuration file format in version 1.1.0 from
 INI-style to YAML. This better supports validation, and has a more natural way
 to express lists of values. To upgrade your existing configuration, first
-upgrade to the new version of borgmatic.
+upgrade to the last version of borgmatic to support converting configuration:
+borgmatic 1.7.14.
 
 As of version 1.1.0, borgmatic no longer supports Python 2. If you were
 already running borgmatic with Python 3, then you can upgrade borgmatic
 in-place:
 
 ```bash
-sudo pip3 install --user --upgrade borgmatic
+sudo pip3 install --user --upgrade borgmatic==1.7.14
 ```
 
 But if you were running borgmatic with Python 2, uninstall and reinstall instead:
 
 ```bash
 sudo pip uninstall borgmatic
-sudo pip3 install --user borgmatic
+sudo pip3 install --user borgmatic==1.7.14
 ```
 
 The pip binary names for different versions of Python can differ, so the above
@@ -93,29 +98,12 @@ That will generate a new YAML configuration file at /etc/borgmatic/config.yaml
 excludes files. The new version of borgmatic will consume the YAML
 configuration file instead of the old one.
 
-
-### Upgrading from atticmatic
-
-You can ignore this section if you're not an atticmatic user (the former name
-of borgmatic).
-
-borgmatic only supports Borg now and no longer supports Attic. So if you're
-an Attic user, consider switching to Borg. See the [Borg upgrade
-command](https://borgbackup.readthedocs.io/en/stable/usage.html#borg-upgrade)
-for more information. Then, follow the instructions above about setting up
-your borgmatic configuration files.
-
-If you were already using Borg with atticmatic, then you can upgrade
-from atticmatic to borgmatic by running the following commands:
+Now you can upgrade to a newer version of borgmatic:
 
 ```bash
-sudo pip3 uninstall atticmatic
 sudo pip3 install --user borgmatic
 ```
 
-That's it! borgmatic will continue using your /etc/borgmatic configuration
-files.
-
 
 ## Upgrading Borg
 
@@ -143,22 +131,23 @@ Let's say your original borgmatic repository configuration file looks something
 like this:
 
 ```yaml
-location:
-    repositories:
-        - path: original.borg
+repositories:
+    - path: original.borg
 ```
 
-<span class="minilink minilink-addedin">Prior to version 1.7.10</span> Omit
-the `path:` portion of the `repositories` list.
-
 Change it to a new (not yet created) repository path:
 
 ```yaml
-location:
-    repositories:
-        - path: upgraded.borg
+repositories:
+    - path: upgraded.borg
 ```
 
+<span class="minilink minilink-addedin">Prior to version 1.8.0</span> This
+option was found in the `location:` section of your configuration.
+
+<span class="minilink minilink-addedin">Prior to version 1.7.10</span> Omit
+the `path:` portion of the `repositories` list.
+
 Then, run the `rcreate` action (formerly `init`) to create that new Borg 2
 repository:
 

docs/reference/command-line.md

@@ -7,11 +7,18 @@ eleventyNavigation:
 ---
 ## borgmatic options
 
-Here are all of the available borgmatic command-line options, including the
-separate options for each action sub-command. Note that most of the
-flags listed here do not have equivalents in borgmatic's [configuration
+Here are all of the available borgmatic command-line flags for the [most
+recent version of
+borgmatic](https://projects.torsion.org/borgmatic-collective/borgmatic/releases),
+including the separate flags for each action (sub-command). Most of the flags
+listed here do not have equivalents in borgmatic's [configuration
 file](https://torsion.org/borgmatic/docs/reference/configuration/).
 
+If you're using an older version of borgmatic, some of these flags may not be
+present in that version and you should instead use `borgmatic --help` or
+`borgmatic [action name] --help` (where `[action name]` is the name of an
+action like `list`, `create`, etc.).
+
 ```
 {% include borgmatic/command-line.txt %}
 ```

docs/reference/configuration.md

@@ -7,11 +7,19 @@ eleventyNavigation:
 ---
 ## Configuration file
 
-Here is a full sample borgmatic configuration file including all available options: 
+Below is a sample borgmatic configuration file including all available options
+for the [most recent version of
+borgmatic](https://projects.torsion.org/borgmatic-collective/borgmatic/releases).
+This file is also [available for
+download](https://torsion.org/borgmatic/docs/reference/config.yaml).
+
+If you're using an older version of borgmatic, some of these options may not
+work, and you should instead [generate a sample configuration file specific to
+your borgmatic
+version](https://torsion.org/borgmatic/docs/how-to/set-up-backups/#configuration).
 
 ```yaml
 {% include borgmatic/config.yaml %}
 ```
 
 Note that you can also [download this configuration
-file](https://torsion.org/borgmatic/docs/reference/config.yaml) for use locally.

docs/reference/index.md

@@ -1,5 +1,6 @@
 ---
 eleventyNavigation:
   key: Reference guides
+  order: 2
 permalink: false
 ---

sample/systemd/borgmatic-user.service

@@ -0,0 +1,15 @@
+[Unit]
+Description=borgmatic backup
+Wants=network-online.target
+After=network-online.target
+ConditionACPower=true
+
+[Service]
+Type=oneshot
+Restart=no
+# Prevent rate limiting of borgmatic log events. If you are using an older version of systemd that
+# doesn't support this (pre-240 or so), you may have to remove this option.
+LogRateLimitIntervalSec=0
+# Delay start to prevent backups running during boot.
+ExecStartPre=sleep 1m
+ExecStart=/root/.local/bin/borgmatic --verbosity -2 --syslog-verbosity 1