From d83c444d9ef7ee744d3b0e0aa0cb88367eb0e289 Mon Sep 17 00:00:00 2001
From: Dan Helfman <witten@torsion.org>
Date: Tue, 13 May 2025 12:34:21 -0700
Subject: [PATCH] More documentation fixes/clarifications for customizing
 warnings and errors (#1094).

---
 docs/how-to/customize-warnings-and-errors.md | 77 ++++++++++----------
 1 file changed, 37 insertions(+), 40 deletions(-)

diff --git a/docs/how-to/customize-warnings-and-errors.md b/docs/how-to/customize-warnings-and-errors.md
index 6b584e7a..d20c3469 100644
--- a/docs/how-to/customize-warnings-and-errors.md
+++ b/docs/how-to/customize-warnings-and-errors.md
@@ -12,44 +12,10 @@ numeric ID indicating success, warning, or error. borgmatic consumes this exit
 code to decide how to respond. Normally, a Borg error results in a borgmatic
 error, while a Borg warning or success doesn't.
 
-But if that default behavior isn't sufficient for your needs, you can
-customize how borgmatic interprets [Borg's exit
+<span class="minilink minilink-addedin">With Borg version 1.4+</span> If the
+default behavior isn't sufficient for your needs, you can customize how
+borgmatic interprets [Borg's exit
 codes](https://borgbackup.readthedocs.io/en/stable/usage/general.html#return-codes).
-For instance, to elevate Borg warnings to errors, thereby causing borgmatic to
-error on them, use the following borgmatic configuration:
-
-```yaml
-borg_exit_codes:
-    - code: 1
-      treat_as: error
-```
-
-Be aware though that Borg exits with a warning code for a variety of benign
-situations such as files changing while they're being read, so this example
-may not meet your needs. Keep reading though for more granular exit code
-configuration.
-
-Here's an example that squashes Borg errors to warnings:
-
-```yaml
-borg_exit_codes:
-    - code: 2
-      treat_as: warning
-```
-
-Be careful with this example though, because it prevents borgmatic from
-erroring when Borg errors, which may not be desirable.
-
-
-### More granular configuration
-
-<span class="minilink minilink-addedin">New in Borg version 1.4</span> Borg
-support for [more granular exit
-codes](https://borgbackup.readthedocs.io/en/1.4-maint/usage/general.html#return-codes)
-means that you can configure borgmatic to respond to specific Borg conditions.
-See the full list of [Borg 1.4 error and warning exit
-codes](https://borgbackup.readthedocs.io/en/stable/internals/frontends.html#message-ids).
-The `rc:` numeric value there tells you the exit code for each.
 
 For instance, this borgmatic configuration elevates all Borg backup file
 permission warnings (exit code `105`)—and only those warnings—to errors:
@@ -71,10 +37,14 @@ borg_exit_codes:
       treat_as: error
 ```
 
+See the full list of [Borg 1.4 error and warning exit
+codes](https://borgbackup.readthedocs.io/en/stable/internals/frontends.html#message-ids).
+The `rc:` numeric value there tells you the exit code for each.
+
 If you don't know the exit code for a particular Borg error or warning you're
-experiencing, you can usually find it in your borgmatic output when
-`--verbosity 2` is enabled. For instance, here's a snippet of that output when
-a backup file is not found:
+experiencing, you can usually find it in your borgmatic output when `--verbosity
+2` is enabled. For instance, here's a snippet of that output when a backup file
+is not found:
 
 ```
 /noexist: stat: [Errno 2] No such file or directory: '/noexist'
@@ -84,3 +54,30 @@ terminating with warning status, rc 107
 
 So if you want to configure borgmatic to treat this as an error instead of a
 warning, the exit status to use is `107`.
+
+<span class="minilink minilink-addedin">With Borg version 1.2 and earlier</span>
+Older versions of Borg didn't support granular exit codes, but still
+distinguished between Borg errors and warnings. For instance, to elevate Borg
+warnings to errors, thereby causing borgmatic to error on them, use the
+following borgmatic configuration with Borg 1.2 or below:
+
+```yaml
+borg_exit_codes:
+    - code: 1
+      treat_as: error
+```
+
+Be aware though that Borg exits with a warning code for a variety of benign
+situations such as files changing while they're being read, so this example
+may not meet your needs.
+
+Here's another Borg 1.2 example that squashes Borg errors to warnings:
+
+```yaml
+borg_exit_codes:
+    - code: 2
+      treat_as: warning
+```
+
+Be careful with this example though, because it prevents borgmatic from
+erroring when Borg errors, which may not be desirable.