From b496692885429dd8e62775867995e371c6a5ab78 Mon Sep 17 00:00:00 2001
From: Lance Edgar <lance@wuttaproject.org>
Date: Sun, 14 Dec 2025 13:21:22 -0600
Subject: [PATCH] add page about `borg compact` to free archive disk space

---
 docs/backup/compact.rst | 15 +++++++++++++++
 docs/backup/index.rst   |  1 +
 docs/conf.py            |  1 +
 3 files changed, 17 insertions(+)
 create mode 100644 docs/backup/compact.rst

diff --git a/docs/backup/compact.rst b/docs/backup/compact.rst
new file mode 100644
index 0000000..399a3ad
--- /dev/null
+++ b/docs/backup/compact.rst
@@ -0,0 +1,15 @@
+
+============================
+ Freeing Archive Disk Space
+============================
+
+Periodically to free disk space used by Borg archive storage, run the
+``borg compact`` command with your repo URL:
+
+.. code-block:: sh
+
+   sudo borg compact --progress --verbose borg@cloud.example.com:/path/to/borg-repos/myserver
+
+The first time you do so, specify ``--cleanup-commits`` to ensure legacy cruft is removed.
+
+For more info see :doc:`borg:usage/compact`.
diff --git a/docs/backup/index.rst b/docs/backup/index.rst
index 1eadf90..065d03c 100644
--- a/docs/backup/index.rst
+++ b/docs/backup/index.rst
@@ -24,3 +24,4 @@ existing Rattail app in charge of backups.
    running
    features/index
    restore
+   compact
diff --git a/docs/conf.py b/docs/conf.py
index 9b80324..dc7319c 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -39,6 +39,7 @@ extensions = [
 
 intersphinx_mapping = {
     'alembic': ('https://alembic.sqlalchemy.org/en/latest/', None),
+    'borg': ('https://borgbackup.readthedocs.io/en/stable/', None),
     'rattail': ('https://docs.wuttaproject.org/rattail/', None),
     'tailbone': ('https://docs.wuttaproject.org/tailbone/', None),
     'wuttjamaican': ('https://docs.wuttaproject.org/wuttjamaican/', None),