Add "unsafe_skip_path_validation_before_create" option to documentation (#1221).

borgmatic/config/schema.yaml

@@ -146,17 +146,18 @@ properties:
     unsafe_skip_path_validation_before_create:
         type: boolean
         description: |
-            Skip pre-backup safety checks: (1) runtime directory exclusion
+            Skip pre-backup safety validation: (1) runtime directory exclusion
             detection, and (2) special file exclusion for database streaming.
             Can significantly improve performance for large filesystems.
 
-            UNSAFE because if using data source hooks: Borg may hang on special
-            files (named pipes, devices), and data from borgmatic data source
-            hooks may be silently excluded if your exclude_patterns match the
-            runtime directory (see "user_runtime_directory" option).
+            UNSAFE because, when this option is enabled, Borg may hang on
+            special files (named pipes, devices) and data from borgmatic data
+            source hooks may be silently excluded if your excluded patterns
+            match the runtime directory (see the "user_runtime_directory"
+            option).
 
-            Only enable if not using data source hooks, or after manually
-            verifying your excludes don't affect the runtime directory. Defaults
+            Only enable if not using data source hooks and you manually verify
+            that your excludes don't affect the runtime directory. Defaults
             to false.
         example: true
     flags:

docs/how-to/deal-with-very-large-backups.md

@@ -39,6 +39,31 @@ documentation](https://torsion.org/borgmatic/reference/configuration/consistency
 for details.
 
 
+### Pre-backup safety validation
+
+Before running a backup during the `create` action, borgmatic automatically runs
+through some pre-backup safety validation to ensure that:
+
+1. You haven't accidentally excluded borgmatic's [runtime
+directory](https://torsion.org/borgmatic/reference/configuration/runtime-directory/)
+from the backup, which would break things like database dumps, filesystem
+snapshots, etc.
+2. Special files are auto-excluded to prevent Borg from hanging.
+
+This validation does have a cost: performance. On a large filesystem, it can
+take a while to run. So if you are absolutely sure that you aren't excluding
+borgmatic's runtime directory, and you also aren't including any special files
+that might cause Borg to hang, you can disable the pre-backup validation as
+follows:
+
+```yaml
+unsafe_skip_path_validation_before_create: true
+```
+
+However, this is indeed unsafe, and could lead to hangs or data being left out
+of backups. Use this option at your own risk.
+
+
 ## Troubleshooting
 
 ### Broken pipe with remote repository