From db7499db825cad7868a167380d9b177a9c3c34db Mon Sep 17 00:00:00 2001
From: Dan Helfman <witten@torsion.org>
Date: Mon, 14 Mar 2022 13:34:14 -0700
Subject: [PATCH] Document "repositories" context to for "before_*" and
 "after_*" command action hooks (#469).

---
 NEWS                                          |  1 +
 borgmatic/commands/borgmatic.py               |  2 +-
 ...reparation-and-cleanup-steps-to-backups.md | 26 +++++++++++++++++++
 docs/how-to/backup-your-databases.md          |  4 +--
 docs/how-to/monitor-your-backups.md           |  7 +++--
 5 files changed, 33 insertions(+), 7 deletions(-)

diff --git a/NEWS b/NEWS
index 0707a3c37..7eaa051d6 100644
--- a/NEWS
+++ b/NEWS
@@ -3,6 +3,7 @@
  * #444: When loading a configuration file that is unreadable due to file permissions, warn instead
    of erroring. This supports running borgmatic as a non-root user with configuration in ~/.config
    even if there is an unreadable global configuration file in /etc.
+ * #469: Add "repositories" context to "before_*" and "after_*" command action hooks.
  * #486: Fix handling of "patterns_from" and "exclude_from" options to error instead of warning when
    referencing unreadable files and "create" action is run.
  * #507: Fix Borg usage error in the "compact" action when running "borgmatic --dry-run". Now, skip
diff --git a/borgmatic/commands/borgmatic.py b/borgmatic/commands/borgmatic.py
index a027e39cb..b8efb8641 100644
--- a/borgmatic/commands/borgmatic.py
+++ b/borgmatic/commands/borgmatic.py
@@ -66,7 +66,7 @@ def run_configuration(config_filename, config, arguments):
     monitoring_log_level = verbosity_to_log_level(global_arguments.monitoring_verbosity)
 
     hook_context = {
-        'repository': ','.join(location['repositories']),
+        'repositories': ','.join(location['repositories']),
     }
 
     try:
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 45bbfbe2c..abf293d48 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
@@ -37,9 +37,33 @@ There are additional hooks that run before/after other actions as well. For
 instance, `before_prune` runs before a `prune` action, while `after_prune`
 runs after it.
 
+## Variable interpolation
+
+The before and after action hooks support interpolating particular runtime
+variables into the hook command. Here's an example that assumes you provide a
+separate shell script:
+
+```yaml
+hooks:
+    after_prune:
+        - record-prune.sh "{configuration_filename}" "{repositories}"
+```
+
+In this example, when the hook is triggered, borgmatic interpolates runtime
+values into the hook command: the borgmatic configuration filename and the
+paths of all configured repositories. Here's the full set of supported
+variables you can use here:
+
+ * `configuration_filename`: borgmatic configuration filename in which the
+   hook was defined
+ * `repositories`: comma-separated paths of all repositories configured in the
+   current borgmatic configuration file
+
 You can also use `before_everything` and `after_everything` hooks to perform
 global setup or cleanup:
 
+## Global hooks
+
 ```yaml
 hooks:
     before_everything:
@@ -58,6 +82,8 @@ but only if there is a `create` action. It runs even if an error occurs during
 a backup or a backup hook, but not if an error occurs during a
 `before_everything` hook.
 
+## Error hooks
+
 borgmatic also runs `on_error` hooks if an error occurs, either when creating
 a backup or running a backup hook. See the [monitoring and alerting
 documentation](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/)
diff --git a/docs/how-to/backup-your-databases.md b/docs/how-to/backup-your-databases.md
index 0d1abb358..297cf4002 100644
--- a/docs/how-to/backup-your-databases.md
+++ b/docs/how-to/backup-your-databases.md
@@ -244,8 +244,8 @@ hooks:
 ### borgmatic hangs during backup
 
 See Limitations above about `read_special`. You may need to exclude certain
-paths with named pipes, block devices, or character devices on which borgmatic
-is hanging.
+paths with named pipes, block devices, character devices, or sockets on which
+borgmatic is hanging.
 
 Alternatively, if excluding special files is too onerous, you can create two
 separate borgmatic configuration files—one for your source files and a
diff --git a/docs/how-to/monitor-your-backups.md b/docs/how-to/monitor-your-backups.md
index e616a29ec..501e98fe0 100644
--- a/docs/how-to/monitor-your-backups.md
+++ b/docs/how-to/monitor-your-backups.md
@@ -104,10 +104,9 @@ hooks:
         - send-text-message.sh "{configuration_filename}" "{repository}"
 ```
 
-In this example, when the error occurs, borgmatic interpolates a few runtime
-values into the hook command: the borgmatic configuration filename, and the
-path of the repository. Here's the full set of supported variables you can use
-here:
+In this example, when the error occurs, borgmatic interpolates runtime values
+into the hook command: the borgmatic configuration filename, and the path of
+the repository. Here's the full set of supported variables you can use here:
 
  * `configuration_filename`: borgmatic configuration filename in which the
    error occurred