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-12-23" "" "borg backup tool"
.SH NAME
borg-compact \- Collects garbage in the repository.
.SH SYNOPSIS
.sp
borg [common options] compact [options]
.SH DESCRIPTION
.sp
Free repository space by deleting unused chunks.
.sp
\fBborg compact\fP analyzes all existing archives to determine which repository
objects are actually used (referenced). It then deletes all unused objects
from the repository to free space.
.sp
Unused objects may result from:
.INDENT 0.0
.IP \(bu 2
use of \fBborg delete\fP or \fBborg prune\fP
.IP \(bu 2
interrupted backups (consider retrying the backup before running compact)
.IP \(bu 2
backups of source files that encountered an I/O error mid\-transfer and were skipped
.IP \(bu 2
corruption of the repository (e.g., the archives directory lost entries; see notes below)
.UNINDENT
.sp
You usually do not want to run \fBborg compact\fP after every write operation, but
either regularly (e.g., once a month, possibly together with \fBborg check\fP) or
when disk space needs to be freed.
.sp
\fBImportant:\fP
.sp
After compacting, it is no longer possible to use \fBborg undelete\fP to recover
previously soft\-deleted archives.
.sp
\fBborg compact\fP might also delete data from archives that were \(dqlost\(dq due to
archives directory corruption. Such archives could potentially be restored with
\fBborg check \-\-find\-lost\-archives [\-\-repair]\fP, which is slow. You therefore
might not want to do that unless there are signs of lost archives (e.g., when
seeing fatal errors when creating backups or when archives are missing in
\fBborg repo\-list\fP).
.sp
When using the \fB\-\-stats\fP option, borg will internally list all repository
objects to determine their existence and stored size. It will build a fresh
chunks index from that information and cache it in the repository. For some
types of repositories, this might be very slow. It will tell you the sum of
stored object sizes, before and after compaction.
.sp
Without \fB\-\-stats\fP, borg will rely on the cached chunks index to determine
existing object IDs (but there is no stored size information in the index,
thus it cannot compute before/after compaction size statistics).
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS options
.INDENT 0.0
.TP
.B  \-n\fP,\fB  \-\-dry\-run
do not change the repository
.TP
.B  \-s\fP,\fB  \-\-stats
print statistics (might be much slower)
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# Compact segments and free repository disk space
$ borg compact
.EE
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.