From 9074a7da6fefdae6d240537837548f468ba7a9af Mon Sep 17 00:00:00 2001
From: Ken Tobias <634380+l1a@users.noreply.github.com>
Date: Mon, 3 Aug 2026 11:35:04 -0700
Subject: [PATCH] FAQ: sharpen the restic-interop caveat

The restic-compatibility answer says the only thing to take care of is
"that you don't run prune with restic and rustic at the same time",
which reads as prune-versus-prune. The case that actually destroys data
is a restic prune against a rustic writer of any kind, and the sentence
as written does not cover it.

rustic and restic reach safe concurrency by different mechanisms that do
not compose: rustic defers deletion by --keep-delete, restic takes an
exclusive lock which is what lets its prune delete immediately. rustic
neither takes nor honours that lock, so a restic prune can remove packs
an in-flight rustic run has written and not yet referenced.

Measured on rustic 0.11.3 and restic 0.19.1: with a rustic backup frozen
mid-write, restic prune deleted 14 packs and restic check --read-data
then reported the repository damaged. The control, the same prune
against a repository where a restic client held a lock, refused
correctly.

Docs only; no behaviour change is proposed. rustic's lock-free design is
correct and working, which is exactly why the interop caveat is narrower
and sharper than the current sentence suggests.

Assisted-By: Claude Opus 5
---
 src/FAQ.md | 29 +++++++++++++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

diff --git a/src/FAQ.md b/src/FAQ.md
index 6e72207..66d75af 100644
--- a/src/FAQ.md
+++ b/src/FAQ.md
@@ -17,8 +17,33 @@
 ## Can I use rustic with my existing restic repositories?
 
 Yes, you can. rustic uses the same repository format as restic, so you can use
-rustic and restic on the same repository. The only thing you have to take care
-of is that you don't run prune with restic and rustic at the same time.
+rustic and restic on the same repository.
+
+There is one caveat worth stating carefully, because rustic and restic reach
+safe concurrent access by *different* mechanisms and the two do not compose:
+
+- **rustic is lock-free.** `prune` marks packs and deletes them only after
+  `--keep-delete` (default 23h), so a parallel rustic `backup` has that long to
+  finish. See [Are all operations lock free?](#are-all-operations-lock-free).
+- **restic instead takes an exclusive lock** inside the repository, which is
+  what lets its `prune` delete packs immediately.
+
+**rustic neither takes nor honours restic's lock.** So a `restic prune` running
+while *any* rustic command is writing can delete packs that the rustic run has
+just written and not yet referenced, leaving the repository failing
+`restic check`.
+
+Note this is not limited to prune-versus-prune:
+
+| combination                          | safe   | why                                                          |
+| ------------------------------------ | ------ | ------------------------------------------------------------ |
+| `rustic prune` + rustic `backup`     | yes    | the `--keep-delete` grace period                             |
+| `restic prune` + restic `backup`     | yes    | restic's repository lock                                     |
+| **`restic prune` + rustic `backup`** | **no** | restic deletes at once, relying on a lock rustic never takes |
+| `rustic prune` + restic `backup`     | yes    | the grace period still applies                               |
+
+In short: **never run `restic prune` against a repository a rustic command may
+be writing to.** If every client is rustic, none of this applies.
 
 ## What are the differences between rustic and restic?