Suggestion for updating documention regarding snapshot forget rules

[noeck]

While I agree that the forget options can be tricky to understand as the differences are subtle, I find the proposed changes hard to understand. What does it mean to do so “for n repetitions”, for instance?

I think the main idea to keep snapshots for a number of time intervals is quite easy to understand. The main difference between --keep-* and --keep-within-* is whether snapshots from older time intervals are kept instead if some of the recent time intervals have no snapshot.

If there is a snapshot every day except yesterday,

• --keep-daily 7 will keep one snapshot from last week instead (to get 7 snapshots in total),
• --keep-within-daily 7d will just end up with 6 snapshots because there is none for yesterday.

I explained the difference with an easy example here:

Keep vs keep-within

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…

Further comments on the proposed changes:

• The cross references (like “notes further down”) are well-intended, but in my opinion, they make it harder to read because the reader needs to decide if he wants to jump there or continue reading the current paragraph. The text should have the best possible information flow.
• There would be some minor corrections (“pr” instead of “per” etc.).