borg/docs/man/borg-compact.1

.\" 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-COMPACT" "1" "2025-10-31" "" "borg backup tool"
.SH NAME
borg-compact \- compact segment files in the repository
.SH SYNOPSIS
.sp
borg [common options] compact [options] [REPOSITORY]
.SH DESCRIPTION
.sp
This command frees repository space by compacting segments.
.sp
Use this regularly to avoid running out of space \- you do not need to use this
after each borg command though. It is especially useful after deleting archives,
because only compaction will really free repository space.
.sp
borg compact does not need a key, so it is possible to invoke it from the
client or also from the server.
.sp
Depending on the amount of segments that need compaction, it may take a while,
so consider using the \fB\-\-progress\fP option.
.sp
A segment is compacted if the amount of saved space is above the percentage value
given by the \fB\-\-threshold\fP option. If omitted, a threshold of 10% is used.
When using \fB\-\-verbose\fP, borg will output an estimate of the freed space.
.sp
For maximum compaction, use \fB\-\-threshold 0\fP\&. This will compact whenever any
space can be saved and thus rewrites the most data; it can be much slower on
large repositories. Using \fB\-\-threshold 1\fP usually achieves nearly the same
result significantly faster. Higher thresholds (e.g. the default 10) trade
compaction thoroughness for speed. Note: \fB\-\-threshold 100\fP will effectively
compact nothing.
.sp
After upgrading borg (server) to 1.2+, you can use \fBborg compact \-\-cleanup\-commits\fP
to clean up the numerous 17\-byte commit\-only segments that borg 1.1 did not clean up
due to a bug. It is enough to do that once per repository. After cleaning up the
commits, borg will also do a normal compaction.
.sp
See \fIseparate_compaction\fP in Additional Notes for more details.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS arguments
.INDENT 0.0
.TP
.B REPOSITORY
repository to compact
.UNINDENT
.SS options
.INDENT 0.0
.TP
.B  \-n\fP,\fB  \-\-dry\-run
do nothing
.TP
.B  \-\-cleanup\-commits
cleanup commit\-only 17\-byte segment files
.TP
.BI \-\-threshold \ PERCENT
set minimum threshold for saved space in PERCENT (Default: 10)
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# compact segments and free repo disk space
$ borg compact /path/to/repo

# same as above plus clean up 17\-byte commit\-only segments
$ borg compact \-\-cleanup\-commits /path/to/repo
.EE
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.