Keep vs keep-within


Want to preface that I really love the software and documentation.

However I read the retention page multiple times and I still fail to understand the difference between keep and keep-within.

Are both relative to the latest snapshot? Or just one of these?

Could I get a small example for keep and one for keep-within?

The Sunday backup example keeps 4 snapshots when --keep-daily 4 is used. What would the result be if --keep-within-daily 4d was used?


1 Like

You can simply investigate how they differ, with your own snaphots, by using the --dry-run option to the forget command. Restic will list what it keeps and why.

1 Like

My understanding from the documentation can be illustrated with an example. Let’s assume we have snapshots (with pseudo-IDs a0-9):

  • a1 on May 1st 8 a.m.
  • a2 on May 2nd 8 a.m.
  • a3 on May 2nd 11 a.m.
  • a4 on May 4th 9 a.m.
  • a5 on May 5th 10 a.m.

Running forget on May 5th at noon, the two options will do this:

  • --keep-daily 4 keeps the last 4 daily snapshots on days which have a snapshot but only one per day. a5 and a4 obviously, there is nothing on May 3rd, then the latest from May 2nd, i.e. a3 and a1: a1, a3, a4, a5. (4 snapshots)
  • --keep-within-daily 4d keeps only snapshots within the last 4 days. This is similar but not identical. The time range is from May 1st 10 a.m. to May 5th 10 a.m. (last snapshot). a1 is outside of that range. Again, only one snapshot per day, forgetting a2. So the retained snapshots are: a3, a4, a5. (3 snapshots)

In short: with keep-daily 4 you get 4 snapshots. With keep-within-daily 4d you get one per day for the last 4 days. If you have >= 1 snapshots per day at the same times, it should be pretty much the same.

This of it like this:

  • -keep-hourly <n>: “keep n number of hourly snapshots, regardless of timeframe”
  • -keep-within-hourly <timeframe>: “keep all hourly snapshots during the given timeframe”

So the former is just keeping a specified number of snapshots, while the latter keeps snapshots within a timeframe.

1 Like

Thank you kind stranger, this is very verbose I love it

1 Like

Thanks I wasn’t seeing any difference with --dry-run because I just recently started a fresh repo and only did hourly backups for a couple of days

1 Like