From 3c95ce785569a5a886e256229a566d8daa596f50 Mon Sep 17 00:00:00 2001
From: Thomas Waldmann <tw@waldmann-edv.de>
Date: Tue, 13 Oct 2026 18:19:22 +0200
Subject: [PATCH] docs: use content-describing archive names, not the hostname

borg 2 stores hostname, username and time in the archive metadata and
uses the archive name as the series name (files cache, prune grouping),
so the archive name should describe the archive content and be stable.

- quickstart: automated backup script uses the "backup-sys-home" series
  instead of '{hostname}', explain prune's default name+host grouping.
- help placeholders: replace the borg 1.x style {hostname}-{now} archive
  name examples with -a host: and repo URL placeholder usage, explain
  why archive names should not vary.
- create usage: remove the '{fqdn}-root' archive name example.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/quickstart.rst           | 18 +++++++++++-------
 docs/usage/create.rst         |  3 ---
 src/borg/archiver/help_cmd.py | 11 ++++++++---
 3 files changed, 19 insertions(+), 13 deletions(-)

diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index c1f7d4036e..166c7f6e8e 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -172,8 +172,9 @@ backed up and that the ``prune`` command keeps and deletes the correct backups.
 
     info "Starting backup"
 
-    # Back up the most important directories into an archive named after
-    # the machine this script is currently running on:
+    # Back up the most important directories into an archive of the
+    # "backup-sys-home" series. The archive name describes the archive content;
+    # borg records the host, user and time of the backup in the archive metadata:
 
     borg create                         \
         --verbose                       \
@@ -186,7 +187,7 @@ backed up and that the ``prune`` command keeps and deletes the correct backups.
         --exclude 'home/*/.cache/*'     \
         --exclude 'var/tmp/*'           \
                                         \
-        '{hostname}'                    \
+        backup-sys-home                 \
         /etc                            \
         /home                           \
         /root                           \
@@ -197,12 +198,15 @@ backed up and that the ``prune`` command keeps and deletes the correct backups.
     info "Pruning repository"
 
     # Use the `prune` subcommand to maintain 7 daily, 4 weekly and 6 monthly
-    # archives of THIS machine. The '{hostname}' matching is very important to
-    # limit prune's operation to archives with exactly that name and not apply
-    # to archives with other names also:
+    # archives of the "backup-sys-home" series. Giving the series name is very
+    # important to limit prune's operation to archives with exactly that name and
+    # not apply to archives with other names also. By default, prune applies the
+    # retention rules separately per archive name and host, so if several machines
+    # back up to the same repository, each machine's archives get their own
+    # retention and do not push out the archives of other machines:
 
     borg prune               \
-        '{hostname}'         \
+        backup-sys-home      \
         --list               \
         --show-rc            \
         --keep-daily    7    \
diff --git a/docs/usage/create.rst b/docs/usage/create.rst
index 3a96c71798..560bd7e6d2 100644
--- a/docs/usage/create.rst
+++ b/docs/usage/create.rst
@@ -40,9 +40,6 @@ Examples
     # Use zlib compression (good, but slow) — default is LZ4 (fast, low compression ratio)
     $ borg create -C zlib,6 --one-file-system root-archive /
 
-    # Backup into an archive name like FQDN-root
-    $ borg create '{fqdn}-root' /
-
     # Back up a remote host locally ("pull" style) using SSHFS
     $ mkdir sshfs-mount
     $ sshfs root@example.com:/ sshfs-mount
diff --git a/src/borg/archiver/help_cmd.py b/src/borg/archiver/help_cmd.py
index 5c883bef9b..d11557e628 100644
--- a/src/borg/archiver/help_cmd.py
+++ b/src/borg/archiver/help_cmd.py
@@ -462,9 +462,14 @@ class HelpMixIn:
 
         Examples::
 
-            borg create --repo /path/to/repo {hostname}-{user}-{utcnow} ...
-            borg create --repo /path/to/repo {hostname}-{now:%Y-%m-%d_%H:%M:%S%z} ...
-            borg prune -a 'sh:{hostname}-*' ...
+            borg --repo /path/to/repo prune -a 'host:{hostname}' ...
+            borg --repo 'sftp://backup@server/repos/{hostname}' create backup-sys-home ...
+
+        Archive names should describe the archive content (e.g. ``backup-sys-home``) and be
+        the same for all archives of a series. Do not put the hostname, user or a timestamp into
+        the archive name - borg stores them in the archive metadata anyway. Varying archive names
+        (e.g. due to ``{now}``) put every archive into a series of its own, which defeats the
+        files cache and makes ``borg prune`` keep all of them.
 
         .. note::
             systemd uses a difficult, non-standard syntax for command lines in unit files (refer to