Fix incorrect option name within schema description.

Reviewed-on: borgmatic-collective/borgmatic#976

.drone.yml

@@ -1,56 +0,0 @@
-kind: pipeline
-name: python-3-8-alpine-3-13
-
-services:
-  - name: postgresql
-    image: postgres:13.1-alpine
-    environment:
-      POSTGRES_PASSWORD: test
-      POSTGRES_DB: test
-  - name: mysql
-    image: mariadb:10.5
-    environment:
-      MYSQL_ROOT_PASSWORD: test
-      MYSQL_DATABASE: test
-  - name: mongodb
-    image: mongo:5.0.5
-    environment:
-      MONGO_INITDB_ROOT_USERNAME: root
-      MONGO_INITDB_ROOT_PASSWORD: test
-
-clone:
-  skip_verify: true
-
-steps:
-- name: build
-  image: alpine:3.13
-  pull: always
-  commands:
-    - scripts/run-full-tests
----
-kind: pipeline
-name: documentation
-
-clone:
-  skip_verify: true
-
-steps:
-- name: build
-  image: plugins/docker
-  settings:
-    username:
-      from_secret: docker_username
-    password:
-      from_secret: docker_password
-    registry: projects.torsion.org
-    repo: projects.torsion.org/borgmatic-collective/borgmatic
-    tags: docs
-    dockerfile: docs/Dockerfile
-
-trigger:
-  repo:
-    - borgmatic-collective/borgmatic
-  branch:
-    - master
-  event:
-    - push

.eleventy.js

@@ -1,4 +1,5 @@
 const pluginSyntaxHighlight = require("@11ty/eleventy-plugin-syntaxhighlight");
+const codeClipboard = require("eleventy-plugin-code-clipboard");
 const inclusiveLangPlugin = require("@11ty/eleventy-plugin-inclusive-language");
 const navigationPlugin = require("@11ty/eleventy-navigation");
 
