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