mirror of
https://github.com/borgbackup/borg.git
synced 2024-12-27 02:08:54 +00:00
a6f452a050
Move the explanation below the general explanation of the `--keep-*` option behavior rephrase the last sentence to make it clear that it works like the other options that were explained in the previous paragraph. Resolves #7687
173 lines
18 KiB
PHP
173 lines
18 KiB
PHP
.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit!
|
|
|
|
.. _borg_prune:
|
|
|
|
borg prune
|
|
----------
|
|
.. code-block:: none
|
|
|
|
borg [common options] prune [options]
|
|
|
|
.. only:: html
|
|
|
|
.. class:: borg-options-table
|
|
|
|
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
|
|
| **options** |
|
|
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
|
|
| | ``-n``, ``--dry-run`` | do not change repository |
|
|
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
|
|
| | ``--force`` | force pruning of corrupted archives, use ``--force --force`` in case ``--force`` does not work. |
|
|
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
|
|
| | ``-s``, ``--stats`` | print statistics for the deleted archive |
|
|
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
|
|
| | ``--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 |
|
|
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
|
|
| | ``--format FORMAT`` | specify format for the archive part (default: "{archive:<36} {time} [{id}]") |
|
|
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
|
|
| | ``--keep-within INTERVAL`` | 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 |
|
|
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
|
|
| | ``-y``, ``--keep-yearly`` | number of yearly archives to keep |
|
|
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
|
|
| | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) |
|
|
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
|
|
| .. class:: borg-common-opt-ref |
|
|
| |
|
|
| :ref:`common_options` |
|
|
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
|
|
| **Archive filters** — Archive filters can be applied to repository targets. |
|
|
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
|
|
| | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archive names matching the pattern. see "borg help match-archives". |
|
|
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
|
|
| | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. |
|
|
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
|
|
| | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. |
|
|
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
|
|
| | ``--older TIMESPAN`` | consider archives older than (now - TIMESPAN), e.g. 7d oder 12m. |
|
|
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
|
|
| | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. |
|
|
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
|
|
|
|
.. raw:: html
|
|
|
|
<script type='text/javascript'>
|
|
$(document).ready(function () {
|
|
$('.borg-options-table colgroup').remove();
|
|
})
|
|
</script>
|
|
|
|
.. only:: latex
|
|
|
|
|
|
|
|
options
|
|
-n, --dry-run do not change repository
|
|
--force force pruning of corrupted archives, use ``--force --force`` in case ``--force`` does not work.
|
|
-s, --stats print statistics for the deleted archive
|
|
--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
|
|
--format FORMAT specify format for the archive part (default: "{archive:<36} {time} [{id}]")
|
|
--keep-within INTERVAL 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
|
|
-y, --keep-yearly number of yearly archives to keep
|
|
-c SECONDS, --checkpoint-interval SECONDS write checkpoint every SECONDS seconds (Default: 1800)
|
|
|
|
|
|
:ref:`common_options`
|
|
|
|
|
|
|
Archive filters
|
|
-a PATTERN, --match-archives PATTERN only consider archive names matching the pattern. see "borg help match-archives".
|
|
--oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.
|
|
--newest TIMESPAN consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m.
|
|
--older TIMESPAN consider archives older than (now - TIMESPAN), e.g. 7d oder 12m.
|
|
--newer TIMESPAN consider archives newer than (now - TIMESPAN), e.g. 7d or 12m.
|
|
|
|
|
|
Description
|
|
~~~~~~~~~~~
|
|
|
|
The prune command prunes a repository by deleting all archives not matching
|
|
any of the specified retention options.
|
|
|
|
Important: Repository disk space is **not** freed until you run ``borg compact``.
|
|
|
|
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.
|
|
|
|
Also, prune automatically removes checkpoint archives (incomplete archives left
|
|
behind by interrupted backup runs) except if the checkpoint is the latest
|
|
archive (and thus still needed). Checkpoint archives are not considered when
|
|
comparing archive counts against the retention limits (``--keep-X``).
|
|
|
|
If you 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 sequences of archives with different data sets (e.g.
|
|
from different machines) in one shared repository, use one prune call per
|
|
data set that matches only the respective archives using the --match-archives
|
|
(-a) option.
|
|
|
|
A good procedure is to thin out more and more the older your backups get.
|
|
As an example, ``--keep-daily 7`` 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.
|
|
As of borg 1.2.0, borg will retain the oldest archive if any of the secondly,
|
|
minutely, hourly, daily, weekly, monthly, 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-within`` option takes an argument of the form "<int><char>",
|
|
where char is "H", "d", "w", "m", "y". For example, ``--keep-within 2d`` means
|
|
to keep all archives that were created within the past 48 hours.
|
|
"1m" is taken to mean "31d". This option is applied before the secondly option
|
|
and like the other options any archives kept by this option do not count towards
|
|
the later rules.
|
|
|
|
The ``--keep-last N`` option is doing the same as ``--keep-secondly N`` (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).
|
|
|
|
When using ``--stats``, you will get some statistics about how much data was
|
|
deleted - the "Deleted data" deduplicated size there is most interesting as
|
|
that is how much your repository will shrink.
|
|
Please note that the "All archives" stats refer to the state after pruning.
|
|
|
|
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 ``borg rlist`` description for more details about the format string).
|