@@ -6,6 +7,7 @@ module.exports = function(eleventyConfig) {
     eleventyConfig.addPlugin(pluginSyntaxHighlight);
     eleventyConfig.addPlugin(inclusiveLangPlugin);
     eleventyConfig.addPlugin(navigationPlugin);
+    eleventyConfig.addPlugin(codeClipboard);
 
     let markdownIt = require("markdown-it");
     let markdownItAnchor = require("markdown-it-anchor");
@@ -31,6 +33,7 @@ module.exports = function(eleventyConfig) {
         markdownIt(markdownItOptions)
             .use(markdownItAnchor, markdownItAnchorOptions)
             .use(markdownItReplaceLink)
+            .use(codeClipboard.markdownItCopyButton)
     );
 
     eleventyConfig.addPassthroughCopy({"docs/static": "static"});

.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: true

.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

.gitea/workflows/build.yaml

@@ -0,0 +1,30 @@
+name: build
+run-name: ${{ gitea.actor }} is building
+on:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: host
+
+    steps:
+      - uses: actions/checkout@v4
+      - run: scripts/run-end-to-end-tests
+
+  docs:
+    needs: [test]
+    runs-on: host
+    env:
+      IMAGE_NAME: projects.torsion.org/borgmatic-collective/borgmatic:docs
+
+    steps:
+      - uses: actions/checkout@v4
+      - run: podman login --username "$USERNAME" --password "$PASSWORD" projects.torsion.org
+        env:
+          USERNAME: "${{ secrets.REGISTRY_USERNAME }}"
+          PASSWORD: "${{ secrets.REGISTRY_PASSWORD }}"
+      - run: podman build --tag "$IMAGE_NAME" --file docs/Dockerfile --storage-opt "overlay.mount_program=/usr/bin/fuse-overlayfs" .
+      - run: podman push "$IMAGE_NAME"
+      - run: scripts/export-docs-from-image
+      - run: curl --user "${{ secrets.REGISTRY_USERNAME }}:${{ secrets.REGISTRY_PASSWORD }}" --upload-file borgmatic-docs.tar.gz https://projects.torsion.org/api/packages/borgmatic-collective/generic/borgmatic-docs/$(head --lines=1 NEWS)/borgmatic-docs.tar.gz

NEWS

@@ -1,3 +1,511 @@
+1.9.8
+ * #979: Fix root patterns so they don't have an invalid "sh:" prefix before getting passed to Borg.
+ * Expand the recent contributors documentation section to include ticket submitters—not just code
+   contributors—because there are multiple ways to contribute to the project! See:
+   https://torsion.org/borgmatic/#recent-contributors
+
+1.9.7
+ * #855: Add a Sentry monitoring hook. See the documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#sentry-hook
+ * #968: Fix for a "spot" check error when a filename in the most recent archive contains a newline.
+ * #970: Fix for an error when there's a blank line in the configured patterns or excludes.
+ * #971: Fix for "exclude_from" files being completely ignored.
+ * #977: Fix for "exclude_patterns" and "exclude_from" not supporting explicit pattern styles (e.g.,
+   "sh:" or "re:").
+
+1.9.6
+ * #959: Fix an error in the Btrfs hook when a subvolume mounted at "/" is configured in borgmatic's
+   source directories.
+ * #960: Fix for archives storing relative source directory paths such that they contain the working
+   directory.
+ * #960: Fix the "spot" check to support relative source directory paths.
+ * #962: For the ZFS, Btrfs, and LVM hooks, perform path rewriting for excludes and patterns in
+   addition to the existing source directories rewriting.
+ * #962: Under the hood, merge all configured source directories, excludes, and patterns into a
+   unified temporary patterns file for passing to Borg. The borgmatic configuration options remain
+   unchanged.
+ * #962: For the LVM hook, add support for nested logical volumes.
+ * #965: Fix a borgmatic runtime directory error when running the "spot" check with a database hook
+   enabled.
+ * #969: Fix the "restore" action to work on database dumps without a port when a default port is
+   present in configuration.
+ * Fix the "spot" check to no longer consider pipe files within an archive for file comparisons.
+ * Fix the "spot" check to have a nicer error when there are no source paths to compare.
+ * Fix auto-excluding of special files (when databases are configured) to support relative source
+   directory paths.
+ * Drop support for Python 3.8, which has been end-of-lifed.
+
+1.9.5
+ * #418: Backup and restore databases that have the same name but with different ports, hostnames,
+   or hooks.
+ * #947: To avoid a hang in the database hooks, error and exit when the borgmatic runtime
+   directory overlaps with the configured excludes.
+ * #954: Fix a findmnt command error in the Btrfs hook by switching to parsing JSON output.
+ * #956: Fix the printing of a color reset code even when color is disabled.
+ * #958: Drop colorama as a library dependency.
+ * When the ZFS, Btrfs, or LVM hooks aren't configured, don't try to cleanup snapshots for them.
+
+1.9.4
+ * #80 (beta): Add an LVM hook for snapshotting and backing up LVM logical volumes. See the
+   documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/snapshot-your-filesystems/
+ * #251 (beta): Add a Btrfs hook for snapshotting and backing up Btrfs subvolumes. See the
+   documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/snapshot-your-filesystems/
+ * #926: Fix a library error when running within a PyInstaller bundle.
+ * #950: Fix a snapshot unmount error in the ZFS hook when using nested datasets.
+ * Update the ZFS hook to discover and snapshot ZFS datasets even if they are parent/grandparent
+   directories of your source directories.
+ * Reorganize data source and monitoring hooks to make developing new hooks easier.
+
+1.9.3
+ * #261 (beta): Add a ZFS hook for snapshotting and backing up ZFS datasets. See the documentation
+   for more information: https://torsion.org/borgmatic/docs/how-to/snapshot-your-filesystems/
+ * Remove any temporary copies of the manifest file created in support of the "bootstrap" action.
+ * Deprecate the "store_config_files" option at the global scope and move it under the "bootstrap"
+   hook. See the documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/extract-a-backup/#extract-the-configuration-files-used-to-create-an-archive
+ * Require the runtime directory to be an absolute path.
+ * Add a "--deleted" flag to the "repo-list" action for listing deleted archives that haven't
+   yet been compacted (Borg 2 only).
+ * Promote the "spot" check from a beta feature to stable.
+
+1.9.2
+ * #441: Apply the "umask" option to all relevant actions, not just some of them.
+ * #722: Remove the restriction that the "extract" and "mount" actions must match a single
+   repository. Now they work more like other actions, where each repository is applied in turn.
+ * #932: Fix the missing build backend setting in pyproject.toml to allow Fedora builds.
+ * #934: Update the logic that probes for the borgmatic streaming database dump, bootstrap
+   metadata, and check state directories to support more platforms and use cases. See the
+   documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/backup-your-databases/#runtime-directory
+ * #934: Add the "RuntimeDirectory" and "StateDirectory" options to the sample systemd service
+   file to support the new runtime and state directory logic.
+ * #939: Fix borgmatic ignoring the "BORG_RELOCATED_REPO_ACCESS_IS_OK" and
+   "BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK" environment variables.
+ * Add a Pushover monitoring hook. See the documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#pushover-hook
+
+1.9.1
+ * #928: Fix the user runtime directory location on macOS (and possibly Cygwin).
+ * #930: Fix an error with the sample systemd service when no credentials are configured.
+ * #931: Fix an error when implicitly upgrading the check state directory from ~/.borgmatic to
+   ~/.local/state/borgmatic across filesystems.
+
+1.9.0
+ * #609: Fix the glob expansion of "source_directories" values to respect the "working_directory"
+   option.
+ * #609: BREAKING: Apply the "working_directory" option to all actions, not just "create". This
+   includes repository paths, destination paths, mount points, etc.
+ * #562: Deprecate the "borgmatic_source_directory" option in favor of "user_runtime_directory"
+   and "user_state_directory".
+ * #562: BREAKING: Move the default borgmatic streaming database dump and bootstrap metadata
+   directory from ~/.borgmatic to /run/user/$UID/borgmatic, which is more XDG-compliant. You can
+   override this location with the new "user_runtime_directory" option. Existing archives with
+   database dumps at the old location are still restorable. 
+ * #562, #638: Move the default check state directory from ~/.borgmatic to 
+   ~/.local/state/borgmatic. This is more XDG-compliant and also prevents these state files from
+   getting backed up (unless you explicitly include them). You can override this location with the
+   new "user_state_directory" option. After the first time you run the "check" action with borgmatic
+   1.9.0, you can safely delete the ~/.borgmatic directory.
+ * #838: BREAKING: With Borg 1.4+, store database dumps and bootstrap metadata in a "/borgmatic"
+   directory within a backup archive, so the path doesn't depend on the current user. This means
+   that you can now backup as one user and restore or bootstrap as another user, among other use
+   cases.
+ * #902: Add loading of encrypted systemd credentials. See the documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/provide-your-passwords/#using-systemd-service-credentials
+ * #911: Add a "key change-passphrase" action to change the passphrase protecting a repository key.
+ * #914: Fix a confusing apparent hang when when the repository location changes, and instead
+   show a helpful error message.
+ * #915: BREAKING: Rename repository actions like "rcreate" to more explicit names like
+   "repo-create" for compatibility with recent changes in Borg 2.0.0b10.
+ * #918: BREAKING: When databases are configured, don't auto-enable the "one_file_system" option,
+   as existing auto-excludes of special files should be sufficient to prevent Borg from hanging on
+   them. But if this change causes problems for you, you can always enable "one_file_system"
+   explicitly.
+ * #919: Clarify the command-line help for the "--config" flag.
+ * #919: Document a policy for versioning and breaking changes:
+   https://torsion.org/borgmatic/docs/how-to/upgrade/#versioning-and-breaking-changes
+ * #921: BREAKING: Change soft failure command hooks to skip only the current repository rather than
+   all repositories in the configuration file.
+ * #922: Replace setup.py (Python packaging metadata) with the more modern pyproject.toml.
+ * When using Borg 2, default the "archive_name_format" option to just "{hostname}", as Borg 2 does
+   not require unique archive names; identical archive names form a common "series" that can be
+   targeted together. See the Borg 2 documentation for more information:
+   https://borgbackup.readthedocs.io/en/2.0.0b13/changes.html#borg-1-2-x-1-4-x-to-borg-2-0
+ * Add support for Borg 2's "rclone:" repository URLs, so you can backup to 70+ cloud storage
+   services whether or not they support Borg explicitly.
+ * Add support for Borg 2's "sftp://" repository URLs.
+ * Update the "--match-archives" and "--archive" flags to support Borg 2 series names or archive
+   hashes.
+ * Add a "--match-archives" flag to the "prune" action.
+ * Add "--local-path" and "--remote-path" flags to the "config bootstrap" action for setting the
+   Borg executable paths used for bootstrapping.
+ * Add a "--user-runtime-directory" flag to the "config bootstrap" action for helping borgmatic
+   locate the bootstrap metadata stored in an archive.
+ * Add a Zabbix monitoring hook. See the documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#zabbix-hook
+ * Add a tarball of borgmatic's HTML documentation to the packages on the project page.
+
+1.8.14
+ * #896: Fix an error in borgmatic rcreate/init on an empty repository directory with Borg 1.4.
+ * #898: Add glob ("*") support to the "--repository" flag. Just quote any values containing
+   globs so your shell doesn't interpret them.
+ * #899: Fix for a "bad character" Borg error in which the "spot" check fed Borg an invalid pattern.
+ * #900: Fix for a potential traceback (TypeError) during the handling of another error.
+ * #904: Clarify the configuration reference about the "spot" check options:
+   https://torsion.org/borgmatic/docs/reference/configuration/
+ * #905: Fix the "source_directories_must_exist" option to work with relative "source_directories"
+   paths when a "working_directory" is set.
+ * #906: Add documentation details for how to run custom database dump commands using binaries from
+   running containers:
+   https://torsion.org/borgmatic/docs/how-to/backup-your-databases/#containers
+ * Fix a regression in which the "color" option had no effect.
+ * Add a recent contributors section to the documentation, because credit where credit's due! See:
+   https://torsion.org/borgmatic/#recent-contributors
+
+1.8.13
+ * #298: Add "delete" and "rdelete" actions to delete archives or entire repositories.
+ * #785: Add an "only_run_on" option to consistency checks so you can limit a check to running on
+   particular days of the week. See the documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/deal-with-very-large-backups/#check-days
+ * #885: Add an Uptime Kuma monitoring hook. See the documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#uptime-kuma-hook
+ * #886: Fix a PagerDuty hook traceback with Python < 3.10.
+ * #889: Fix the Healthchecks ping body size limit, restoring it to the documented 100,000 bytes.
+
+1.8.12
+ * #817: Add a "--max-duration" flag to the "check" action and a "max_duration" option to the
+   repository check configuration. This tells Borg to interrupt a repository check after a certain
+   duration.
+ * #860: Fix interaction between environment variable interpolation in constants and shell escaping.
+ * #863: When color output is disabled (explicitly or implicitly), don't prefix each log line with
+   the log level.
+ * #865: Add an "upload_buffer_size" option to set the size of the upload buffer used in "create"
+   action.
+ * #866: Fix "Argument list too long" error in the "spot" check when checking hundreds of thousands
+   of files at once.
+ * #874: Add the configured repository label as "repository_label" to the interpolated variables
+   passed to before/after command hooks.
+ * #881: Fix "Unrecognized argument" error when the same value is used with different command-line
+   flags.
+ * In the "spot" check, don't try to hash symlinked directories.
+
+1.8.11
+ * #815: Add optional Healthchecks auto-provisioning via "create_slug" option.
+ * #851: Fix lack of file extraction when using "extract --strip-components all" on a path with a
+   leading slash.
+ * #854: Fix a traceback when the "data" consistency check is used.
+ * #857: Fix a traceback with "check --only spot" when the "spot" check is unconfigured.
+
+1.8.10
+ * #656 (beta): Add a "spot" consistency check that compares file counts and contents between your
+   source files and the latest archive, ensuring they fall within configured tolerances. This can
+   catch problems like incorrect excludes, inadvertent deletes, files changed by malware, etc. See
+   the documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/deal-with-very-large-backups/#spot-check
+ * #779: When "--match-archives *" is used with "check" action, don't skip Borg's orphaned objects
+   check.
+ * #842: When a command hook exits with a soft failure, ping the log and finish states for any
+   configured monitoring hooks.
+ * #843: Add documentation link to Loki dashboard for borgmatic:
+   https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#loki-hook
+ * #847: Fix "--json" error when Borg includes non-JSON warnings in JSON output.
+ * #848: SECURITY: Mask the password when logging a MongoDB dump or restore command.
+ * Fix handling of the NO_COLOR environment variable to ignore an empty value.
+ * Add documentation about backing up containerized databases by configuring borgmatic to exec into
+   a container to run a dump command:
+   https://torsion.org/borgmatic/docs/how-to/backup-your-databases/#containers
+
+1.8.9
+ * #311: Add custom dump/restore command options for MySQL and MariaDB.
+ * #811: Add an "access_token" option to the ntfy monitoring hook for authenticating
+   without username/password.
+ * #827: When the "--json" flag is given, suppress console escape codes so as not to
+   interfere with JSON output.
+ * #829: Fix "--override" values containing deprecated section headers not actually overriding
+   configuration options under deprecated section headers.
+ * #835: Add support for the NO_COLOR environment variable. See the documentation for more
+   information:
+   https://torsion.org/borgmatic/docs/how-to/set-up-backups/#colored-output
+ * #839: Add log sending for the Apprise logging hook, enabled by default. See the documentation for
+   more information:
+   https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#apprise-hook
+ * #839: Document a potentially breaking shell quoting edge case within error hooks:
+   https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#error-hooks
+ * #840: When running the "rcreate" action and the repository already exists but with a different
+   encryption mode than requested, error.
+ * Switch from Drone to Gitea Actions for continuous integration.
+ * Rename scripts/run-end-to-end-dev-tests to scripts/run-end-to-end-tests and use it in both dev
+   and CI for better dev-CI parity.
+ * Clarify documentation about restoring a database: borgmatic does not create the database upon
+   restore.
+
+1.8.8
+ * #370: For the PostgreSQL hook, pass the "PGSSLMODE" environment variable through to Borg when the
+   database's configuration omits the "ssl_mode" option.
+ * #818: Allow the "--repository" flag to match across multiple configuration files.
+ * #820: Fix broken repository detection in the "rcreate" action with Borg 1.4. The issue did not
+   occur with other versions of Borg.
+ * #822: Fix broken escaping logic in the PostgreSQL hook's "pg_dump_command" option.
+ * SECURITY: Prevent additional shell injection attacks within the PostgreSQL hook.
+
+1.8.7
+ * #736: Store included configuration files within each backup archive in support of the "config
+   bootstrap" action. Previously, only top-level configuration files were stored.
+ * #798: Elevate specific Borg warnings to errors or squash errors to
+ * warnings. See the documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/customize-warnings-and-errors/
+ * #810: SECURITY: Prevent shell injection attacks within the PostgreSQL hook, the MongoDB hook, the
+   SQLite hook, the "borgmatic borg" action, and command hook variable/constant interpolation.
+ * #814: Fix a traceback when providing an invalid "--override" value for a list option.
+
+1.8.6
+ * #767: Add an "--ssh-command" flag to the "config bootstrap" action for setting a custom SSH
+   command, as no configuration is available (including the "ssh_command" option) until
+   bootstrapping completes.
+ * #794: Fix a traceback when the "repositories" option contains both strings and key/value pairs.
+ * #800: Add configured repository labels to the JSON output for all actions.
+ * #802: The "check --force" flag now runs checks even if "check" is in "skip_actions".
+ * #804: Validate the configured action names in the "skip_actions" option.
+ * #807: Stream SQLite databases directly to Borg instead of dumping to an intermediate file.
+ * When logging commands that borgmatic executes, log the environment variables that
+   borgmatic sets for those commands. (But don't log their values, since they often contain
+   passwords.)
+
+1.8.5
+ * #701: Add a "skip_actions" option to skip running particular actions, handy for append-only or
+   checkless configurations. See the documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/set-up-backups/#skipping-actions
+ * #701: Deprecate the "disabled" value for the "checks" option in favor of the new "skip_actions"
+   option.
+ * #745: Constants now apply to included configuration, not just the file doing the includes. As a
+   side effect of this change, constants no longer apply to option names and only substitute into
+   configuration values.
+ * #779: Add a "--match-archives" flag to the "check" action for selecting the archives to check,
+   overriding the existing "archive_name_format" and "match_archives" options in configuration.
+ * #779: Only parse "--override" values as complex data types when they're for options of those
+   types.
+ * #782: Fix environment variable interpolation within configured repository paths.
+ * #782: Add configuration constant overriding via the existing "--override" flag.
+ * #783: Upgrade ruamel.yaml dependency to support version 0.18.x.
+ * #784: Drop support for Python 3.7, which has been end-of-lifed.
+
+1.8.4
+ * #715: Add a monitoring hook for sending backup status to a variety of monitoring services via the
+   Apprise library. See the documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#apprise-hook
+ * #748: When an archive filter causes no matching archives for the "rlist" or "info"
+   actions, warn the user and suggest how to remove the filter.
+ * #768: Fix a traceback when an invalid command-line flag or action is used.
+ * #771: Fix normalization of deprecated sections ("location:", "storage:", "hooks:", etc.) to
+   support empty sections without erroring.
+ * #774: Disallow the "--dry-run" flag with the "borg" action, as borgmatic can't guarantee the Borg
+   command won't have side effects.
+
+1.8.3
+ * #665: BREAKING: Simplify logging logic as follows: Syslog verbosity is now disabled by
+   default, but setting the "--syslog-verbosity" flag enables it regardless of whether you're at an
+   interactive console. Additionally, "--log-file-verbosity" and "--monitoring-verbosity" now
+   default to 1 (info about steps borgmatic is taking) instead of 0. And both syslog logging and
+   file logging can be enabled simultaneously.
+ * #743: Add a monitoring hook for sending backup status and logs to Grafana Loki. See the
+   documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#loki-hook
+ * #753: When "archive_name_format" is not set, filter archives using the default archive name
+   format.
+ * #754: Fix error handling to log command output as one record per line instead of truncating
+   too-long output and swallowing the end of some Borg error messages.
+ * #757: Update documentation so "sudo borgmatic" works for pipx borgmatic installations.
+ * #761: Fix for borgmatic not stopping Borg immediately when the user presses ctrl-C.
+ * Update documentation to recommend installing/upgrading borgmatic with pipx instead of pip. See the
+   documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/set-up-backups/#installation
+   https://torsion.org/borgmatic/docs/how-to/upgrade/#upgrading-borgmatic
+
+1.8.2
+ * #345: Add "key export" action to export a copy of the repository key for safekeeping in case
+   the original goes missing or gets damaged.
+ * #727: Add a MariaDB database hook that uses native MariaDB commands instead of the deprecated
+   MySQL ones. Be aware though that any existing backups made with the "mysql_databases:" hook are
+   only restorable with a "mysql_databases:" configuration.
+ * #738: Fix for potential data loss (data not getting restored) in which the database "restore"
+   action didn't actually restore anything and indicated success anyway.
+ * Remove the deprecated use of the MongoDB hook's "--db" flag for database restoration.
+ * Add source code reference documentation for getting oriented with the borgmatic code as a
+   developer: https://torsion.org/borgmatic/docs/reference/source-code/
+
+1.8.1
+ * #326: Add documentation for restoring a database to an alternate host:
+   https://torsion.org/borgmatic/docs/how-to/backup-your-databases/#restore-to-an-alternate-host
+ * #697: Add documentation for "bootstrap" action:
+   https://torsion.org/borgmatic/docs/how-to/extract-a-backup/#extract-the-configuration-files-used-to-create-an-archive
+ * #725: Add "store_config_files" option for disabling the automatic backup of configuration files
+   used by the "config bootstrap" action.
+ * #728: Fix for "prune" action error when using the "keep_exclude_tags" option.
+ * #730: Fix for Borg's interactive prompt on the "check --repair" action automatically getting
+   answered "NO" even when the "check_i_know_what_i_am_doing" option isn't set.
+ * #732: Include multiple configuration files with a single "!include". See the documentation for
+   more information:
+   https://torsion.org/borgmatic/docs/how-to/make-per-application-backups/#multiple-merge-includes
+ * #734: Omit "--glob-archives" or "--match-archives" Borg flag when its value would be "*" (meaning
+   all archives).
+
+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:
+   https://torsion.org/borgmatic/docs/how-to/backup-your-databases/#restore-particular-schemas
+ * #678: Fix error from PostgreSQL when dumping a database with a "format" of "plain".
+ * #678: Fix PostgreSQL hook to support "psql_command" and "pg_restore_command" options containing
+   commands with arguments.
+ * #678: Fix calls to psql in PostgreSQL hook to ignore "~/.psqlrc", whose settings can break
+   database dumping.
+ * #680: Add support for logging each log line as a JSON object via global "--log-json" flag.
+ * #682: Fix "source_directories_must_exist" option to expand globs and tildes in source directories.
+ * #684: Rename "master" development branch to "main" to use more inclusive language. You'll need to
+   update your development checkouts accordingly.
+ * #686: Add fish shell completion script so you can tab-complete on the borgmatic command-line. See
+   the documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/set-up-backups/#shell-completion
+ * #687: Fix borgmatic error when not finding the configuration schema for certain "pip install
+   --editable" development installs.
+ * #688: Fix archive checks being skipped even when particular archives haven't been checked
+   recently. This occurred when using multiple borgmatic configuration files with different
+   "archive_name_format"s, for instance.
+ * #691: Fix error in "borgmatic restore" action when the configured repository path is relative
+   instead of absolute.
+ * #694: Run "borgmatic borg" action without capturing output so interactive prompts and flags like
+   "--progress" still work.
+
+1.7.12
+ * #413: Add "log_file" context to command hooks so your scripts can consume the borgmatic log file.
+   See the documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/
+ * #666, #670: Fix error when running the "info" action with the "--match-archives" or "--archive"
+   flags. Also fix the "--match-archives"/"--archive" flags to correctly override the
+   "match_archives" configuration option for the "transfer", "list", "rlist", and "info" actions.
+ * #668: Fix error when running the "prune" action with both "archive_name_format" and "prefix"
+   options set.
+ * #672: Selectively shallow merge certain mappings or sequences when including configuration files.
+   See the documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/make-per-application-backups/#shallow-merge
+ * #672: Selectively omit list values when including configuration files. See the documentation for
+   more information:
+   https://torsion.org/borgmatic/docs/how-to/make-per-application-backups/#list-merge
+ * #673: View the results of configuration file merging via "validate-borgmatic-config --show" flag.
+   See the documentation for more information:
+   https://torsion.org/borgmatic/docs/how-to/make-per-application-backups/#debugging-includes
+ * Add optional support for running end-to-end tests and building documentation with rootless Podman
+   instead of Docker.
+
+1.7.11
+ * #479, #588: BREAKING: Automatically use the "archive_name_format" option to filter which archives
+   get used for borgmatic actions that operate on multiple archives. Override this behavior with the
+   new "match_archives" option in the storage section. This change is "breaking" in that it silently
+   changes which archives get considered for "rlist", "prune", "check", etc. See the documentation
+   for more information:
+   https://torsion.org/borgmatic/docs/how-to/make-per-application-backups/#archive-naming
+ * #479, #588: The "prefix" options have been deprecated in favor of the new "archive_name_format"
+   auto-matching behavior and the "match_archives" option.
+ * #658: Add "--log-file-format" flag for customizing the log message format. See the documentation
+   for more information:
+   https://torsion.org/borgmatic/docs/how-to/inspect-your-backups/#logging-to-file
+ * #662: Fix regression in which the "check_repositories" option failed to match repositories.
+ * #663: Fix regression in which the "transfer" action produced a traceback.
+ * Add spellchecking of source code during test runs.
+
+1.7.10
+ * #396: When a database command errors, display and log the error message instead of swallowing it.
+ * #501: Optionally error if a source directory does not exist via "source_directories_must_exist"
+   option in borgmatic's location configuration.
+ * #576: Add support for "file://" paths within "repositories" option.
+ * #612: Define and use custom constants in borgmatic configuration files. See the documentation for
+   more information:
+   https://torsion.org/borgmatic/docs/how-to/make-per-application-backups/#constant-interpolation
+ * #618: Add support for BORG_FILES_CACHE_TTL environment variable via "borg_files_cache_ttl" option
+   in borgmatic's storage configuration.
+ * #623: Fix confusing message when an error occurs running actions for a configuration file.
+ * #635: Add optional repository labels so you can select a repository via "--repository yourlabel"
+   at the command-line. See the configuration reference for more information:
+   https://torsion.org/borgmatic/docs/reference/configuration/
+ * #649: Add documentation on backing up a database running in a container:
+   https://torsion.org/borgmatic/docs/how-to/backup-your-databases/#containers
+ * #655: Fix error when databases are configured and a source directory doesn't exist.
+ * Add code style plugins to enforce use of Python f-strings and prevent single-letter variables.
+   To join in the pedantry, refresh your test environment with "tox --recreate".
+ * Rename scripts/run-full-dev-tests to scripts/run-end-to-end-dev-tests and make it run end-to-end
+   tests only. Continue using tox to run unit and integration tests.
+
+1.7.9
+ * #295: Add a SQLite database dump/restore hook.
+ * #304: Change the default action order when no actions are specified on the command-line to:
+   "create", "prune", "compact", "check". If you'd like to retain the old ordering ("prune" and
+   "compact" first), then specify actions explicitly on the command-line.
+ * #304: Run any command-line actions in the order specified instead of using a fixed ordering.
+ * #564: Add "--repository" flag to all actions where it makes sense, so you can run borgmatic on
+   a single configured repository instead of all of them.
+ * #628: Add a Healthchecks "log" state to send borgmatic logs to Healthchecks without signalling
+   success or failure.
+ * #647: Add "--strip-components all" feature on the "extract" action to remove leading path
+   components of files you extract. Must be used with the "--path" flag.
+ * Add support for Python 3.11.
+
 1.7.8
  * #620: With the "create" action and the "--list" ("--files") flag, only show excluded files at
    verbosity 2.
@@ -289,7 +797,7 @@
  * #398: Clarify canonical home of borgmatic in documentation.
  * #406: Clarify that spaces in path names should not be backslashed in path names.
  * #423: Fix error handling to error loudly when Borg gets killed due to running out of memory!
- * Fix build so as not to attempt to build and push documentation for a non-master branch.
+ * Fix build so as not to attempt to build and push documentation for a non-main branch.
  * "Fix" build failure with Alpine Edge by switching from Edge to Alpine 3.13.
  * Move #borgmatic IRC channel from Freenode to Libera Chat due to Freenode takeover drama.
    IRC connection info: https://torsion.org/borgmatic/#issues
@@ -352,7 +860,7 @@
    configuration schema descriptions.
 
 1.5.6
- * #292: Allow before_backup and similiar hooks to exit with a soft failure without altering the
+ * #292: Allow before_backup and similar hooks to exit with a soft failure without altering the
    monitoring status on Healthchecks or other providers. Support this by waiting to ping monitoring
    services with a "start" status until after before_* hooks finish. Failures in before_* hooks
    still trigger a monitoring "fail" status.
@@ -421,7 +929,7 @@
  * For "list" and "info" actions, show repository names even at verbosity 0.
 
 1.4.22
- * #276, #285: Disable colored output when "--json" flag is used, so as to produce valid JSON ouput.
+ * #276, #285: Disable colored output when "--json" flag is used, so as to produce valid JSON output.
  * After a backup of a database dump in directory format, properly remove the dump directory.
  * In "borgmatic --help", don't expand $HOME in listing of default "--config" paths.
 
