From b0eb3652b8923f2427dee56e79c94b5dc0563967 Mon Sep 17 00:00:00 2001 From: Paulo Manuel Ferreira Dos Santos Saraiva Date: Wed, 22 Oct 2025 09:31:49 +0200 Subject: [PATCH] Improve example for forget --keep-daily --- doc/060_forget.rst | 153 +++++++++++++++++++++++++++------------------ 1 file changed, 92 insertions(+), 61 deletions(-) diff --git a/doc/060_forget.rst b/doc/060_forget.rst index 6a985db73..10253013d 100644 --- a/doc/060_forget.rst +++ b/doc/060_forget.rst @@ -260,67 +260,6 @@ the tag. $ restic forget --tag '' --keep-last 1 -Let's look at a simple example: Suppose you have only made one backup every -Sunday for 12 weeks: - -.. code-block:: console - - $ restic snapshots - repository f00c6e2a opened successfully - ID Time Host Tags Paths - --------------------------------------------------------------- - 0a1f9759 2019-09-01 11:00:00 mopped /home/user/work - 46cfe4d5 2019-09-08 11:00:00 mopped /home/user/work - f6b1f037 2019-09-15 11:00:00 mopped /home/user/work - eb430a5d 2019-09-22 11:00:00 mopped /home/user/work - 8cf1cb9a 2019-09-29 11:00:00 mopped /home/user/work - 5d33b116 2019-10-06 11:00:00 mopped /home/user/work - b9553125 2019-10-13 11:00:00 mopped /home/user/work - e1a7b58b 2019-10-20 11:00:00 mopped /home/user/work - 8f8018c0 2019-10-27 11:00:00 mopped /home/user/work - 59403279 2019-11-03 11:00:00 mopped /home/user/work - dfee9fb4 2019-11-10 11:00:00 mopped /home/user/work - e1ae2f40 2019-11-17 11:00:00 mopped /home/user/work - --------------------------------------------------------------- - 12 snapshots - -Then ``forget --keep-daily 4`` will keep the last four snapshots, for the last -four Sundays, and remove the other snapshots: - -.. code-block:: console - - $ restic forget --keep-daily 4 --dry-run - repository f00c6e2a opened successfully - Applying Policy: keep the last 4 daily snapshots - keep 4 snapshots: - ID Time Host Tags Reasons Paths - ------------------------------------------------------------------------------- - 8f8018c0 2019-10-27 11:00:00 mopped daily snapshot /home/user/work - 59403279 2019-11-03 11:00:00 mopped daily snapshot /home/user/work - dfee9fb4 2019-11-10 11:00:00 mopped daily snapshot /home/user/work - e1ae2f40 2019-11-17 11:00:00 mopped daily snapshot /home/user/work - ------------------------------------------------------------------------------- - 4 snapshots - - remove 8 snapshots: - ID Time Host Tags Paths - --------------------------------------------------------------- - 0a1f9759 2019-09-01 11:00:00 mopped /home/user/work - 46cfe4d5 2019-09-08 11:00:00 mopped /home/user/work - f6b1f037 2019-09-15 11:00:00 mopped /home/user/work - eb430a5d 2019-09-22 11:00:00 mopped /home/user/work - 8cf1cb9a 2019-09-29 11:00:00 mopped /home/user/work - 5d33b116 2019-10-06 11:00:00 mopped /home/user/work - b9553125 2019-10-13 11:00:00 mopped /home/user/work - e1a7b58b 2019-10-20 11:00:00 mopped /home/user/work - --------------------------------------------------------------- - 8 snapshots - -The processed snapshots are evaluated against all ``--keep-*`` options but a -snapshot only need to match a single option to be kept (the results are ORed). -This means that the most recent snapshot on a Sunday would match both hourly, -daily and weekly ``--keep-*`` options, and possibly more depending on calendar. - For example, suppose you make one backup every day for 100 years. Then ``forget --keep-daily 7 --keep-weekly 5 --keep-monthly 12 --keep-yearly 75`` would keep the most recent 7 daily snapshots and 4 last-day-of-the-week ones (since the 7 @@ -339,6 +278,98 @@ year and yearly for the last 75 years, you can instead specify ``forget --keep-within-yearly 75y`` (note that `1w` is not a recognized duration, so you will have to specify `7d` instead). +The processed snapshots are evaluated against all ``--keep-*`` options but a +snapshot only need to match a single option to be kept (the results are ORed). +This means that the most recent snapshot would match both hourly, +daily and weekly ``--keep-*`` options, and possibly more depending on calendar. + +Let's look at a simple example: Suppose you have made backups every weekday for the past two weeks, +and on Fridays, you make an additional backup: + +.. code-block:: console + + $ restic snapshots + repository f00c6e2a opened successfully + ID Time Host Tags Paths + --------------------------------------------------------------- + 60e5c031 2025-04-21 11:00:00 mopped /home/user/work + 1dccffe9 2025-04-22 11:00:00 mopped /home/user/work + 90a5c949 2025-04-23 11:00:00 mopped /home/user/work + 79580708 2025-04-24 11:00:00 mopped /home/user/work + 8a603ddf 2025-04-25 11:00:00 mopped /home/user/work + ae33bf10 2025-04-25 23:00:00 mopped /home/user/work + fb8b1418 2025-04-28 11:00:00 mopped /home/user/work + 1db188b4 2025-04-29 11:00:00 mopped /home/user/work + 7baa4f28 2025-05-01 11:00:00 mopped /home/user/work + 05c48af3 2025-05-02 11:00:00 mopped /home/user/work + ad72e262 2025-05-02 23:00:00 mopped /home/user/work + --------------------------------------------------------------- + 11 snapshots + +However, for some reason, you missed making a backup last Wednesday. +Then ``forget --keep-daily 5`` will keep only one snapshot per day for the last +five days that had a snapshot and remove the other snapshots: + +.. code-block:: console + + $ restic forget --keep-daily 5 --dry-run + repository f00c6e2a opened successfully + Applying Policy: keep 5 daily snapshots + keep 5 snapshots: + ID Time Host Tags Reasons Paths + ------------------------------------------------------------------------------- + 8a603ddf 2025-04-25 23:00:00 mopped daily snapshot /home/user/work + fb8b1418 2025-04-28 11:00:00 mopped daily snapshot /home/user/work + 1db188b4 2025-04-29 11:00:00 mopped daily snapshot /home/user/work + 7baa4f28 2025-05-01 11:00:00 mopped daily snapshot /home/user/work + ad72e262 2025-05-02 23:00:00 mopped daily snapshot /home/user/work + ------------------------------------------------------------------------------- + 5 snapshots + + remove 6 snapshots: + ID Time Host Tags Paths + --------------------------------------------------------------- + 60e5c031 2025-04-21 11:00:00 mopped /home/user/work + 1dccffe9 2025-04-22 11:00:00 mopped /home/user/work + 90a5c949 2025-04-23 11:00:00 mopped /home/user/work + 79580708 2025-04-24 11:00:00 mopped /home/user/work + 8a603ddf 2025-04-25 11:00:00 mopped /home/user/work + 05c48af3 2025-05-02 11:00:00 mopped /home/user/work + --------------------------------------------------------------- + 6 snapshots + +As you can see, this kept a snapshot from the previous Friday since you missed the Wednesday backup. +If you use ``forget --keep-within-daily 7d`` instead, you will only keep +at most one daily backup from any given day for the last seven days. In this example, it means that no backups from the first week will be kept, +regardless of how many backups exist in the second week: + +.. code-block:: console + + $ restic forget --keep-daily 5 --dry-run + repository f00c6e2a opened successfully + Applying Policy: keep daily snapshots within 7d + keep 4 snapshots: + ID Time Host Tags Reasons Paths + ------------------------------------------------------------------------------- + fb8b1418 2025-04-28 11:00:00 mopped daily within 7d /home/user/work + 1db188b4 2025-04-29 11:00:00 mopped daily within 7d /home/user/work + 7baa4f28 2025-05-01 11:00:00 mopped daily within 7d /home/user/work + ad72e262 2025-05-02 23:00:00 mopped daily within 7d /home/user/work + ------------------------------------------------------------------------------- + 4 snapshots + + remove 7 snapshots: + ID Time Host Tags Paths + --------------------------------------------------------------- + 60e5c031 2025-04-21 11:00:00 mopped /home/user/work + 1dccffe9 2025-04-22 11:00:00 mopped /home/user/work + 90a5c949 2025-04-23 11:00:00 mopped /home/user/work + 79580708 2025-04-24 11:00:00 mopped /home/user/work + 8a603ddf 2025-04-25 11:00:00 mopped /home/user/work + ae33bf10 2025-04-25 23:00:00 mopped /home/user/work + 05c48af3 2025-05-02 11:00:00 mopped /home/user/work + --------------------------------------------------------------- + 7 snapshots Removing all snapshots ======================