Factor out command hook reference documentation.

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

@@ -72,69 +72,9 @@ commands:
           - echo "After successful create!"
 ```
 
-Each command in the `commands:` list has the following options:
-
- * `before` or `after`: Name for the point in borgmatic's execution that the commands should be run before or after, one of:
-    * `action` runs before or after each action for each repository. This replaces the deprecated `before_create`, `after_prune`, etc.
-    * `repository` runs before or after all actions for each repository. This replaces the deprecated `before_actions` and `after_actions`.
-    * `configuration` runs before or after all actions and repositories in the current configuration file.
-    * `everything` runs before or after all configuration files. Errors here do not trigger `error` hooks or the `fail` state in monitoring hooks. This replaces the deprecated `before_everything` and `after_everything`.
-    * `error` runs after an error occurs—and it's only available for `after`. This replaces the deprecated `on_error` hook.
- * `when`: Only trigger the hook when borgmatic is run with particular actions (`create`, `prune`, etc.) listed here. Defaults to running for all actions.
- * `states`: <span class="minilink minilink-addedin">New in version 2.0.3</span> Only trigger the hook if borgmatic encounters one of the states (execution results) listed here. This state is evaluated only for the scope of the configured `action`, `repository`, etc., rather than for the entire borgmatic run. Only available for `after` hooks. Defaults to running the hook for all states. One or more of:
-    * `finish`: No errors occurred.
-    * `fail`: An error occurred.
- * `run`: List of one or more shell commands or scripts to run when this command hook is triggered.
-
-When command hooks run, they respect the `working_directory` option if it is
-configured, meaning that the hook commands are run in that directory.
-
-<span class="minilink minilink-addedin">New in version 2.0.4</span>If the exact
-same `everything` command hook is present in multiple configuration files,
-borgmatic only runs it once.
-
-borgmatic's `--repository` flag does not impact which command hooks get run. But
-you can use the `--config` flag to limit the configuration files (and thus
-command hooks) used.
-
-
-### 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:
-
- * Run `before: everything` hooks (from all configuration files).
-    * Run `before: configuration` hooks (from the first configuration file).
-        * Run `before: repository` hooks (for the first repository).
-            * Run `before: action` hooks for `create`.
-            * Actually run the `create` action (e.g. `borg create`).
-            * Run `after: action` hooks for `create`.
-            * Run `before: action` hooks for `prune`.
-            * Actually run the `prune` action (e.g. `borg prune`).
-            * Run `after: action` hooks for `prune`.
-        * Run `after: repository` hooks (for the first repository).
-    * Run `after: configuration` hooks (from the first configuration file).
-    * Run `after: error` hooks (if an error occurs).
- * Run `after: everything` hooks (from all configuration files).
-
-This same order of execution extends to multiple repositories and/or
-configuration files.
-
-Based on the above, you can see the difference between, say, an `after: action`
-hook with `states: [fail]` and an `after: error` hook. The `after: action hook`
-runs immediately after the create action fails for a particular repository—so
-before any subsequent actions for that repository or other repositories even
-have a chance to run. Whereas the `after: error` hook doesn't run until all
-actions for—and repositories in—a configuration file have had a chance to
-execute.
-
-And if there are multiple hooks defined for a particular step (e.g. `before:
-action` for `create`), then those hooks are run in the order they're defined in
-configuration.
+See the [command hooks
+documentation](https://torsion.org/borgmatic/reference/configuration/command-hooks/)
+for additional details about how to configure command hooks.
 
 
 ### Deprecated command hooks
@@ -245,77 +185,6 @@ borgmatic does not run `on_error` hooks if an error occurs within a
 `before_everything` or `after_everything` hook.
 
 
-## Variable interpolation
-
-The command action hooks support interpolating particular runtime variables into
-the commands that are run. Here's are a couple examples that assume you provide
-separate shell scripts:
-
-```yaml
-commands:
-    - after: action
-      when: [prune]
-      run:
-          - record-prune.sh {configuration_filename} {repository}
-    - after: error
-      when: [create]
-      run:
-          - send-text-message.sh {configuration_filename} {repository}
-```
-
-In this example, when the hook is triggered, borgmatic interpolates runtime
-values into each hook command: the borgmatic configuration filename and the
-paths of the current Borg repository.
-
-Here's the full set of supported variables you can use here:
-
- * `configuration_filename`: borgmatic configuration filename in which the
-   hook was defined
- * `log_file`
-   <span class="minilink minilink-addedin">New in version 1.7.12</span>:
-   path of the borgmatic log file, only set when the `--log-file` flag is used
- * `repository`: path of the current repository as configured in the current
-   borgmatic configuration file, if applicable to the current hook
- * `repository_label` <span class="minilink minilink-addedin">New in version
-   1.8.12</span>: label of the current repository as configured in the current
-   borgmatic configuration file, if applicable to the current hook
- * `error`: the error message itself, only applies to `error` hooks
- * `output`: output of the command that failed, only applies to `error` hooks
-   (may be blank if an error occurred without running a command)
-
-Not all command hooks support all variables. For instance, the `everything` and
-`configuration` hooks don't support repository variables because those hooks
-don't run in the context of a single repository. But the deprecated command
-hooks (`before_backup`, `on_error`, etc.) do generally support variable
-interpolation.
-
-borgmatic automatically escapes these interpolated values to prevent shell
-injection attacks. One implication is that you shouldn't wrap the interpolated
-values in your own quotes, as that will interfere with the quoting performed by
-borgmatic and result in your command receiving incorrect arguments. For
-instance, this won't work:
-
-```yaml
-commands:
-    - after: error
-      run:
-          # Don't do this! It won't work, as the {error} value is already quoted.
-          - send-text-message.sh "Uh oh: {error}"
-```
-
-Do this instead:
-
-```yaml
-commands:
-    - after: error
-      run:
-          - send-text-message.sh {error}
-```
-
-Note that you can also interpolate [arbitrary environment
-variables](https://torsion.org/borgmatic/how-to/provide-your-passwords/).
-
-
 ## Hook output
 
 Any output produced by your hooks shows up both at the console and in syslog

docs/reference/configuration/command-hooks.md

@@ -0,0 +1,168 @@
+---
+title: Command hooks
+eleventyNavigation:
+  key: 🪝 Command hooks
+  parent: ⚙️  Configuration
+---
+<span class="minilink minilink-addedin">New in version 2.0.0</span> Command
+hooks are configured 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 or prune!"
+    - after: error
+      run:
+          - echo "Something went wrong!"
+```
+
+Each command in the `commands:` list has the following options:
+
+ * `before` or `after`: Name for the point in borgmatic's execution that the commands should be run before or after, one of:
+    * `action` runs before or after each action for each repository. This replaces the deprecated `before_create`, `after_prune`, etc.
+    * `repository` runs before or after all actions for each repository. This replaces the deprecated `before_actions` and `after_actions`.
+    * `configuration` runs before or after all actions and repositories in the current configuration file.
+    * `everything` runs before or after all configuration files. Errors here do not trigger `error` hooks or the `fail` state in monitoring hooks. This replaces the deprecated `before_everything` and `after_everything`.
+    * `error` runs after an error occurs—and it's only available for `after`. This replaces the deprecated `on_error` hook.
+ * `when`: Only trigger the hook when borgmatic is run with particular actions (`create`, `prune`, etc.) listed here. Defaults to running for all actions.
+ * `states`: <span class="minilink minilink-addedin">New in version 2.0.3</span> Only trigger the hook if borgmatic encounters one of the states (execution results) listed here. This state is evaluated only for the scope of the configured `action`, `repository`, etc., rather than for the entire borgmatic run. Only available for `after` hooks. Defaults to running the hook for all states. One or more of:
+    * `finish`: No errors occurred.
+    * `fail`: An error occurred.
+ * `run`: List of one or more shell commands or scripts to run when this command hook is triggered.
+
+When command hooks run, they respect the `working_directory` option if it is
+configured, meaning that the hook commands are run in that directory.
+
+<span class="minilink minilink-addedin">New in version 2.0.4</span>If the exact
+same `everything` command hook is present in multiple configuration files,
+borgmatic only runs it once.
+
+borgmatic's `--repository` flag does not impact which command hooks get run. But
+you can use the `--config` flag to limit the configuration files (and thus
+command hooks) used.
+
+
+## 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:
+
+ * Run `before: everything` hooks (from all configuration files).
+    * Run `before: configuration` hooks (from the first configuration file).
+        * Run `before: repository` hooks (for the first repository).
+            * Run `before: action` hooks for `create`.
+            * Actually run the `create` action (e.g. `borg create`).
+            * Run `after: action` hooks for `create`.
+            * Run `before: action` hooks for `prune`.
+            * Actually run the `prune` action (e.g. `borg prune`).
+            * Run `after: action` hooks for `prune`.
+        * Run `after: repository` hooks (for the first repository).
+    * Run `after: configuration` hooks (from the first configuration file).
+    * Run `after: error` hooks (if an error occurs).
+ * Run `after: everything` hooks (from all configuration files).
+
+This same order of execution extends to multiple repositories and/or
+configuration files.
+
+Based on the above, you can see the difference between, say, an `after: action`
+hook with `states: [fail]` and an `after: error` hook. The `after: action hook`
+runs immediately after the create action fails for a particular repository—so
+before any subsequent actions for that repository or other repositories even
+have a chance to run. Whereas the `after: error` hook doesn't run until all
+actions for—and repositories in—a configuration file have had a chance to
+execute.
+
+And if there are multiple hooks defined for a particular step (e.g. `before:
+action` for `create`), then those hooks are run in the order they're defined in
+configuration.
+
+
+## Variable interpolation
+
+The command action hooks support interpolating particular runtime variables into
+the commands that are run. Here's are a couple examples that assume you provide
+separate shell scripts:
+
+```yaml
+commands:
+    - after: action
+      when: [prune]
+      run:
+          - record-prune.sh {configuration_filename} {repository}
+    - after: error
+      when: [create]
+      run:
+          - send-text-message.sh {configuration_filename} {repository}
+```
+
+In this example, when the hook is triggered, borgmatic interpolates runtime
+values into each hook command: the borgmatic configuration filename and the
+paths of the current Borg repository.
+
+Here's the full set of supported variables you can use here:
+
+ * `configuration_filename`: borgmatic configuration filename in which the
+   hook was defined
+ * `log_file`
+   <span class="minilink minilink-addedin">New in version 1.7.12</span>:
+   path of the borgmatic log file, only set when the `--log-file` flag is used
+ * `repository`: path of the current repository as configured in the current
+   borgmatic configuration file, if applicable to the current hook
+ * `repository_label` <span class="minilink minilink-addedin">New in version
+   1.8.12</span>: label of the current repository as configured in the current
+   borgmatic configuration file, if applicable to the current hook
+ * `error`: the error message itself, only applies to `error` hooks
+ * `output`: output of the command that failed, only applies to `error` hooks
+   (may be blank if an error occurred without running a command)
+
+Not all command hooks support all variables. For instance, the `everything` and
+`configuration` hooks don't support repository variables because those hooks
+don't run in the context of a single repository. But the deprecated command
+hooks (`before_backup`, `on_error`, etc.) do generally support variable
+interpolation.
+
+borgmatic automatically escapes these interpolated values to prevent shell
+injection attacks. One implication is that you shouldn't wrap the interpolated
+values in your own quotes, as that will interfere with the quoting performed by
+borgmatic and result in your command receiving incorrect arguments. For
+instance, this won't work:
+
+```yaml
+commands:
+    - after: error
+      run:
+          # Don't do this! It won't work, as the {error} value is already quoted.
+          - send-text-message.sh "Uh oh: {error}"
+```
+
+Do this instead:
+
+```yaml
+commands:
+    - after: error
+      run:
+          - send-text-message.sh {error}
+```
+
+Note that you can also interpolate [arbitrary environment
+variables](https://torsion.org/borgmatic/reference/configuration/environment-variables/).
+
+
+## Full configuration
+
+```yaml
+{% include borgmatic/commands.yaml %}
+```