@@ -793,7 +1301,7 @@
  * #77: Skip non-"*.yaml" config filenames in /etc/borgmatic.d/ so as not to parse backup files,
    editor swap files, etc.
  * #81: Document user-defined hooks run before/after backup, or on error.
- * Add code style guidelines to the documention.
+ * Add code style guidelines to the documentation.
 
 1.2.0
  * #61: Support for Borg --list option via borgmatic command-line to list all archives.

README.md

@@ -11,68 +11,72 @@ borgmatic is simple, configuration-driven backup software for servers and
 workstations. Protect your files with client-side encryption. Backup your
 databases too. Monitor it all with integrated third-party services.
 
-The canonical home of borgmatic is at <a href="https://torsion.org/borgmatic">https://torsion.org/borgmatic</a>.
+The canonical home of borgmatic is at <a href="https://torsion.org/borgmatic">https://torsion.org/borgmatic/</a>
 
 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:
-        - ssh://1234@usw-s001.rsync.net/./backups.borg
-        - ssh://k8pDxu32@k8pDxu32.repo.borgbase.com/./repo
-        - /var/lib/backups/local.borg
+# 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:
+    ping_url: 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
 
-<a href="https://www.postgresql.org/"><img src="docs/static/postgresql.png" alt="PostgreSQL" height="60px" style="margin-bottom:20px;"></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-<a href="https://www.mysql.com/"><img src="docs/static/mysql.png" alt="MySQL" height="60px" style="margin-bottom:20px;"></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-<a href="https://mariadb.com/"><img src="docs/static/mariadb.png" alt="MariaDB" height="60px" style="margin-bottom:20px;"></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-<a href="https://www.mongodb.com/"><img src="docs/static/mongodb.png" alt="MongoDB" height="60px" style="margin-bottom:20px;"></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-<a href="https://healthchecks.io/"><img src="docs/static/healthchecks.png" alt="Healthchecks" height="60px" style="margin-bottom:20px;"></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-<a href="https://cronitor.io/"><img src="docs/static/cronitor.png" alt="Cronitor" height="60px" style="margin-bottom:20px;"></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-<a href="https://cronhub.io/"><img src="docs/static/cronhub.png" alt="Cronhub" height="60px" style="margin-bottom:20px;"></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-<a href="https://www.pagerduty.com/"><img src="docs/static/pagerduty.png" alt="PagerDuty" height="60px" style="margin-bottom:20px;"></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-<a href="https://ntfy.sh/"><img src="docs/static/ntfy.png" alt="ntfy" height="60px" style="margin-bottom:20px;"></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-<a href="https://www.borgbase.com/?utm_source=borgmatic"><img src="docs/static/borgbase.png" alt="BorgBase" height="60px" style="margin-bottom:20px;"></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+<a href="https://www.postgresql.org/"><img src="docs/static/postgresql.png" alt="PostgreSQL" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
+<a href="https://www.mysql.com/"><img src="docs/static/mysql.png" alt="MySQL" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
+<a href="https://mariadb.com/"><img src="docs/static/mariadb.png" alt="MariaDB" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
+<a href="https://www.mongodb.com/"><img src="docs/static/mongodb.png" alt="MongoDB" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
+<a href="https://sqlite.org/"><img src="docs/static/sqlite.png" alt="SQLite" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
+<a href="https://openzfs.org/"><img src="docs/static/openzfs.png" alt="OpenZFS" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
+<a href="https://btrfs.readthedocs.io/"><img src="docs/static/btrfs.png" alt="Btrfs" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
+<a href="https://sourceware.org/lvm2/"><img src="docs/static/lvm.png" alt="LVM" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
+<a href="https://rclone.org"><img src="docs/static/rclone.png" alt="rclone" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
+<a href="https://healthchecks.io/"><img src="docs/static/healthchecks.png" alt="Healthchecks" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
+<a href="https://uptime.kuma.pet/"><img src="docs/static/uptimekuma.png" alt="Uptime Kuma" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
+<a href="https://cronitor.io/"><img src="docs/static/cronitor.png" alt="Cronitor" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
+<a href="https://cronhub.io/"><img src="docs/static/cronhub.png" alt="Cronhub" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
+<a href="https://www.pagerduty.com/"><img src="docs/static/pagerduty.png" alt="PagerDuty" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
+<a href="https://www.pushover.net/"><img src="docs/static/pushover.png" alt="Pushover" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
+<a href="https://ntfy.sh/"><img src="docs/static/ntfy.png" alt="ntfy" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
+<a href="https://grafana.com/oss/loki/"><img src="docs/static/loki.png" alt="Loki" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
+<a href="https://github.com/caronc/apprise/wiki"><img src="docs/static/apprise.png" alt="Apprise" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
+<a href="https://www.zabbix.com/"><img src="docs/static/zabbix.png" alt="Zabbix" height="40px" style="margin-bottom:20px; margin-right:20px;"></a>
+<a href="https://sentry.io/"><img src="docs/static/sentry.png" alt="Sentry" height="40px" style="margin-bottom:20px; margin-right:20px;"></a>
+<a href="https://www.borgbase.com/?utm_source=borgmatic"><img src="docs/static/borgbase.png" alt="BorgBase" height="60px" style="margin-bottom:20px; margin-right:20px;"></a>
 
 
 ## Getting started
