Borg: Explain prune daily, weekly, monthly in a calendar chart

Created on 9 Mar 2016 · 13Comments · Source: borgbackup/borg

I am not sure I understand how will prune command behave if I would have 1 hour cronjob running on a machine thats on 24/7
borg prune -v $REPOSITORY \ --keep-daily=2 --keep-weekly=4 --keep-monthly=2

Can someone please illustrate in the chart? Each day is separated in to 24 hours. Which backups would be kept if prune above would be executed after every backup?

monthly chart

documentation easy

Source

DoTheEvo

👍1

Most helpful comment

In borg 1.1, there will be a unified prune output: not first keep list, then delete list, but one list sorted by archive datetime and marked with "keeping" or "prune" at the left.

If one uses prune -v --list --dry-run ... with that, it becomes well visible what it does (and what is described in words in the docs already).

ThomasWaldmann on 19 Apr 2016

👍2

All 13 comments

@DoTheEvo example from docs looks clear for me

``````

Keep 7 end of day, 4 additional end of week archives,

and an end of month archive for every month:

$ borg prune --keep-daily=7 --keep-weekly=4 --keep-monthly=-1 /mnt/backup```
``````

infectormp on 9 Mar 2016

I'ld love to have a _practically verified_ picture about what prune does, additional to the textual description.

ThomasWaldmann on 9 Mar 2016

@ThomasWaldmann --keep-monthly=-1 is typo?

infectormp on 10 Mar 2016

From prune --help:
"""
Specifying a negative number of archives to keep means that there is no limit.
"""
The default for --keep-* is 0.

ThomasWaldmann on 10 Mar 2016

I'm also really interested in this.

Right now my script is using: --keep-daily=7 --keep-weekly=4 --keep-monthly=12

I just started to use Borg and I could really use a complete example of how it will exactly behave. I can't afford to accidentally prune too much. It's something serious enough to justify a full "pruning for dummies" documentation page with nice, verified pictures.

Algent on 15 Apr 2016

@Algent that's what --dry-run is for.

ThomasWaldmann on 15 Apr 2016

In borg 1.1, there will be a unified prune output: not first keep list, then delete list, but one list sorted by archive datetime and marked with "keeping" or "prune" at the left.

If one uses prune -v --list --dry-run ... with that, it becomes well visible what it does (and what is described in words in the docs already).

ThomasWaldmann on 19 Apr 2016

👍2

I will add that I was a bit confused by this command as well. I ran

/path/to/fixed/borg/version/borg-linux64-v1.1.6 prune           \
    --verbose                       \
    --list                          \
    --keep-daily    7               \
    --keep-weekly   4               \
    --keep-monthly  12              \
    --keep-yearly   -1              \
    /path/to/repository

and was surprised to see for a few days after a week had passed that it kept pruning the oldest (week old) snapshots, when I thought it would have kept the first one. After reading the docs again, it still isn't clear, but I _think_ the way it works is that Borg has a predetermined list of dates that it considers to be "weekly backup days", "monthly backup days", and "yearly backup days"; if this is the case, I probably have simply not passed one of the "weekly" days yet. We'll see if this is correct in a few days.

If my understanding is correct, it would be nice to include a list or description of these "special" dates in the docs page. Or, maybe one could change the last sentence to read something like "Borg uses the ISO Week Date to mark specific dates throughout each year as 'weekly', 'monthly', and 'yearly' backup days (every day is a 'daily' backup day). When deciding whether to prune a particular snapshot, Borg first checks if the snapshot's date is one of these special backup days, then makes sure it is not older than the user has specified, and that there doesn't already exist a saved snapshot for that date." and maybe moving this info to the introduction paragraph?

jaxankey on 24 Jul 2018

IIRC, it is keeping the latest backup of a keep-class. so if you only have --keep-daily 7, it will keep the latest backup on each of the most recent 7 days which have backups.

So if you did multiple backups one some of these days, only the last one per day will survive (so e.g. it might keep the one from 23:30, but kill the one from 11:30).

There is a textual example in docs\misc\... btw, maybe looking at that helps.

ThomasWaldmann on 26 Jul 2018

Maybe I am wrong, and please correct me if I am. I was also confused by this and ended up here.

I think when pruning and you say keep X weeks. It will keep the backups that were made on Sunday of each week (as in ISO format Sunday is the last day of the week). But if no backup on Sunday it then will go to Saturday and so on.

For monthly backups it will keep the backup from the last day of the month, if one exists. If not existing then will use the next latest backup in the month.