From 2419ae314ec49e96de84894b27c2f0da62f568e4 Mon Sep 17 00:00:00 2001
From: Dan Helfman <witten@torsion.org>
Date: Fri, 16 Jan 2026 12:41:12 -0800
Subject: [PATCH] Add "unsafe_skip_path_validation_before_create" option to
 documentation (#1221).

---
 borgmatic/config/schema.yaml                | 15 +++++++------
 docs/how-to/deal-with-very-large-backups.md | 25 +++++++++++++++++++++
 2 files changed, 33 insertions(+), 7 deletions(-)

diff --git a/borgmatic/config/schema.yaml b/borgmatic/config/schema.yaml
index 38be8776..b389db8b 100644
--- a/borgmatic/config/schema.yaml
+++ b/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:
diff --git a/docs/how-to/deal-with-very-large-backups.md b/docs/how-to/deal-with-very-large-backups.md
index 1e380bb3..0d64b94e 100644
--- a/docs/how-to/deal-with-very-large-backups.md
+++ b/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