borg-prune - Prune repository archives according to specified rules

       The Borg Collective

                                                   2025-01-03                                      BORG-PRUNE(1)

       The  prune  command  prunes  a repository by soft-deleting all archives not matching any of the specified
       retention options.

       Important:

       • The prune command will only mark archives for deletion ("soft-deletion"), repository disk space is  not
         freed until you run borgcompact.

       • You can use borgundelete to undelete archives, but only until you run borgcompact.

       This  command  is  normally used by automated backup scripts wanting to keep a certain number of historic
       backups.     This      retention      policy      is      commonly      referred      to      as      GFS
       <https://en.wikipedia.org/wiki/Backup_rotation_scheme#Grandfather-father-son>

       (Grandfather-father-son) backup rotation scheme.

       The recommended way to use prune is to give the archive series name to it via the NAME argument (assuming
       you  have  the same name for all archives in a series).  Alternatively, you can also use --match-archives
       (-a), then only archives that match the pattern are considered for deletion and only those archives count
       towards the totals specified by the rules.  Otherwise, all archives in the repository are candidates  for
       deletion!  There is no automatic distinction between archives representing different contents. These need
       to be distinguished by specifying matching globs.

       If  you  have multiple series of archives with different data sets (e.g.  from different machines) in one
       shared repository, use one prune call per series.

       The --keep-within option takes an argument of the form "<int><char>", where char is "H", "d",  "w",  "m",
       "y". For example, --keep-within2d means to keep all archives that were created within the past 48 hours.
       "1m" is taken to mean "31d". The archives kept with this option do not count towards the totals specified
       by any other options.

       A  good procedure is to thin out more and more the older your backups get.  As an example, --keep-daily7
       means to keep the latest backup on each day, up to 7 most recent days with backups (days without  backups
       do  not count).  The rules are applied from secondly to yearly, and backups selected by previous rules do
       not count towards those of later rules. The time that each backup starts is used  for  pruning  purposes.
       Dates  and  times are interpreted in the local timezone of the system where borg prune runs, and weeks go
       from Monday to Sunday.  Specifying a negative number of archives to keep means that there is no limit.

       Borg will retain the oldest archive if any of the secondly, minutely,  hourly,  daily,  weekly,  monthly,
       quarterly,  or  yearly  rules was not otherwise able to meet its retention target. This enables the first
       chronological archive to continue aging until it is replaced by a newer archive that meets the  retention
       criteria.

       The  --keep-13weekly  and  --keep-3monthly  rules are two different strategies for keeping archives every
       quarter year.

       The --keep-lastN option is doing the same as --keep-secondlyN (and it will keep  the  last  N  archives
       under the assumption that you do not create more than one backup archive in the same second).

       You can influence how the --list output is formatted by using the --short option (less wide output) or by
       giving  a  custom  format  using  --format (see the borgrepo-list description for more details about the
       format string).

       Be careful, prune is a potentially dangerous command, it will remove backup archives.

       The default of prune is to apply to allarchivesintherepository unless you restrict its operation to a
       subset of the archives.

       The recommended way to name archives (with borgcreate) is to use the identical  archive  name  within  a
       series  of archives. Then you can simply give that name to prune also, so it operates just on that series
       of archives.

       Alternatively, you can use -a / --match-archives to do a match on the archive names  to  select  some  of
       them.   When using -a, be careful to choose a good pattern - e.g. do not use a prefix "foo" if you do not
       also want to match "foobar".

       It is strongly recommended to always run prune-v--list--dry-run...  first so you  will  see  what  it
       would do without it actually doing anything.

       Don't forget to run borgcompact-v after prune to actually free disk space.

          # Keep 7 end of day and 4 additional end of week archives.
          # Do a dry-run without actually deleting anything.
          $ borg prune -v --list --dry-run --keep-daily=7 --keep-weekly=4

          # Similar as above but only apply to the archive series named '{hostname}':
          $ borg prune -v --list --keep-daily=7 --keep-weekly=4 '{hostname}'

          # Similar as above but apply to archive names starting with the hostname
          # of the machine followed by a "-" character:
          $ borg prune -v --list --keep-daily=7 --keep-weekly=4 -a 'sh:{hostname}-*'

          # Keep 7 end of day, 4 additional end of week archives,
          # and an end of month archive for every month:
          $ borg prune -v --list --keep-daily=7 --keep-weekly=4 --keep-monthly=-1

          # Keep all backups in the last 10 days, 4 additional end of week archives,
          # and an end of month archive for every month:
          $ borg prune -v --list --keep-within=10d --keep-weekly=4 --keep-monthly=-1

       There is also a visualized prune example in docs/misc/prune-example.txt.

       borg-prune - Prune repository archives according to specified rules

       See borg-common(1) for common options of Borg commands.

   argumentsNAME   specify the archive name

   options-n, --dry-run
              do not change repository

       --list output verbose list of archives it keeps/prunes

       --short
              use a less wide archive part format

       --list-pruned
              output verbose list of archives it prunes

       --list-kept
              output verbose list of archives it keeps

       --formatFORMAT
              specify format for the archive part (default: "{archive:<36} {time} [{id}]")

       --keep-withinINTERVAL
              keep all archives within this time interval

       --keep-last, --keep-secondly
              number of secondly archives to keep

       --keep-minutely
              number of minutely archives to keep

       -H, --keep-hourly
              number of hourly archives to keep

       -d, --keep-daily
              number of daily archives to keep

       -w, --keep-weekly
              number of weekly archives to keep

       -m, --keep-monthly
              number of monthly archives to keep

       --keep-13weekly
              number of quarterly archives to keep (13 week strategy)

       --keep-3monthly
              number of quarterly archives to keep (3 month strategy)

       -y, --keep-yearly
              number of yearly archives to keep

   Archivefilters-aPATTERN, --match-archivesPATTERN
              only consider archives matching all patterns. see "borg help match-archives".

       --oldestTIMESPAN
              consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.

       --newestTIMESPAN
              consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m.

       --olderTIMESPAN
              consider archives older than (now - TIMESPAN), e.g. 7d or 12m.

       --newerTIMESPAN
              consider archives newer than (now - TIMESPAN), e.g. 7d or 12m.

borg-common(1), borg-compact(1)

       borg [common options] prune [options] [NAME]