@@ -80,8 +84,8 @@ borgmatic is powered by [Borg Backup](https://www.borgbackup.org/).
 Your first step is to [install and configure
 borgmatic](https://torsion.org/borgmatic/docs/how-to/set-up-backups/).
 
-For additional documentation, check out the links above for <a
-href="https://torsion.org/borgmatic/#documentation">borgmatic how-to and
+For additional documentation, check out the links above (left panel on wide screens)
+for <a href="https://torsion.org/borgmatic/#documentation">borgmatic how-to and
 reference guides</a>.
 
 
@@ -89,16 +93,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
 
@@ -119,10 +122,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
@@ -163,5 +163,10 @@ Also, please check out the [borgmatic development
 how-to](https://torsion.org/borgmatic/docs/how-to/develop-on-borgmatic/) for
 info on cloning source code, running tests, etc.
 
-<a href="https://build.torsion.org/borgmatic-collective/borgmatic" alt="build status">![Build Status](https://build.torsion.org/api/badges/borgmatic-collective/borgmatic/status.svg?ref=refs/heads/master)</a>
+### Recent contributors
 
+Thanks to all borgmatic contributors! There are multiple ways to contribute to
+this project, so the following includes those who have fixed bugs, contributed
+features, *or* filed tickets.
+
+{% include borgmatic/contributors.html %}

SECURITY.md

@@ -7,8 +7,8 @@ permalink: security-policy/index.html
 
 While we want to hear about security vulnerabilities in all versions of
 borgmatic, security fixes are only made to the most recently released version.
-It's simply not practical for our small volunteer effort to maintain multiple
-release branches and put out separate security patches for each.
+It's not practical for our small volunteer effort to maintain multiple release
+branches and put out separate security patches for each.
 
 ## Reporting a vulnerability
 

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

@@ -1,14 +1,20 @@
 import logging
 
 import borgmatic.borg.borg
-import borgmatic.borg.rlist
+import borgmatic.borg.repo_list
 import borgmatic.config.validate
 
 logger = logging.getLogger(__name__)
 
 
 def run_borg(
-    repository, storage, local_borg_version, borg_arguments, local_path, remote_path,
+    repository,
+    config,
+    local_borg_version,
+    borg_arguments,
+    global_arguments,
+    local_path,
+    remote_path,
 ):
     '''
     Run the "borg" action for the given repository.
@@ -16,18 +22,21 @@ def run_borg(
     if borg_arguments.repository is None or borgmatic.config.validate.repositories_match(
         repository, borg_arguments.repository
     ):
-        logger.info('{}: Running arbitrary Borg command'.format(repository))
-        archive_name = borgmatic.borg.rlist.resolve_archive_name(
-            repository,
+        logger.info(
+            f'{repository.get("label", repository["path"])}: Running arbitrary Borg command'
+        )
+        archive_name = borgmatic.borg.repo_list.resolve_archive_name(
+            repository['path'],
             borg_arguments.archive,
-            storage,
+            config,
             local_borg_version,
+            global_arguments,
             local_path,
             remote_path,
         )
         borgmatic.borg.borg.run_arbitrary_borg(
-            repository,
-            storage,
+            repository['path'],
+            config,
             local_borg_version,
             options=borg_arguments.options,
             archive=archive_name,

borgmatic/actions/break_lock.py

@@ -7,7 +7,13 @@ logger = logging.getLogger(__name__)
 
 
 def run_break_lock(
-    repository, storage, local_borg_version, break_lock_arguments, local_path, remote_path,
+    repository,
+    config,
+    local_borg_version,
+    break_lock_arguments,
+    global_arguments,
+    local_path,
+    remote_path,
 ):
     '''
     Run the "break-lock" action for the given repository.
@@ -15,7 +21,14 @@ def run_break_lock(
     if break_lock_arguments.repository is None or borgmatic.config.validate.repositories_match(
         repository, break_lock_arguments.repository
     ):
-        logger.info(f'{repository}: Breaking repository and cache locks')
-        borgmatic.borg.break_lock.break_lock(
-            repository, storage, local_borg_version, local_path=local_path, remote_path=remote_path,
+        logger.info(
+            f'{repository.get("label", repository["path"])}: Breaking repository and cache locks'
+        )
+        borgmatic.borg.break_lock.break_lock(
+            repository['path'],
+            config,
+            local_borg_version,
+            global_arguments,
+            local_path=local_path,
+            remote_path=remote_path,
         )

borgmatic/actions/change_passphrase.py

@@ -0,0 +1,38 @@
+import logging
+
+import borgmatic.borg.change_passphrase
+import borgmatic.config.validate
+
+logger = logging.getLogger(__name__)
+
+
+def run_change_passphrase(
+    repository,
+    config,
+    local_borg_version,
+    change_passphrase_arguments,
+    global_arguments,
+    local_path,
+    remote_path,
+):
+    '''
+    Run the "key change-passprhase" action for the given repository.
+    '''
+    if (
+        change_passphrase_arguments.repository is None
+        or borgmatic.config.validate.repositories_match(
+            repository, change_passphrase_arguments.repository
+        )
+    ):
+        logger.info(
+            f'{repository.get("label", repository["path"])}: Changing repository passphrase'
+        )
+        borgmatic.borg.change_passphrase.change_passphrase(
+            repository['path'],
+            config,
+            local_borg_version,
+            change_passphrase_arguments,
+            global_arguments,
+            local_path=local_path,
+            remote_path=remote_path,
+        )

borgmatic/actions/check.py

@@ -1,18 +1,692 @@
+import calendar
+import datetime
+import hashlib
+import itertools
 import logging
+import os
+import pathlib
+import random
+import shutil
 
+import borgmatic.actions.create
 import borgmatic.borg.check
+import borgmatic.borg.create
+import borgmatic.borg.environment
+import borgmatic.borg.extract
+import borgmatic.borg.list
+import borgmatic.borg.repo_list
+import borgmatic.borg.state
+import borgmatic.config.paths
+import borgmatic.config.validate
+import borgmatic.execute
 import borgmatic.hooks.command
 
+DEFAULT_CHECKS = (
+    {'name': 'repository', 'frequency': '1 month'},
+    {'name': 'archives', 'frequency': '1 month'},
+)
+
+
 logger = logging.getLogger(__name__)
 
 
+def parse_checks(config, only_checks=None):
+    '''
+    Given a configuration dict with a "checks" sequence of dicts and an optional list of override
+    checks, return a tuple of named checks to run.
+
+    For example, given a config of:
+
+        {'checks': ({'name': 'repository'}, {'name': 'archives'})}
+
+    This will be returned as:
+
+        ('repository', 'archives')
+
+    If no "checks" option is present in the config, return the DEFAULT_CHECKS. If a checks value
+    has a name of "disabled", return an empty tuple, meaning that no checks should be run.
+    '''
+    checks = only_checks or tuple(
+        check_config['name'] for check_config in (config.get('checks', None) or DEFAULT_CHECKS)
+    )
+    checks = tuple(check.lower() for check in checks)
+
+    if 'disabled' in checks:
+        logger.warning(
+            'The "disabled" value for the "checks" option is deprecated and will be removed from a future release; use "skip_actions" instead'
+        )
+        if len(checks) > 1:
+            logger.warning(
+                'Multiple checks are configured, but one of them is "disabled"; not running any checks'
+            )
+        return ()
+
+    return checks
+
+
+def parse_frequency(frequency):
+    '''
+    Given a frequency string with a number and a unit of time, return a corresponding
+    datetime.timedelta instance or None if the frequency is None or "always".
+
+    For instance, given "3 weeks", return datetime.timedelta(weeks=3)
+
+    Raise ValueError if the given frequency cannot be parsed.
+    '''
+    if not frequency:
+        return None
+
+    frequency = frequency.strip().lower()
+
+    if frequency == 'always':
+        return None
+
+    try:
+        number, time_unit = frequency.split(' ')
+        number = int(number)
+    except ValueError:
+        raise ValueError(f"Could not parse consistency check frequency '{frequency}'")
+
+    if not time_unit.endswith('s'):
+        time_unit += 's'
+
+    if time_unit == 'months':
+        number *= 30
+        time_unit = 'days'
+    elif time_unit == 'years':
+        number *= 365
+        time_unit = 'days'
+
+    try:
+        return datetime.timedelta(**{time_unit: number})
+    except TypeError:
+        raise ValueError(f"Could not parse consistency check frequency '{frequency}'")
+
+
+WEEKDAY_DAYS = calendar.day_name[0:5]
+WEEKEND_DAYS = calendar.day_name[5:7]
+
+
+def filter_checks_on_frequency(
+    config,
+    borg_repository_id,
+    checks,
+    force,
+    archives_check_id=None,
+    datetime_now=datetime.datetime.now,
+):
+    '''
+    Given a configuration dict with a "checks" sequence of dicts, a Borg repository ID, a sequence
+    of checks, whether to force checks to run, and an ID for the archives check potentially being
+    run (if any), filter down those checks based on the configured "frequency" for each check as
+    compared to its check time file.
+
+    In other words, a check whose check time file's timestamp is too new (based on the configured
+    frequency) will get cut from the returned sequence of checks. Example:
+
+    config = {
+        'checks': [
+            {
+                'name': 'archives',
+                'frequency': '2 weeks',
+            },
+        ]
+    }
+
+    When this function is called with that config and "archives" in checks, "archives" will get
+    filtered out of the returned result if its check time file is newer than 2 weeks old, indicating
+    that it's not yet time to run that check again.
+
+    Raise ValueError if a frequency cannot be parsed.
+    '''
+    if not checks:
+        return checks
+
+    filtered_checks = list(checks)
+
+    if force:
+        return tuple(filtered_checks)
+
+    for check_config in config.get('checks', DEFAULT_CHECKS):
+        check = check_config['name']
+        if checks and check not in checks:
+            continue
+
+        only_run_on = check_config.get('only_run_on')
+        if only_run_on:
+            # Use a dict instead of a set to preserve ordering.
+            days = dict.fromkeys(only_run_on)
+
+            if 'weekday' in days:
+                days = {
+                    **dict.fromkeys(day for day in days if day != 'weekday'),
+                    **dict.fromkeys(WEEKDAY_DAYS),
+                }
+            if 'weekend' in days:
+                days = {
+                    **dict.fromkeys(day for day in days if day != 'weekend'),
+                    **dict.fromkeys(WEEKEND_DAYS),
+                }
+
+            if calendar.day_name[datetime_now().weekday()] not in days:
+                logger.info(
+                    f"Skipping {check} check due to day of the week; check only runs on {'/'.join(days)} (use --force to check anyway)"
+                )
+                filtered_checks.remove(check)
+                continue
+
+        frequency_delta = parse_frequency(check_config.get('frequency'))
+        if not frequency_delta:
+            continue
+
+        check_time = probe_for_check_time(config, borg_repository_id, check, archives_check_id)
+        if not check_time:
+            continue
+
+        # If we've not yet reached the time when the frequency dictates we're ready for another
+        # check, skip this check.
+        if datetime_now() < check_time + frequency_delta:
+            remaining = check_time + frequency_delta - datetime_now()
+            logger.info(
+                f'Skipping {check} check due to configured frequency; {remaining} until next check (use --force to check anyway)'
+            )
+            filtered_checks.remove(check)
+
+    return tuple(filtered_checks)
+
+
+def make_archives_check_id(archive_filter_flags):
+    '''
+    Given a sequence of flags to filter archives, return a unique hash corresponding to those
+    particular flags. If there are no flags, return None.
+    '''
+    if not archive_filter_flags:
+        return None
+
+    return hashlib.sha256(' '.join(archive_filter_flags).encode()).hexdigest()
+
+
+def make_check_time_path(config, borg_repository_id, check_type, archives_check_id=None):
+    '''
+    Given a configuration dict, a Borg repository ID, the name of a check type ("repository",
+    "archives", etc.), and a unique hash of the archives filter flags, return a path for recording
+    that check's time (the time of that check last occurring).
+    '''
+    borgmatic_state_directory = borgmatic.config.paths.get_borgmatic_state_directory(config)
+
+    if check_type in ('archives', 'data'):
+        return os.path.join(
+            borgmatic_state_directory,
+            'checks',
+            borg_repository_id,
+            check_type,
+            archives_check_id if archives_check_id else 'all',
+        )
+
+    return os.path.join(
+        borgmatic_state_directory,
+        'checks',
+        borg_repository_id,
+        check_type,
+    )
+
+
+def write_check_time(path):  # pragma: no cover
+    '''
+    Record a check time of now as the modification time of the given path.
+    '''
+    logger.debug(f'Writing check time at {path}')
+
+    os.makedirs(os.path.dirname(path), mode=0o700, exist_ok=True)
+    pathlib.Path(path, mode=0o600).touch()
+
+
+def read_check_time(path):
+    '''
+    Return the check time based on the modification time of the given path. Return None if the path
+    doesn't exist.
+    '''
+    logger.debug(f'Reading check time from {path}')
+
+    try:
+        return datetime.datetime.fromtimestamp(os.stat(path).st_mtime)
+    except FileNotFoundError:
+        return None
+
+
+def probe_for_check_time(config, borg_repository_id, check, archives_check_id):
+    '''
+    Given a configuration dict, a Borg repository ID, the name of a check type ("repository",
+    "archives", etc.), and a unique hash of the archives filter flags, return the corresponding
+    check time or None if such a check time does not exist.
+
+    When the check type is "archives" or "data", this function probes two different paths to find
+    the check time, e.g.:
+
+      ~/.borgmatic/checks/1234567890/archives/9876543210
+      ~/.borgmatic/checks/1234567890/archives/all
+
+    ... and returns the maximum modification time of the files found (if any). The first path
+    represents a more specific archives check time (a check on a subset of archives), and the second
+    is a fallback to the last "all" archives check.
+
+    For other check types, this function reads from a single check time path, e.g.:
+
+      ~/.borgmatic/checks/1234567890/repository
+    '''
+    check_times = (
+        read_check_time(group[0])
+        for group in itertools.groupby(
+            (
+                make_check_time_path(config, borg_repository_id, check, archives_check_id),
+                make_check_time_path(config, borg_repository_id, check),
+            )
+        )
+    )
+
+    try:
+        return max(check_time for check_time in check_times if check_time)
+    except ValueError:
+        return None
+
+
+def upgrade_check_times(config, borg_repository_id):
+    '''
+    Given a configuration dict and a Borg repository ID, upgrade any corresponding check times on
+    disk from old-style paths to new-style paths.
+
+    One upgrade performed is moving the checks directory from:
+
+      {borgmatic_source_directory}/checks (e.g., ~/.borgmatic/checks)
+
+    to:
+
+      {borgmatic_state_directory}/checks (e.g. ~/.local/state/borgmatic)
+
+    Another upgrade is renaming an archive or data check path that looks like:
+
+      {borgmatic_state_directory}/checks/1234567890/archives
+
+    to:
+
+      {borgmatic_state_directory}/checks/1234567890/archives/all
+    '''
+    borgmatic_source_checks_path = os.path.join(
+        borgmatic.config.paths.get_borgmatic_source_directory(config), 'checks'
+    )
+    borgmatic_state_path = borgmatic.config.paths.get_borgmatic_state_directory(config)
+    borgmatic_state_checks_path = os.path.join(borgmatic_state_path, 'checks')
+
+    if os.path.exists(borgmatic_source_checks_path) and not os.path.exists(
+        borgmatic_state_checks_path
+    ):
+        logger.debug(
+            f'Upgrading archives check times directory from {borgmatic_source_checks_path} to {borgmatic_state_checks_path}'
+        )
+        os.makedirs(borgmatic_state_path, mode=0o700, exist_ok=True)
+        shutil.move(borgmatic_source_checks_path, borgmatic_state_checks_path)
+
+    for check_type in ('archives', 'data'):
+        new_path = make_check_time_path(config, borg_repository_id, check_type, 'all')
+        old_path = os.path.dirname(new_path)
+        temporary_path = f'{old_path}.temp'
+
+        if not os.path.isfile(old_path) and not os.path.isfile(temporary_path):
+            continue
+
+        logger.debug(f'Upgrading archives check time file from {old_path} to {new_path}')
+
+        try:
+            shutil.move(old_path, temporary_path)
+        except FileNotFoundError:
+            pass
+
+        os.mkdir(old_path)
+        shutil.move(temporary_path, new_path)
+
+
+def collect_spot_check_source_paths(
+    repository,
+    config,
+    local_borg_version,
+    global_arguments,
+    local_path,
+    remote_path,
+    borgmatic_runtime_directory,
+):
+    '''
+    Given a repository configuration dict, a configuration dict, the local Borg version, global
+    arguments as an argparse.Namespace instance, the local Borg path, and the remote Borg path,
+    collect the source paths that Borg would use in an actual create (but only include files).
+    '''
+    stream_processes = any(
+        borgmatic.hooks.dispatch.call_hooks(
+            'use_streaming',
+            config,
+            repository['path'],
+            borgmatic.hooks.dispatch.Hook_type.DATA_SOURCE,
+        ).values()
+    )
+    working_directory = borgmatic.config.paths.get_working_directory(config)
+
+    (create_flags, create_positional_arguments, pattern_file) = (
+        borgmatic.borg.create.make_base_create_command(
+            dry_run=True,
+            repository_path=repository['path'],
+            config=config,
+            patterns=borgmatic.actions.create.process_patterns(
+                borgmatic.actions.create.collect_patterns(config),
+                working_directory,
+            ),
+            local_borg_version=local_borg_version,
+            global_arguments=global_arguments,
+            borgmatic_runtime_directory=borgmatic_runtime_directory,
+            local_path=local_path,
+            remote_path=remote_path,
+            list_files=True,
+            stream_processes=stream_processes,
+        )
+    )
+    borg_environment = borgmatic.borg.environment.make_environment(config)
+    working_directory = borgmatic.config.paths.get_working_directory(config)
+
+    paths_output = borgmatic.execute.execute_command_and_capture_output(
+        create_flags + create_positional_arguments,
+        capture_stderr=True,
+        extra_environment=borg_environment,
+        working_directory=working_directory,
+        borg_local_path=local_path,
+        borg_exit_codes=config.get('borg_exit_codes'),
+    )
+
+    paths = tuple(
+        path_line.split(' ', 1)[1]
+        for path_line in paths_output.splitlines()
+        if path_line and path_line.startswith('- ') or path_line.startswith('+ ')
+    )
+
+    return tuple(
+        path for path in paths if os.path.isfile(os.path.join(working_directory or '', path))
+    )
+
+
+BORG_DIRECTORY_FILE_TYPE = 'd'
+BORG_PIPE_FILE_TYPE = 'p'
+
+
+def collect_spot_check_archive_paths(
+    repository,
+    archive,
+    config,
+    local_borg_version,
+    global_arguments,
+    local_path,
+    remote_path,
+    borgmatic_runtime_directory,
+):
+    '''
+    Given a repository configuration dict, the name of the latest archive, a configuration dict, the
+    local Borg version, global arguments as an argparse.Namespace instance, the local Borg path, the
+    remote Borg path, and the borgmatic runtime directory, collect the paths from the given archive
+    (but only include files and symlinks and exclude borgmatic runtime directories).
+
+    These paths do not have a leading slash, as that's how Borg stores them. As a result, we don't
+    know whether they came from absolute or relative source directories.
+    '''
+    borgmatic_source_directory = borgmatic.config.paths.get_borgmatic_source_directory(config)
+
+    return tuple(
+        path
+        for line in borgmatic.borg.list.capture_archive_listing(
+            repository['path'],
+            archive,
+            config,
+            local_borg_version,
+            global_arguments,
+            path_format='{type} {path}{NL}',  # noqa: FS003
+            local_path=local_path,
+            remote_path=remote_path,
+        )
+        for (file_type, path) in (line.split(' ', 1),)
+        if file_type not in (BORG_DIRECTORY_FILE_TYPE, BORG_PIPE_FILE_TYPE)
+        if pathlib.Path('borgmatic') not in pathlib.Path(path).parents
+        if pathlib.Path(borgmatic_source_directory.lstrip(os.path.sep))
+        not in pathlib.Path(path).parents
+        if pathlib.Path(borgmatic_runtime_directory.lstrip(os.path.sep))
+        not in pathlib.Path(path).parents
+    )
+
+
+SAMPLE_PATHS_SUBSET_COUNT = 10000
+
+
+def compare_spot_check_hashes(
+    repository,
+    archive,
+    config,
+    local_borg_version,
+    global_arguments,
+    local_path,
+    remote_path,
+    log_prefix,
+    source_paths,
+):
+    '''
+    Given a repository configuration dict, the name of the latest archive, a configuration dict, the
+    local Borg version, global arguments as an argparse.Namespace instance, the local Borg path, the
+    remote Borg path, a log label, and spot check source paths, compare the hashes for a sampling of
+    the source paths with hashes from corresponding paths in the given archive. Return a sequence of
+    the paths that fail that hash comparison.
+    '''
+    # Based on the configured sample percentage, come up with a list of random sample files from the
+    # source directories.
+    spot_check_config = next(check for check in config['checks'] if check['name'] == 'spot')
+    sample_count = max(
+        int(len(source_paths) * (min(spot_check_config['data_sample_percentage'], 100) / 100)), 1
+    )
+    source_sample_paths = tuple(random.sample(source_paths, sample_count))
+    working_directory = borgmatic.config.paths.get_working_directory(config)
+    existing_source_sample_paths = {
+        source_path
+        for source_path in source_sample_paths
+        if os.path.exists(os.path.join(working_directory or '', source_path))
+    }
+    logger.debug(
+        f'{log_prefix}: Sampling {sample_count} source paths (~{spot_check_config["data_sample_percentage"]}%) for spot check'
+    )
+
+    source_sample_paths_iterator = iter(source_sample_paths)
+    source_hashes = {}
+    archive_hashes = {}
+
+    # Only hash a few thousand files at a time (a subset of the total paths) to avoid an "Argument
+    # list too long" shell error.
+    while True:
+        # Hash each file in the sample paths (if it exists).
+        source_sample_paths_subset = tuple(
+            itertools.islice(source_sample_paths_iterator, SAMPLE_PATHS_SUBSET_COUNT)
+        )
+        if not source_sample_paths_subset:
+            break
+
+        hash_output = borgmatic.execute.execute_command_and_capture_output(
+            (spot_check_config.get('xxh64sum_command', 'xxh64sum'),)
+            + tuple(
+                path for path in source_sample_paths_subset if path in existing_source_sample_paths
+            ),
+            working_directory=working_directory,
+        )
+
+        source_hashes.update(
+            **dict(
+                (reversed(line.split('  ', 1)) for line in hash_output.splitlines()),
+                # Represent non-existent files as having empty hashes so the comparison below still works.
+                **{
+                    path: ''
+                    for path in source_sample_paths_subset
+                    if path not in existing_source_sample_paths
+                },
+            )
+        )
+
+        # Get the hash for each file in the archive.
+        archive_hashes.update(
+            **dict(
+                reversed(line.split(' ', 1))
+                for line in borgmatic.borg.list.capture_archive_listing(
+                    repository['path'],
+                    archive,
+                    config,
+                    local_borg_version,
+                    global_arguments,
+                    list_paths=source_sample_paths_subset,
+                    path_format='{xxh64} {path}{NL}',  # noqa: FS003
+                    local_path=local_path,
+                    remote_path=remote_path,
+                )
+                if line
+            )
+        )
+
+    # Compare the source hashes with the archive hashes to see how many match.
+    failing_paths = []
+
+    for path, source_hash in source_hashes.items():
+        archive_hash = archive_hashes.get(path.lstrip(os.path.sep))
+
+        if archive_hash is not None and archive_hash == source_hash:
+            continue
+
+        failing_paths.append(path)
+
+    return tuple(failing_paths)
+
+
+def spot_check(
+    repository,
+    config,
+    local_borg_version,
+    global_arguments,
+    local_path,
+    remote_path,
+    borgmatic_runtime_directory,
+):
+    '''
+    Given a repository dict, a loaded configuration dict, the local Borg version, global arguments
+    as an argparse.Namespace instance, the local Borg path, the remote Borg path, and the borgmatic
+    runtime directory, perform a spot check for the latest archive in the given repository.
+
+    A spot check compares file counts and also the hashes for a random sampling of source files on
+    disk to those stored in the latest archive. If any differences are beyond configured tolerances,
+    then the check fails.
+    '''
+    log_prefix = f'{repository.get("label", repository["path"])}'
+    logger.debug(f'{log_prefix}: Running spot check')
+
+    try:
+        spot_check_config = next(
+            check for check in config.get('checks', ()) if check.get('name') == 'spot'
+        )
+    except StopIteration:
+        raise ValueError('Cannot run spot check because it is unconfigured')
+
+    if spot_check_config['data_tolerance_percentage'] > spot_check_config['data_sample_percentage']:
+        raise ValueError(
+            'The data_tolerance_percentage must be less than or equal to the data_sample_percentage'
+        )
+
+    source_paths = collect_spot_check_source_paths(
+        repository,
+        config,
+        local_borg_version,
+        global_arguments,
+        local_path,
+        remote_path,
+        borgmatic_runtime_directory,
+    )
+    logger.debug(f'{log_prefix}: {len(source_paths)} total source paths for spot check')
+
+    archive = borgmatic.borg.repo_list.resolve_archive_name(
+        repository['path'],
+        'latest',
+        config,
+        local_borg_version,
+        global_arguments,
+        local_path,
+        remote_path,
+    )
+    logger.debug(f'{log_prefix}: Using archive {archive} for spot check')
+
+    archive_paths = collect_spot_check_archive_paths(
+        repository,
+        archive,
+        config,
+        local_borg_version,
+        global_arguments,
+        local_path,
+        remote_path,
+        borgmatic_runtime_directory,
+    )
+    logger.debug(f'{log_prefix}: {len(archive_paths)} total archive paths for spot check')
+
+    if len(source_paths) == 0:
+        logger.debug(
+            f'{log_prefix}: Paths in latest archive but not source paths: {", ".join(set(archive_paths)) or "none"}'
+        )
+        raise ValueError(
+            'Spot check failed: There are no source paths to compare against the archive'
+        )
+
+    # Calculate the percentage delta between the source paths count and the archive paths count, and
+    # compare that delta to the configured count tolerance percentage.
+    count_delta_percentage = abs(len(source_paths) - len(archive_paths)) / len(source_paths) * 100
+
+    if count_delta_percentage > spot_check_config['count_tolerance_percentage']:
+        rootless_source_paths = set(path.lstrip(os.path.sep) for path in source_paths)
+        logger.debug(
+            f'{log_prefix}: Paths in source paths but not latest archive: {", ".join(rootless_source_paths - set(archive_paths)) or "none"}'
+        )
+        logger.debug(
+            f'{log_prefix}: Paths in latest archive but not source paths: {", ".join(set(archive_paths) - rootless_source_paths) or "none"}'
+        )
+        raise ValueError(
+            f'Spot check failed: {count_delta_percentage:.2f}% file count delta between source paths and latest archive (tolerance is {spot_check_config["count_tolerance_percentage"]}%)'
+        )
+
+    failing_paths = compare_spot_check_hashes(
+        repository,
+        archive,
+        config,
+        local_borg_version,
+        global_arguments,
+        local_path,
+        remote_path,
+        log_prefix,
+        source_paths,
+    )
+
+    # Error if the percentage of failing hashes exceeds the configured tolerance percentage.
+    logger.debug(f'{log_prefix}: {len(failing_paths)} non-matching spot check hashes')
+    data_tolerance_percentage = spot_check_config['data_tolerance_percentage']
+    failing_percentage = (len(failing_paths) / len(source_paths)) * 100
+
+    if failing_percentage > data_tolerance_percentage:
+        logger.debug(
+            f'{log_prefix}: Source paths with data not matching the latest archive: {", ".join(failing_paths)}'
+        )
+        raise ValueError(
+            f'Spot check failed: {failing_percentage:.2f}% of source paths with data not matching the latest archive (tolerance is {data_tolerance_percentage}%)'
+        )
+
+    logger.info(
+        f'{log_prefix}: Spot check passed with a {count_delta_percentage:.2f}% file count delta and a {failing_percentage:.2f}% file data delta'
+    )
+
+
 def run_check(
     config_filename,
     repository,
-    location,
-    storage,
-    consistency,
-    hooks,
+    config,
     hook_context,
     local_borg_version,
     check_arguments,
@@ -22,32 +696,94 @@ def run_check(
 ):
     '''
     Run the "check" action for the given repository.
+
+    Raise ValueError if the Borg repository ID cannot be determined.
     '''
+    if check_arguments.repository and not borgmatic.config.validate.repositories_match(
+        repository, check_arguments.repository
+    ):
+        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,
         **hook_context,
     )
-    logger.info('{}: Running consistency checks'.format(repository))
-    borgmatic.borg.check.check_archives(
-        repository,
-        location,
-        storage,
-        consistency,
+
+    log_prefix = repository.get('label', repository['path'])
+    logger.info(f'{log_prefix}: Running consistency checks')
+
+    repository_id = borgmatic.borg.check.get_repository_id(
+        repository['path'],
+        config,
         local_borg_version,
+        global_arguments,
         local_path=local_path,
         remote_path=remote_path,
-        progress=check_arguments.progress,
-        repair=check_arguments.repair,
-        only_checks=check_arguments.only,
-        force=check_arguments.force,
     )
+    upgrade_check_times(config, repository_id)
+    configured_checks = parse_checks(config, check_arguments.only_checks)
+    archive_filter_flags = borgmatic.borg.check.make_archive_filter_flags(
+        local_borg_version, config, configured_checks, check_arguments
+    )
+    archives_check_id = make_archives_check_id(archive_filter_flags)
+    checks = filter_checks_on_frequency(
+        config,
+        repository_id,
+        configured_checks,
+        check_arguments.force,
+        archives_check_id,
+    )
+    borg_specific_checks = set(checks).intersection({'repository', 'archives', 'data'})
+
+    if borg_specific_checks:
+        borgmatic.borg.check.check_archives(
+            repository['path'],
+            config,
+            local_borg_version,
+            check_arguments,
+            global_arguments,
+            borg_specific_checks,
+            archive_filter_flags,
+            local_path=local_path,
+            remote_path=remote_path,
+        )
+        for check in borg_specific_checks:
+            write_check_time(make_check_time_path(config, repository_id, check, archives_check_id))
+
+    if 'extract' in checks:
+        borgmatic.borg.extract.extract_last_archive_dry_run(
+            config,
+            local_borg_version,
+            global_arguments,
+            repository['path'],
+            config.get('lock_wait'),
+            local_path,
+            remote_path,
+        )
+        write_check_time(make_check_time_path(config, repository_id, 'extract'))
+
+    if 'spot' in checks:
+        with borgmatic.config.paths.Runtime_directory(
+            config, log_prefix
+        ) as borgmatic_runtime_directory:
+            spot_check(
+                repository,
+                config,
+                local_borg_version,
+                global_arguments,
+                local_path,
+                remote_path,
+                borgmatic_runtime_directory,
+            )
+        write_check_time(make_check_time_path(config, repository_id, 'spot'))
+
     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

@@ -2,6 +2,7 @@ import logging
 
 import borgmatic.borg.compact
 import borgmatic.borg.feature
+import borgmatic.config.validate
 import borgmatic.hooks.command
 
 logger = logging.getLogger(__name__)
@@ -10,9 +11,7 @@ logger = logging.getLogger(__name__)
 def run_compact(
     config_filename,
     repository,
-    storage,
-    retention,
-    hooks,
+    config,
     hook_context,
     local_borg_version,
     compact_arguments,
@@ -24,21 +23,29 @@ def run_compact(
     '''
     Run the "compact" action for the given repository.
     '''
+    if compact_arguments.repository and not borgmatic.config.validate.repositories_match(
+        repository, compact_arguments.repository
+    ):
+        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,
         **hook_context,
     )
     if borgmatic.borg.feature.available(borgmatic.borg.feature.Feature.COMPACT, local_borg_version):
-        logger.info('{}: Compacting segments{}'.format(repository, dry_run_label))
+        logger.info(
+            f'{repository.get("label", repository["path"])}: Compacting segments{dry_run_label}'
+        )
         borgmatic.borg.compact.compact_segments(
             global_arguments.dry_run,
-            repository,
-            storage,
+            repository['path'],
+            config,
             local_borg_version,
+            global_arguments,
             local_path=local_path,
             remote_path=remote_path,
             progress=compact_arguments.progress,
@@ -46,10 +53,12 @@ def run_compact(
             threshold=compact_arguments.threshold,
         )
     else:  # pragma: nocover
-        logger.info('{}: Skipping compact (only available/needed in Borg 1.2+)'.format(repository))
+        logger.info(
+            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,132 @@
+import json
+import logging
+import os
+
+import borgmatic.borg.extract
+import borgmatic.borg.repo_list
+import borgmatic.config.paths
+import borgmatic.config.validate
+import borgmatic.hooks.command
+
+logger = logging.getLogger(__name__)
+
+
+def make_bootstrap_config(bootstrap_arguments):
+    '''
+    Given the bootstrap arguments as an argparse.Namespace, return a corresponding config dict.
+    '''
+    return {
+        'ssh_command': bootstrap_arguments.ssh_command,
+        # In case the repo has been moved or is accessed from a different path at the point of
+        # bootstrapping.
+        'relocated_repo_access_is_ok': True,
+    }
+
+
+def get_config_paths(archive_name, bootstrap_arguments, global_arguments, local_borg_version):
+    '''
+    Given an archive name, the bootstrap arguments as an argparse.Namespace (containing the
+    repository and archive name, Borg local path, Borg remote path, borgmatic runtime directory,
+    borgmatic source directory, destination directory, and whether to strip components), the global
+    arguments as an argparse.Namespace (containing the dry run flag and the local borg version),
+    return the config paths from the manifest.json file in the borgmatic source directory or runtime
+    directory after extracting it from the repository archive.
+
+    Raise ValueError if the manifest JSON is missing, can't be decoded, or doesn't contain the
+    expected configuration path data.
+    '''
+    borgmatic_source_directory = borgmatic.config.paths.get_borgmatic_source_directory(
+        {'borgmatic_source_directory': bootstrap_arguments.borgmatic_source_directory}
+    )
+    config = make_bootstrap_config(bootstrap_arguments)
+
+    # Probe for the manifest file in multiple locations, as the default location has moved to the
+    # borgmatic runtime directory (which gets stored as just "/borgmatic" with Borg 1.4+). But we
+    # still want to support reading the manifest from previously created archives as well.
+    with borgmatic.config.paths.Runtime_directory(
+        {'user_runtime_directory': bootstrap_arguments.user_runtime_directory},
+        bootstrap_arguments.repository,
+    ) as borgmatic_runtime_directory:
+        for base_directory in (
+            'borgmatic',
+            borgmatic.config.paths.make_runtime_directory_glob(borgmatic_runtime_directory),
+            borgmatic_source_directory,
+        ):
+            borgmatic_manifest_path = 'sh:' + os.path.join(
+                base_directory, 'bootstrap', 'manifest.json'
+            )
+
+            extract_process = borgmatic.borg.extract.extract_archive(
+                global_arguments.dry_run,
+                bootstrap_arguments.repository,
+                archive_name,
+                [borgmatic_manifest_path],
+                config,
+                local_borg_version,
+                global_arguments,
+                local_path=bootstrap_arguments.local_path,
+                remote_path=bootstrap_arguments.remote_path,
+                extract_to_stdout=True,
+            )
+            manifest_json = extract_process.stdout.read()
+
+            if manifest_json:
+                break
+        else:
+            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.
+    '''
+    config = make_bootstrap_config(bootstrap_arguments)
+    archive_name = borgmatic.borg.repo_list.resolve_archive_name(
+        bootstrap_arguments.repository,
+        bootstrap_arguments.archive,
+        config,
+        local_borg_version,
+        global_arguments,
+        local_path=bootstrap_arguments.local_path,
+        remote_path=bootstrap_arguments.remote_path,
+    )
+    manifest_config_paths = get_config_paths(
+        archive_name, 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,
+        archive_name,
+        [config_path.lstrip(os.path.sep) for config_path in manifest_config_paths],
+        config,
+        local_borg_version,
+        global_arguments,
+        local_path=bootstrap_arguments.local_path,
+        remote_path=bootstrap_arguments.remote_path,
+        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,20 +1,261 @@
-import json
+import glob
+import itertools
 import logging
+import os
+import pathlib
 
+import borgmatic.actions.json
 import borgmatic.borg.create