4.3-Prune-timeframe-examples.md

@@ -0,0 +1,34 @@
+# Prune timeframe examples
+
+The [borg documentation](https://borgbackup.readthedocs.io/en/stable/usage/prune.html) outlines timeframes pretty well, but since you're already here, I'll give you a few examples to get you started. The default configuration file includes this line as an example and pretty decent default value:
+
+```ini
+borgPruneSettings="--keep-within=14d --keep-daily=30 --keep-weekly=12 --keep-monthly=12"
+```
+
+I use the long-form parameters because they are very self explanatory. In this example:
+
+* Regardless of other options, keep any backups made in the last 14 days (automated, manual, accidental, everything);
+* Keep the most recent backup made each day for the last 30 days;
+* Keep the most recent backup made each week for 12 weeks; and
+* Keep the most recent backup made each month for 12 months.
+
+There are quirks with how borg counts days and you need to remember that earlier timeframes protect and push later ones. For example, if an end-of-month and end-of-week backup coincide, the end-of-week will 'push' the monthly backups back. Please refer to the [documentation](https://borgbackup.readthedocs.io/en/stable/usage/prune.html) for better examples.
+
+## other examples
+
+Preserve the last 30 days regardless and then 16 weeks thereafter:
+
+```ini
+borgPruneSettings="--keep-within=30d --keep-weekly=16"
+```
+
+Preserve the last 15 end-of-day, 4 weeks end-of-week (will start counting after the 15-day period!) and then 6 months end-of-month thereafter:
+
+```ini
+borgPruneSettings="--keep-daily=15d --keep-weekly=4 --keep-monthly=6"
+```
+
+## a note about 'keep-within'
+
+You may notice that I use 'keep-within' and 'keep-daily'. *keep-within* means *all* backups made within the specified timeframe whereas *keep-daily* means the *last* backup made on that day. Let's say I'm doing a migration or something, I might make 5 backups all on the migration day. *keep-within* ensures that all 5 of those backups are kept and does not count them toward the the single *keep-daily* that will also be made.