Treat Borg "file not found" warnings (exit code 107) as warnings again instead of errors. Also un-deprecate the "source_directories_must_exist" option and default it to true (#1248).

docs/how-to/customize-warnings-and-errors.md

@@ -12,10 +12,11 @@ decide how to respond. By default, Borg errors (and some warnings) result
 in a borgmatic error, while Borg successes don't.
 
 <span class="minilink minilink-addedin">New in borgmatic version 2.1.0</span>
-borgmatic elevates most Borg warnings to errors by default. For instance, if a
-source directory is missing during backup, Borg indicates that with a warning
-exit code (`107`). And starting in borgmatic 2.1.0, that exit code is considered
-an error, so you'll actually find out about missing files.
+borgmatic elevates several Borg warnings to errors by default. For instance, if
+borgmatic doesn't have permission to read a configured source directory during
+backup, Borg indicates that with a warning exit code (`105`). And starting in
+borgmatic 2.1.0, that exit code is considered an error, so you'll actually find
+out about files that borgmatic can't read.
 
 <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
@@ -23,7 +24,7 @@ borgmatic interprets [Borg's exit
 codes](https://borgbackup.readthedocs.io/en/stable/internals/frontends.html#message-ids).
 
 For instance, this borgmatic configuration elevates a Borg warning about source files
-changes during backup (exit code `100`)—and only those warnings—to
+changing during backup (exit code `100`)—and only those warnings—to
 errors:
 
 ```yaml
@@ -32,14 +33,15 @@ borg_exit_codes:
       treat_as: error
 ```
 
-The following configuration does that *and* treats Borg's backup file not found
-(exit code `107`) as a warning:
+The following configuration does that *and* squashes errors about Borg
+encountering file permissions issues during backup (exit code `105`) to
+warnings.
 
 ```yaml
 borg_exit_codes:
     - code: 100
       treat_as: error
-    - code: 107
+    - code: 105
       treat_as: warning
 ```
 
@@ -54,8 +56,11 @@ is not found:
 terminating with warning status, rc 107
 ```
 
-So if you want to configure borgmatic to treat this as an warning instead of an
-error, the exit status to use is `107`.
+So if you want to configure borgmatic's interpretation of this warning, the exit
+status to use is `107`. Note however that in the particular case of missing
+files, there's a separate [`source_directories_must_exist`
+option](https://torsion.org/borgmatic/reference/configuration/#source_directories_must_exist-option)
+that can catch such problems before Borg even runs.
 
 <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