From dfdb1cb15e1db90226cbcb4bfd8a335796a6c721 Mon Sep 17 00:00:00 2001
From: Dan Helfman <witten@torsion.org>
Date: Sat, 13 Dec 2025 09:57:33 -0800
Subject: [PATCH] Document a problematic interaction between borgmatic and
 systemd-tmpfiles (#1201).

---
 NEWS                                          |  2 ++
 .../configuration/runtime-directory.md        | 25 +++++++++++++++++++
 2 files changed, 27 insertions(+)

diff --git a/NEWS b/NEWS
index c8d9110f..af723620 100644
--- a/NEWS
+++ b/NEWS
@@ -12,6 +12,8 @@
    source configuration file. 
  * #1195: Fix a regression in the ZFS, LVM, and Btrfs hooks in which snapshotted paths ignored
    global excludes.
+ * #1201: Document a problematic interaction between borgmatic and systemd-tmpfiles:
+   https://torsion.org/borgmatic/reference/configuration/runtime-directory/#systemd-tmpfiles
  * Update the sample systemd timer with a shorter random delay when catching up on a missed run.
 
 2.0.12
diff --git a/docs/reference/configuration/runtime-directory.md b/docs/reference/configuration/runtime-directory.md
index cddad8ae..6edf7a86 100644
--- a/docs/reference/configuration/runtime-directory.md
+++ b/docs/reference/configuration/runtime-directory.md
@@ -39,3 +39,28 @@ system temporary directories.
 borgmatic created temporary streaming database dumps within the `~/.borgmatic`
 directory by default. At that time, the path was configurable by the
 `borgmatic_source_directory` configuration option (now deprecated).
+
+
+## systemd-tmpfiles
+
+If borgmatic's runtime directory is in `/tmp`, be aware that some systems may
+automatically delete `/tmp` files on a periodic basis, e.g. via
+[systemd-tmpfiles](https://www.freedesktop.org/software/systemd/man/251/systemd-tmpfiles.html).
+
+One sign that this is happening is borgmatic erroring during cleanup with "No
+such file or directory" on the runtime directory path, indicating that
+borgmatic's runtime diectory is getting deleted out from under it.
+
+You can work around this by either excluding borgmatic's runtime directory from
+automatic systemd-tmpfiles management—or you can change borgmatic's runtime
+directory to not be in `/tmp` as described above.
+
+Here's what a systemd-tmpfiles exclude for borgmatic might look like, for
+instance in an `/etc/tmpfiles.d/borgmatic.conf` file:
+
+```
+x /tmp/borgmatic-*
+```
+
+That tells systemd-tmpfiles to ignore borgmatic's runtime directory when
+automatically deleting paths in `/tmp`.