mirror of
https://github.com/borgbackup/borg.git
synced 2024-12-30 11:46:48 +00:00
188 lines
6.9 KiB
Groff
188 lines
6.9 KiB
Groff
.\" Man page generated from reStructuredText.
|
|
.
|
|
.
|
|
.nr rst2man-indent-level 0
|
|
.
|
|
.de1 rstReportMargin
|
|
\\$1 \\n[an-margin]
|
|
level \\n[rst2man-indent-level]
|
|
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
-
|
|
\\n[rst2man-indent0]
|
|
\\n[rst2man-indent1]
|
|
\\n[rst2man-indent2]
|
|
..
|
|
.de1 INDENT
|
|
.\" .rstReportMargin pre:
|
|
. RS \\$1
|
|
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
|
|
. nr rst2man-indent-level +1
|
|
.\" .rstReportMargin post:
|
|
..
|
|
.de UNINDENT
|
|
. RE
|
|
.\" indent \\n[an-margin]
|
|
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.nr rst2man-indent-level -1
|
|
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
|
..
|
|
.TH "BORG-PRUNE" 1 "2022-07-03" "" "borg backup tool"
|
|
.SH NAME
|
|
borg-prune \- Prune repository archives according to specified rules
|
|
.SH SYNOPSIS
|
|
.sp
|
|
borg [common options] prune [options]
|
|
.SH DESCRIPTION
|
|
.sp
|
|
The prune command prunes a repository by deleting all archives not matching
|
|
any of the specified retention options.
|
|
.sp
|
|
Important: Repository disk space is \fBnot\fP freed until you run \fBborg compact\fP\&.
|
|
.sp
|
|
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
|
|
\fI\%GFS\fP
|
|
(Grandfather\-father\-son) backup rotation scheme.
|
|
.sp
|
|
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 (\fB\-\-keep\-X\fP).
|
|
.sp
|
|
If a prefix is set with \-P, then only archives that start with the prefix are
|
|
considered for deletion and only those archives count towards the totals
|
|
specified by the rules.
|
|
Otherwise, \fIall\fP 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 prefixes.
|
|
.sp
|
|
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 \-P option.
|
|
.sp
|
|
The \fB\-\-keep\-within\fP option takes an argument of the form "<int><char>",
|
|
where char is "H", "d", "w", "m", "y". For example, \fB\-\-keep\-within 2d\fP 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.
|
|
.sp
|
|
A good procedure is to thin out more and more the older your backups get.
|
|
As an example, \fB\-\-keep\-daily 7\fP 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, 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.
|
|
.sp
|
|
The \fB\-\-keep\-last N\fP option is doing the same as \fB\-\-keep\-secondly N\fP (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).
|
|
.sp
|
|
When using \fB\-\-stats\fP, 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.
|
|
.SH OPTIONS
|
|
.sp
|
|
See \fIborg\-common(1)\fP for common options of Borg commands.
|
|
.SS optional arguments
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-n\fP,\fB \-\-dry\-run
|
|
do not change repository
|
|
.TP
|
|
.B \-\-force
|
|
force pruning of corrupted archives, use \fB\-\-force \-\-force\fP in case \fB\-\-force\fP does not work.
|
|
.TP
|
|
.B \-s\fP,\fB \-\-stats
|
|
print statistics for the deleted archive
|
|
.TP
|
|
.B \-\-list
|
|
output verbose list of archives it keeps/prunes
|
|
.TP
|
|
.BI \-\-keep\-within \ INTERVAL
|
|
keep all archives within this time interval
|
|
.TP
|
|
.B \-\-keep\-last\fP,\fB \-\-keep\-secondly
|
|
number of secondly archives to keep
|
|
.TP
|
|
.B \-\-keep\-minutely
|
|
number of minutely archives to keep
|
|
.TP
|
|
.B \-H\fP,\fB \-\-keep\-hourly
|
|
number of hourly archives to keep
|
|
.TP
|
|
.B \-d\fP,\fB \-\-keep\-daily
|
|
number of daily archives to keep
|
|
.TP
|
|
.B \-w\fP,\fB \-\-keep\-weekly
|
|
number of weekly archives to keep
|
|
.TP
|
|
.B \-m\fP,\fB \-\-keep\-monthly
|
|
number of monthly archives to keep
|
|
.TP
|
|
.B \-y\fP,\fB \-\-keep\-yearly
|
|
number of yearly archives to keep
|
|
.TP
|
|
.B \-\-save\-space
|
|
work slower, but using less space
|
|
.UNINDENT
|
|
.SS Archive filters
|
|
.INDENT 0.0
|
|
.TP
|
|
.BI \-a \ GLOB\fR,\fB \ \-\-glob\-archives \ GLOB
|
|
only consider archive names matching the glob. sh: rules apply, see "borg help patterns".
|
|
.UNINDENT
|
|
.SH EXAMPLES
|
|
.sp
|
|
Be careful, prune is a potentially dangerous command, it will remove backup
|
|
archives.
|
|
.sp
|
|
The default of prune is to apply to \fBall archives in the repository\fP unless
|
|
you restrict its operation to a subset of the archives using \fB\-a\fP / \fB\-\-glob\-archives\fP\&.
|
|
When using \fB\-a\fP, be careful to choose a good pattern \- e.g. do not use a
|
|
prefix "foo" if you do not also want to match "foobar".
|
|
.sp
|
|
It is strongly recommended to always run \fBprune \-v \-\-list \-\-dry\-run ...\fP
|
|
first so you will see what it would do without it actually doing anything.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
# 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
|
|
|
|
# Same as above but only 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 \(aq{hostname}\-*\(aq
|
|
# actually free disk space:
|
|
$ borg compact
|
|
|
|
# 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
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
There is also a visualized prune example in \fBdocs/misc/prune\-example.txt\fP\&.
|
|
.SH SEE ALSO
|
|
.sp
|
|
\fIborg\-common(1)\fP, \fIborg\-compact(1)\fP
|
|
.SH AUTHOR
|
|
The Borg Collective
|
|
.\" Generated by docutils manpage writer.
|
|
.
|