From cf9e387811f402742133ae23da93d5734bb84213 Mon Sep 17 00:00:00 2001
From: Dan Helfman <witten@torsion.org>
Date: Mon, 11 Mar 2024 10:42:51 -0700
Subject: [PATCH] Document a potentially breaking shell quoting edge case
 within error hooks (#839).

---
 NEWS                                |  2 ++
 docs/how-to/monitor-your-backups.md | 23 ++++++++++++++++++++++-
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/NEWS b/NEWS
index aaf65212..0d34a806 100644
--- a/NEWS
+++ b/NEWS
@@ -10,6 +10,8 @@
  * #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
  * 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.
diff --git a/docs/how-to/monitor-your-backups.md b/docs/how-to/monitor-your-backups.md
index da938711..f485aebd 100644
--- a/docs/how-to/monitor-your-backups.md
+++ b/docs/how-to/monitor-your-backups.md
@@ -101,7 +101,7 @@ script to handle the alerting:
 
 ```yaml
 on_error:
-    - send-text-message.sh "{configuration_filename}" "{repository}"
+    - send-text-message.sh {configuration_filename} {repository}
 ```
 
 In this example, when the error occurs, borgmatic interpolates runtime values
@@ -124,6 +124,27 @@ actions. borgmatic does not run `on_error` hooks if an error occurs within a
 documentation](https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/),
 especially the security information.
 
+<span class="minilink minilink-addedin">New in version 1.8.7</span> borgmatic
+automatically escapes these interpolated values to prevent shell injection
+attacks. One implication of this change 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
+on_error:
+    # 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
+on_error:
+    - send-text-message.sh {error}
+```
+
 
 ## Healthchecks hook