docs: use content-describing archive names, not the hostname

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    \

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

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