diff --git a/borgmatic/config/schema.yaml b/borgmatic/config/schema.yaml
index 24609f40..31129af2 100644
--- a/borgmatic/config/schema.yaml
+++ b/borgmatic/config/schema.yaml
@@ -961,8 +961,8 @@ properties:
- everything
- dump_data_sources
description: |
- Name for the point in borgmatic's execution before
- which the commands should be run (required if
+ Name for the point in borgmatic's execution that
+ the commands should be run before (required if
"after" isn't set):
* "action" runs before each action for each
repository.
@@ -1039,8 +1039,8 @@ properties:
- error
- dump_data_sources
description: |
- Name for the point in borgmatic's execution after
- which the commands should be run (required if
+ Name for the point in borgmatic's execution that
+ the commands should be run after (required if
"before" isn't set):
* "action" runs after each action for each
repository.
diff --git a/docs/how-to/add-preparation-and-cleanup-steps-to-backups.md b/docs/how-to/add-preparation-and-cleanup-steps-to-backups.md
index aa0fbcfb..d6ea1e06 100644
--- a/docs/how-to/add-preparation-and-cleanup-steps-to-backups.md
+++ b/docs/how-to/add-preparation-and-cleanup-steps-to-backups.md
@@ -17,7 +17,97 @@ But if you're looking to backup a database, it's probably easier to use the
feature](https://torsion.org/borgmatic/docs/how-to/backup-your-databases/)
instead.
-You can specify `before_backup` hooks to perform preparation steps before
+New in version 1.9.14 You can
+configure command hooks via a list of `commands:` in your borgmatic
+configuration file. For example:
+
+```yaml
+commands:
+ - before: action
+ when:
+ - create
+ run:
+ - echo "Before create!"
+ - after: action
+ when:
+ - create
+ - prune
+ run:
+ - echo "After create and/or prune!"
+```
+
+If A `run:` command contains a special YAML character such as a colon, you may
+need to quote the entire string (or use a [multiline
+string](https://yaml-multiline.info/)) to avoid an error:
+
+```yaml
+commands:
+ - before: action
+ when:
+ - create
+ run:
+ - "echo Backup: start"
+```
+
+Each command has the following options:
+
+ * `before` or `after`: Name for the point in borgmatic's execution that the commands should be run before/after, one of:
+ * `action` runs before each action for each repository. (Replaces the deprecated `before_create`, `after_prune`, etc.)
+ * `repository` runs before/after all actions for each repository. (Replaces the deprecated `before_actions`/`after_actions`.)
+ * `configuration` runs before/after all actions and repositories in the current configuration file.
+ * `everything` runs before/after all configuration files. (Replaces the deprecated `before_everything`/`after_everything`.)
+ * `when`: List of actions for which the commands will be run. Defaults to running for all actions.
+ * `run`: List of one or more shell commands or scripts to run when this command hook is triggered.
+
+There's also another command hook that works a little differently:
+
+```yaml
+commands:
+ - before: dump_data_sources
+ hooks:
+ - postgresql
+ run:
+ - echo "Right before the PostgreSQL database dump!"
+```
+
+This command hook has the following options:
+
+ * `before` or `after`: `dump_data_sources`
+ * `hooks`: List of names of other hooks that this command hook applies to. Defaults to all hooks of the relevant type.
+ * `run`: List of one or more shell commands or scripts to run when this command hook is triggered.
+
+
+### Order of execution
+
+Here's a way of visualizing how all of these command hooks slot into borgmatic's
+execution.
+
+Let's say you've got a borgmatic configuration file with a configured
+repository. And suppose you configure several command hooks and then run
+borgmatic for the `create` and `prune` actions. Here's the order of execution:
+
+ * Trigger `before: everything` (from all configuration files).
+ * Trigger `before: configuration` (from the first configuration file).
+ * Trigger `before: repository` (for the first repository).
+ * Trigger `before: action` for `create`.
+ * Run the `create` action.
+ * Trigger `after: action` for `create`.
+ * Trigger `before: action` for `prune`.
+ * Run the `prune` action.
+ * Trigger `after: action` for `prune`.
+ * Trigger `after: repository` (for the first repository).
+ * Trigger `after: configuration` (from the first configuration file).
+ * Trigger `after: everything` (from all configuration files).
+
+You can imagine how this would be extended to multiple repositories and/or
+configuration files.
+
+
+### Deprecated command hooks
+
+Prior to version 1.9.14 The
+command hooks worked a little differently. In these older versions of borgmatic,
+you can specify `before_backup` hooks to perform preparation steps before
running backups and specify `after_backup` hooks to perform cleanup steps
afterwards. Here's an example: