From 7227fbbde646e1c5028dc176fb3dcab3938a7f18 Mon Sep 17 00:00:00 2001
From: TW <tw@waldmann-edv.de>
Date: Wed, 13 May 2026 10:30:12 +0200
Subject: [PATCH] docs: forward port FAQ entry for full repository filesystem,
 fixes #9573

---
 docs/faq.rst | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/docs/faq.rst b/docs/faq.rst
index f222643b8..7c08a1acc 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -171,6 +171,66 @@ then use ``tar`` to perform the comparison:
 
     borg export-tar archive-name - | tar --compare -f - -C /path/to/compare/to
 
+Repository filesystem is full. What now?
+----------------------------------------
+
+If your repository filesystem is full (ENOSPC error), don't panic. Borg is
+designed to be robust and usually doesn't corrupt data in this situation.
+
+To fix this, you need to free up some space on that filesystem.
+
+Increasing available space
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- **Delete unrelated files**: If there are other files on the same filesystem
+  (e.g., temporary files, logs), delete them to get some free space.
+- **Reserved space (ext2/3/4)**: On Linux ext-filesystems, some space (usually 5%)
+  is reserved for the root user. If you run borg as a normal user, you might hit
+  this limit while root could still write. You can reduce this reserve to 1% to
+  gain some space for Borg::
+
+    sudo tune2fs -m 1 /dev/sdXN  # Replace with your device
+
+- **Increase filesystem size**: If you're using LVM, cloud volumes, or a virtual
+  disk, increasing the partition and filesystem size is the easiest way.
+- **Move to a larger disk**: Move the entire repository to a larger disk
+  (e.g., using ``rsync -aH /old/repo /new/repo``) and perform the cleanup there.
+
+Freeing space using Borg
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want to free space by deleting Borg archives, keep in mind that
+``borg delete`` and ``borg compact`` need some free space themselves to work,
+as they write new data before deleting old data.
+
+If you have really zero bytes free and ``borg delete`` fails:
+
+1. **Free reserved space**: If you have previously reserved space via
+   ``borg repo-space --reserve``, you can now free it::
+
+    borg repo-space --free
+
+2. **Prune/Delete and Compact**: Now that you have some space, use
+   ``borg prune`` or ``borg delete`` to remove unneeded archives, and
+   **must** run ``borg compact`` to actually free up the space.
+
+How to avoid that it happens again?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- **Reserve space via Borg**: You can reserve space for emergencies by using the
+  ``borg repo-space --reserve`` command. For example, to reserve 2 GB::
+
+    borg repo-space --reserve 2G
+
+- **Emergency space file**: Manually create a large "space reserve" file in the
+  repository filesystem that you can delete if you ever run out of space again.
+  This ensures you have enough room for ``borg delete`` and ``borg compact`` to
+  function::
+
+    dd if=/dev/zero of=/path/to/repo/reserve_file bs=1M count=2048
+
+- **Monitoring**: Set up disk space monitoring and alerts for your backup
+  storage to be notified before it runs out of space.
 
 Can Borg add redundancy to the backup data to deal with hardware malfunction?
 -----------------------------------------------------------------------------