borgbackup/borg
1
0
Fork 0
mirror of https://github.com/borgbackup/borg.git synced 2026-10-12 02:11:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

build_man ; build_usage

Browse Source
This commit is contained in:
Thomas Waldmann
2026-08-29 17:42:35 +02:00
parent 6e2c5a1818
commit e97cba32cc
73 changed files with 1192 additions and 655 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/man/borg-analyze.1
+1 -1
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-analyze" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-analyze" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-analyze \- Analyzes archives.
.SH SYNOPSIS
docs/man/borg-benchmark-cpu.1
+2 -2
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-benchmark-cpu" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-benchmark-cpu" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-benchmark-cpu \- Benchmark CPU-bound operations.
.SH SYNOPSIS
@@ -52,7 +52,7 @@ By default all benchmarks run. Give one or more of \-\-chunking, \-\-hashing,
.sp
Some algorithms use multiple threads only above a size threshold, so the
hashes and the compressors are measured at more than one buffer size: the
hashes at 64MiB (a borg pack) and 2MiB (a typical borg chunk), both above
hashes at 64MiB (roughly pack\-sized) and 2MiB (a typical borg chunk), both above
blake3\(aqs threshold, the compressors at 2MiB and 128kiB, which is below
zstd\(aqs. Within a section every row processes the same total number of
bytes \- 1 GiB, or 10 MiB for the compressors \- so the throughput column is
docs/man/borg-benchmark-crud.1
+10 -7
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-benchmark-crud" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-benchmark-crud" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
.SH SYNOPSIS
@@ -38,8 +38,9 @@ borg [common options] benchmark crud [options] PATH
.sp
This command benchmarks borg CRUD (create, read, update, delete) operations.
.sp
It creates input data below the given PATH and backs up this data into the given REPO.
The REPO must already exist (it could be a fresh empty repo or an existing repo, the
It creates input data below the given PATH and backs up this data into the repository
given via \-r/\-\-repo (or the BORG_REPO environment variable).
The repository must already exist (it could be a fresh empty repo or an existing repo, the
command will create / read / update / delete some archives named borg\-benchmark\-crud* there.
.sp
Make sure you have free space there; you will need about 1 GB each (+ overhead).
@@ -49,7 +50,7 @@ If your repository is encrypted and borg needs a passphrase to unlock the key, u
.INDENT 3.5
.sp
.EX
BORG_PASSPHRASE=mysecret borg benchmark crud REPO PATH
BORG_PASSPHRASE=mysecret borg \-r REPO benchmark crud PATH
.EE
.UNINDENT
.UNINDENT
@@ -74,9 +75,11 @@ The throughput value is kind of virtual here, it does not actually read the file
U\-Z\- == needs to check the 2 all\-zero chunks\(aq existence in the repo.
U\-R\- == needs to check existence of a lot of different chunks in the repo.
.TP
.B D\- == borg delete archive (delete last remaining archive, measure deletion + compaction)
D\-Z\- == few chunks to delete / few segments to compact/remove.
D\-R\- == many chunks to delete / many segments to compact/remove.
.B D\- == borg delete archive (soft\-delete the last remaining archive, measure deletion)
Deletion only removes the archive from the archives list, it does not free any
repository space \- that is what borg compact does (not measured here).
D\-Z\- == all\-zero files archive.
D\-R\- == random files archive.
.UNINDENT
.sp
Please note that there might be quite some variance in these measurements.
docs/man/borg-benchmark.1
+1 -1
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-benchmark" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-benchmark" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-benchmark \- benchmark command
.SH SYNOPSIS
docs/man/borg-break-lock.1
+1 -1
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-break-lock" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-break-lock" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-break-lock \- Breaks the repository lock (for example, if it was left by a dead Borg process).
.SH SYNOPSIS
docs/man/borg-check.1
+25 -16
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-check" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-check" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-check \- Checks repository consistency.
.SH SYNOPSIS
@@ -40,13 +40,18 @@ The check command verifies the consistency of a repository and its archives.
It consists of two major steps:
.INDENT 0.0
.IP 1. 3
Checking the consistency of the repository itself. This includes checking
the file magic headers, and both the metadata and data of all objects in
the repository. The read data is checked by size and hash. Bit rot and other
types of accidental damage can be detected this way. Running the repository
check can be split into multiple partial checks using \fB\-\-max\-duration\fP\&.
When checking an \%<ssh://> remote repository, please note that the checks run on
the server and do not cause significant network traffic.
Checking the consistency of the repository itself. The objects in the \fBindex/\fP
and \fBpacks/\fP namespaces are named by the sha256 hash of their content, so such
an object is intact if and only if the hash of its content still equals its name.
The check verifies the (small) index objects first and, only if they are intact,
all packs. It also cross\-checks the chunk index against the packs present in the
repository to detect referenced but missing packs. Bit rot and other types of
accidental damage can be detected this way, but as sha256 content\-addressing is
not a MAC, this step does not detect tampering. Running the repository check can
be split into multiple partial checks using \fB\-\-max\-duration\fP\&.
For rest:// repositories, the server computes the hashes, so the pack contents do
not have to travel over the network. For other remote backends, borg usually has
to read (download) the objects to hash them.
.IP 2. 3
Checking consistency and correctness of the archive metadata and optionally
archive data (requires \fB\-\-verify\-data\fP). This includes ensuring that the
@@ -54,7 +59,9 @@ repository manifest exists, the archive metadata chunk is present, and that
all chunks referencing files (items) in the archive exist. This requires
reading archive and file metadata, but not data. To scan for archives whose
entries were lost from the archive directory, pass \fB\-\-find\-lost\-archives\fP\&.
It requires reading all data and is hence very time\-consuming.
It has to look at the metadata of every object in the repository (only for the
archive metadata objects it finds that way, it also reads the object data), so
it is very time\-consuming for big repositories.
To additionally cryptographically verify the file (content) data integrity,
pass \fB\-\-verify\-data\fP, which is even more time\-consuming.
.sp
@@ -90,11 +97,13 @@ verification per week. Partial repository checks run neither archive checks
nor repair mode, so \fB\-\-max\-duration\fP requires \fB\-\-repository\-only\fP and
cannot be combined with \fB\-\-archives\-only\fP or \fB\-\-repair\fP\&.
.sp
\fBWarning:\fP Please note that partial repository checks (i.e., running with
\fB\-\-max\-duration\fP) can only perform non\-cryptographic checksum checks on the
repository files. Enabling partial repository checks excludes archive checks
for the same reason. Therefore, partial checks may be useful only with very large
repositories where a full check would take too long.
\fBNote:\fP A partial repository check verifies the repository files in exactly the
same way as a full repository check does \- the difference is only how many of them
one run gets to. What a partial run does not do are the archive checks: because
\fB\-\-max\-duration\fP requires \fB\-\-repository\-only\fP, neither the archive metadata
checks nor the cryptographic data verification of \fB\-\-verify\-data\fP run. Partial
checks are therefore mostly useful for very large repositories where a full check
would take too long.
.sp
The \fB\-\-verify\-data\fP option will perform a full integrity verification of data,
which means reading the data from the repository, decrypting and decompressing it.
@@ -112,8 +121,8 @@ tells Borg to search for lost archive metadata. If Borg encounters any archive
metadata that does not match an archive directory entry (including
soft\-deleted archives), it means that an entry was lost.
Unless \fBborg compact\fP is called, these archives can be fully restored with
\fB\-\-repair\fP\&. Please note that \fB\-\-find\-lost\-archives\fP must read a lot of
data from the repository and is thus very time\-consuming. You cannot use
\fB\-\-repair\fP\&. Please note that \fB\-\-find\-lost\-archives\fP must look at every
object in the repository and is thus very time\-consuming. You cannot use
\fB\-\-find\-lost\-archives\fP with \fB\-\-repository\-only\fP\&.
.sp
You can influence how the archive part of the \fBAnalyzing archive ...\fP output is
docs/man/borg-common.1
+1 -1
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-common" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-common" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-common \- Common options of Borg commands
.SH SYNOPSIS
docs/man/borg-compact.1
+2 -2
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-compact" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-compact" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-compact \- Collects garbage in the repository.
.SH SYNOPSIS
@@ -113,7 +113,7 @@ rewrite a pack when at least PERCENT of its bytes are unused; also gates whether
.INDENT 3.5
.sp
.EX
# Compact segments and free repository disk space
# Free repository disk space by deleting unused chunks (rewriting packs as needed)
$ borg compact
.EE
.UNINDENT
docs/man/borg-completion.1
+1 -1
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-completion" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-completion" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-completion \- Output shell completion script for the given shell.
.SH SYNOPSIS
docs/man/borg-compression.1
+1 -1
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-compression" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-compression" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-compression \- Details regarding compression
.SH DESCRIPTION
docs/man/borg-copy.1
+4 -4
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-copy" "1" "2026-08-28" "" "borg backup tool"
.TH "borg-copy" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-copy \- Copy an archive to a new archive name.
.SH SYNOPSIS
@@ -81,8 +81,8 @@ specify the new archive name
$ borg create backup\-2016\-02\-15 ~
$ borg copy backup\-2016\-02\-15 known\-good
$ borg repo\-list
e6a2b1c4 Mon, 2016\-02\-15 19:50:19 +0100 backup\-2016\-02\-15 tw MacBook\-Pro
9f3d0a77 Mon, 2016\-02\-15 19:50:19 +0100 known\-good tw MacBook\-Pro
d7b79fd3 Sat, 2026\-08\-29 14:39:27 +0200 backup\-2016\-02\-15 tw MacBook\-Pro
f81040e3 Sat, 2026\-08\-29 14:39:27 +0200 known\-good tw MacBook\-Pro
# the copy is an independent archive:
# after deleting (and compacting away) the original, the copy is still complete.
@@ -91,7 +91,7 @@ $ borg compact
$ borg extract known\-good
# if the archive name is not unique, address the archive by its ID:
$ borg copy aid:e6a2b1c4 known\-good
$ borg copy aid:d7b79fd3 known\-good
.EE
.UNINDENT
.UNINDENT
docs/man/borg-create.1
+8 -7
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-create" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-create" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-create \- Creates a new archive.
.SH SYNOPSIS
@@ -65,8 +65,8 @@ objects only once, under the path given first (like for any other root given twi
.sp
When specifying \(aq\-\(aq as a path, borg will read data from standard input and create a
file named \(aqstdin\(aq in the created archive from that data. In some cases, it is more
appropriate to use \-\-content\-from\-command. See the section \fIReading from stdin\fP
below for details.
appropriate to use \-\-content\-from\-command. See the section
\fIReading backup data from stdin\fP below for details.
.sp
The archive will consume almost no disk space for files or parts of files that
have already been stored in other archives.
@@ -238,7 +238,7 @@ set group GROUP in archive for stdin data (default: do not store group/gid)
set mode to M in archive for stdin data (default: 0660)
.TP
.B \-\-content\-from\-command
interpret PATH as a command and store its stdout. See also the section \(aqReading from stdin\(aq below.
interpret PATH as a command and store its stdout. See also the section \(aqReading backup data from stdin\(aq below.
.TP
.B \-\-paths\-from\-stdin
read DELIM\-separated list of paths to back up from stdin. All control is external: it will back up all files given \- no more, no less.
@@ -250,7 +250,7 @@ interpret PATH as command and treat its output as \fB\-\-paths\-from\-stdin\fP
interpret PATH as shell command and treat its output as \fB\-\-paths\-from\-stdin\fP
.TP
.BI \-\-paths\-delimiter \ DELIM
set path delimiter for \fB\-\-paths\-from\-stdin\fP and \fB\-\-paths\-from\-command\fP (default: \fB\en\fP)
set path delimiter for \fB\-\-paths\-from\-stdin\fP, \fB\-\-paths\-from\-command\fP and \fB\-\-paths\-from\-shell\-command\fP (default: \fB\en\fP)
.UNINDENT
.SS Include/Exclude options
.INDENT 0.0
@@ -534,6 +534,8 @@ Other flags used include:
.IP \(bu 2
\(aqi\(aq = backup data was read from standard input (stdin)
.IP \(bu 2
\(aqx\(aq = skipped due to \fB\-\-exclude\-dataless\fP (file is flagged DATALESS)
.IP \(bu 2
\(aq?\(aq = missing status code (if you see this, please file a bug report!)
.UNINDENT
.SS Errors and (incomplete) archives
@@ -546,8 +548,7 @@ At the end of the backup, if there were any such issues, borg will exit with
a non\-zero exit code (usually 1 for warnings).
.sp
\fBThe archive is still saved even if warnings or errors occurred\fP, but it will
only contain the data borg was able to read successfully. It is like a
checkpoint (see below), but with a user\-given name.
only contain the data borg was able to read successfully.
.sp
You should always check the backup logs and the exit code of the borg command.
.SS Reading backup data from stdin
docs/man/borg-delete.1
+2 -2
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-delete" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-delete" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-delete \- Deletes archives.
.SH SYNOPSIS
@@ -52,7 +52,7 @@ When in doubt, use \fB\-\-dry\-run \-\-list\fP to see what would be deleted.
.sp
You can delete multiple archives by specifying a match pattern using
the \fB\-\-match\-archives PATTERN\fP option (for more information on these
patterns, see \fIborg_patterns\fP).
patterns, see \(dqborg help match\-archives\(dq).
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
docs/man/borg-diff.1
+61 -34
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-diff" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-diff" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-diff \- Finds differences between two archives.
.SH SYNOPSIS
@@ -95,26 +95,36 @@ read include/exclude patterns from PATTERNFILE, one per line
.INDENT 3.5
.sp
.EX
# By default, borg diff reports metadata changes (mode, mtime, ctime, ...) besides
# the content changes, so the lines can get quite long:
$ borg diff archive1 archive2
+17 B \-5 B [\-rw\-r\-\-r\-\- \-> \-rwxr\-xr\-x] file1
+135 B \-252 B file2
added 0 B file4
removed 0 B file3
[mtime: Fri, 2026\-08\-28 12:26:23.433047048 +0200 \-> Fri, 2026\-08\-28 12:26:24.204040020 +0200] [ctime: Fri, 2026\-08\-28 12:26:23.433047048 +0200 \-> Fri, 2026\-08\-28 12:26:24.204040020 +0200] .
modified: +17 B \-5 B [\-rw\-r\-\-r\-\- \-> \-rwxr\-xr\-x] [mtime: Fri, 2026\-08\-28 12:26:23.431245244 +0200 \-> Fri, 2026\-08\-28 12:26:24.199251801 +0200] [ctime: Fri, 2026\-08\-28 12:26:23.431245244 +0200 \-> Fri, 2026\-08\-28 12:26:24.200688313 +0200] file1
modified: +135 B \-252 B [mtime: Fri, 2026\-08\-28 12:26:23.432895166 +0200 \-> Fri, 2026\-08\-28 12:26:24.202236091 +0200] [ctime: Fri, 2026\-08\-28 12:26:23.432895166 +0200 \-> Fri, 2026\-08\-28 12:26:24.202236091 +0200] file2
added: 0 B file4
removed: 0 B file3
$ borg diff archive1 archive2
{\(dqpath\(dq: \(dqfile1\(dq, \(dqchanges\(dq: [{\(dqtype\(dq: \(dqmodified\(dq, \(dqadded\(dq: 17, \(dqremoved\(dq: 5}, {\(dqtype\(dq: \(dqmode\(dq, \(dqold_mode\(dq: \(dq\-rw\-r\-\-r\-\-\(dq, \(dqnew_mode\(dq: \(dq\-rwxr\-xr\-x\(dq}]}
{\(dqpath\(dq: \(dqfile2\(dq, \(dqchanges\(dq: [{\(dqtype\(dq: \(dqmodified\(dq, \(dqadded\(dq: 135, \(dqremoved\(dq: 252}]}
{\(dqpath\(dq: \(dqfile4\(dq, \(dqchanges\(dq: [{\(dqtype\(dq: \(dqadded\(dq, \(dqsize\(dq: 0}]}
{\(dqpath\(dq: \(dqfile3\(dq, \(dqchanges\(dq: [{\(dqtype\(dq: \(dqremoved\(dq, \(dqsize\(dq: 0}]}
# \-\-content\-only hides the metadata changes and only reports content differences:
$ borg diff \-\-content\-only archive1 archive2
modified: +17 B \-5 B file1
modified: +135 B \-252 B file2
added: 0 B file4
removed: 0 B file3
# Use \-\-json\-lines to get one JSON object per changed path:
$ borg diff \-\-json\-lines \-\-content\-only archive1 archive2
{\(dqchanges\(dq: [{\(dqadded\(dq: 17, \(dqremoved\(dq: 5, \(dqtype\(dq: \(dqmodified\(dq}], \(dqpath\(dq: \(dqfile1\(dq}
{\(dqchanges\(dq: [{\(dqadded\(dq: 135, \(dqremoved\(dq: 252, \(dqtype\(dq: \(dqmodified\(dq}], \(dqpath\(dq: \(dqfile2\(dq}
{\(dqchanges\(dq: [{\(dqadded\(dq: 0, \(dqremoved\(dq: 0, \(dqtype\(dq: \(dqadded\(dq}], \(dqpath\(dq: \(dqfile4\(dq}
{\(dqchanges\(dq: [{\(dqadded\(dq: 0, \(dqremoved\(dq: 0, \(dqtype\(dq: \(dqremoved\(dq}], \(dqpath\(dq: \(dqfile3\(dq}
# Use \-\-sort\-by with a comma\-separated list; sorts apply stably from last to first.
# Here: primary by net size change descending, tie\-breaker by path ascending
$ borg diff \-\-sort\-by=\(dq>size_diff,path\(dq archive1 archive2
+17 B \-5 B [\-rw\-r\-\-r\-\- \-> \-rwxr\-xr\-x] file1
removed 0 B file3
added 0 B file4
+135 B \-252 B file2
$ borg diff \-\-content\-only \-\-sort\-by=\(dq>size_diff,path\(dq archive1 archive2
modified: +17 B \-5 B file1
removed: 0 B file3
added: 0 B file4
modified: +135 B \-252 B file2
.EE
.UNINDENT
.UNINDENT
@@ -142,13 +152,22 @@ $ borg diff \-\-format \(aq{content:>30} {path}{NL}\(aq ArchiveFoo ArchiveBar
.UNINDENT
.sp
The following keys are always available:
\- NEWLINE: OS dependent line separator
\- NL: alias of NEWLINE
\- NUL: NUL character for creating print0 / xargs \-0 like output
\- SPACE: space character
\- TAB: tab character
\- CR: carriage return character
\- LF: line feed character
.INDENT 0.0
.IP \(bu 2
NEWLINE: OS dependent line separator
.IP \(bu 2
NL: alias of NEWLINE
.IP \(bu 2
NUL: NUL character for creating print0 / xargs \-0 like output
.IP \(bu 2
SPACE: space character
.IP \(bu 2
TAB: tab character
.IP \(bu 2
CR: carriage return character
.IP \(bu 2
LF: line feed character
.UNINDENT
.sp
Keys available only when showing differences between archives:
.INDENT 0.0
@@ -193,12 +212,14 @@ For each matching item in both archives, Borg reports:
.INDENT 0.0
.IP \(bu 2
Content changes: total added/removed bytes within files. If chunker parameters are comparable,
Borg compares chunk IDs quickly; otherwise, it compares the content.
Borg compares chunk IDs quickly; otherwise, it compares the content. In the latter case, borg
can only tell that a file was modified, not by how much: no byte counts are given for it, the
text output shows \(dqmodified: (can\(aqt get size)\(dq instead.
.IP \(bu 2
Metadata changes: user, group, mode, and other metadata shown inline, like
\(dq[old_mode \-> new_mode]\(dq for mode changes. Use \fB\-\-content\-only\fP to suppress metadata changes.
Metadata changes: user, group, mode, and other metadata shown inline as \(dq[old \-> new]\(dq, like
\(dq[\-rw\-r\-\-r\-\- \-> \-rwxr\-xr\-x]\(dq for a mode change. Use \fB\-\-content\-only\fP to suppress metadata changes.
.IP \(bu 2
Added/removed items: printed as \(dqadded SIZE path\(dq or \(dqremoved SIZE path\(dq.
Added/removed items: printed as \(dqadded: SIZE path\(dq or \(dqremoved: SIZE path\(dq.
.UNINDENT
.SS Output formats
.sp
@@ -207,22 +228,28 @@ The default (text) output shows one line per changed path, e.g.:
.INDENT 3.5
.sp
.EX
+135 B \-252 B [ \-rw\-r\-\-r\-\- \-> \-rwxr\-xr\-x ] path/to/file
modified: +23 B \-5 B [\-rwxr\-xr\-x \-> \-rw\-r\-\-r\-\-] path/to/file
added: 4 B path/to/added\-file
removed: 5 B path/to/removed\-file
.EE
.UNINDENT
.UNINDENT
.sp
JSON Lines output (\fB\-\-json\-lines\fP) prints one JSON object per changed path, e.g.:
JSON Lines output (\fB\-\-json\-lines\fP) prints one JSON object per changed path, with a list of
change objects. Each change object has a \(dqtype\(dq plus type\-specific data: content changes
(\(dqadded\(dq, \(dqremoved\(dq, \(dqmodified\(dq) carry \(dqadded\(dq/\(dqremoved\(dq byte counts \- except for a
\(dqmodified\(dq that was determined by comparing the content, which carries no counts at all;
metadata changes (\(dqchanged mode\(dq, \(dqchanged owner\(dq, \(dqmtime\(dq, ...) carry the old and new
values as \(dqitem1\(dq and \(dqitem2\(dq. Example:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
{\(dqpath\(dq: \(dqPATH\(dq, \(dqchanges\(dq: [
{\(dqtype\(dq: \(dqmodified\(dq, \(dqadded\(dq: BYTES, \(dqremoved\(dq: BYTES},
{\(dqtype\(dq: \(dqmode\(dq, \(dqold_mode\(dq: \(dq\-rw\-r\-\-r\-\-\(dq, \(dqnew_mode\(dq: \(dq\-rwxr\-xr\-x\(dq},
{\(dqtype\(dq: \(dqadded\(dq, \(dqsize\(dq: SIZE},
{\(dqtype\(dq: \(dqremoved\(dq, \(dqsize\(dq: SIZE}
]}
{\(dqchanges\(dq: [{\(dqadded\(dq: 23, \(dqremoved\(dq: 5, \(dqtype\(dq: \(dqmodified\(dq}], \(dqpath\(dq: \(dqpath/to/file\(dq}
{\(dqchanges\(dq: [{\(dqtype\(dq: \(dqmodified\(dq}], \(dqpath\(dq: \(dqpath/to/other\-file\(dq}
{\(dqchanges\(dq: [{\(dqitem1\(dq: \(dq\-rw\-r\-\-r\-\-\(dq, \(dqitem2\(dq: \(dq\-rwxr\-xr\-x\(dq, \(dqtype\(dq: \(dqchanged mode\(dq}], \(dqpath\(dq: \(dqsome/file\(dq}
{\(dqchanges\(dq: [{\(dqadded\(dq: 4, \(dqremoved\(dq: 0, \(dqtype\(dq: \(dqadded\(dq}], \(dqpath\(dq: \(dqpath/to/added\-file\(dq}
{\(dqchanges\(dq: [{\(dqadded\(dq: 0, \(dqremoved\(dq: 5, \(dqtype\(dq: \(dqremoved\(dq}], \(dqpath\(dq: \(dqpath/to/removed\-file\(dq}
.EE
.UNINDENT
.UNINDENT
docs/man/borg-environment.1
+114 -39
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-environment" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-environment" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-environment \- Details regarding environment
.SH DESCRIPTION
@@ -50,6 +50,10 @@ Similar to BORG_REPO, but gives the default for \fB\-\-other\-repo\fP\&.
When set, use the value to answer the passphrase question for encrypted repositories.
It is used when a passphrase is needed to access an encrypted repo as well as when a new
passphrase should be initially set when initializing an encrypted repo.
BORG_PASSPHRASE, BORG_PASSCOMMAND and BORG_PASSPHRASE_FD are mutually exclusive:
if more than one of them is set, borg refuses to guess and aborts with
\(dqMore than one passphrase environment variable is set\(dq. The same applies to the
\fBBORG_OTHER_*\fP variants (which are a separate, independent group).
See also BORG_NEW_PASSPHRASE.
.TP
.B BORG_PASSCOMMAND (and BORG_OTHER_PASSCOMMAND)
@@ -58,7 +62,7 @@ passphrase question for encrypted repositories.
It is used when a passphrase is needed to access an encrypted repo as well as when a new
passphrase should be initially set when initializing an encrypted repo. Note that the command
is executed without a shell. So variables, like \fB$HOME\fP will work, but \fB~\fP won\(aqt.
If BORG_PASSPHRASE is also set, it takes precedence.
Mutually exclusive with BORG_PASSPHRASE and BORG_PASSPHRASE_FD, see there.
See also BORG_NEW_PASSPHRASE.
.TP
.B BORG_PASSPHRASE_FD (and BORG_OTHER_PASSPHRASE_FD)
@@ -67,12 +71,12 @@ from. Programs starting borg may choose to open an anonymous pipe
and use it to pass a passphrase. This is safer than passing via
BORG_PASSPHRASE, because on some systems (e.g. Linux) environment
can be examined by other processes.
If BORG_PASSPHRASE or BORG_PASSCOMMAND are also set, they take precedence.
Mutually exclusive with BORG_PASSPHRASE and BORG_PASSCOMMAND, see there.
.TP
.B BORG_NEW_PASSPHRASE
When set, use the value to answer the passphrase question when a \fBnew\fP passphrase is asked for.
This variable is checked first. If it is not set, BORG_PASSPHRASE and BORG_PASSCOMMAND will also
be checked.
This variable is checked first. If it is not set, BORG_PASSPHRASE, BORG_PASSCOMMAND and
BORG_PASSPHRASE_FD are checked (in that order).
Main use case for this is to fully automate \fBborg key change\-passphrase\fP\&.
.TP
.B BORG_DISPLAY_PASSPHRASE
@@ -186,6 +190,42 @@ cache entries for backup sources other than the current sources.
When set to a numeric value, this determines the maximum \(dqtime to live\(dq for the files cache
entries (default: 2). The files cache is used to determine quickly whether a file is unchanged.
.TP
.B BORG_STORE_CACHE
When set, borg keeps a local writethrough cache of the repository\(aqs \fBpacks/\fP
namespace: on a cache miss the whole pack is fetched once and later reads of the
objects inside that pack are served from the cache. Use this for slow or
high\-latency repositories.
Set it to \fB1\fP to use \fB$BORG_CACHE_DIR/storecache\fP, or to a directory path to
use that directory (it is created if it does not exist). Packs are named by
content hash, so one cache directory can safely hold packs of multiple repositories.
If it is not set, no such caching happens.
.TP
.B BORG_PACK_CACHE_SIZE
When set to a numeric value, limit the pack cache to that many bytes.
Only has an effect if BORG_STORE_CACHE is set.
.TP
.B BORG_PACK_MAX_SIZE
When set to a numeric value, cap packs (the repository objects that batch up many
chunks, see the internals documentation about pack files) at that many bytes
instead of the default of 50000000.
Smaller packs mean more (but smaller) repository objects and more
fine\-grained uploads; bigger packs mean fewer objects and fewer stores.
.TP
.B BORG_PACK_MAX_COUNT
When set to a numeric value, cap packs at that many objects per pack.
If BORG_PACK_MAX_SIZE is not also set, packs are then bound by count only.
.TP
.B BORG_PACK_ASYNC
When set to \fBno\fP, disable the background thread that stores a finished pack
while the next one is being assembled, and store packs synchronously instead.
This is mainly a debugging aid.
.TP
.B BORG_PACK_TRACE
When set to \fByes\fP, print one\-character lifecycle markers of the background
pack store\-thread to stderr (\fB<\fP thread started, \fBH\fP hashing starts,
\fBS\fP storing starts, \fB>\fP thread finished). This is a debugging aid to
visualize how pack stores overlap with the assembly of the next pack.
.TP
.B BORG_ASSERT_ID
Comma\-separated list of the places where borg shall verify that a chunk\(aqs content matches
its chunk id (\fBchunkid == id_hash(content)\fP) after decrypting and decompressing it.
@@ -227,15 +267,17 @@ more afterwards. (Re\-chunking in \fBborg transfer\fP is covered by \fBtransfer\
An unknown place name is an error. An empty value (\fBBORG_ASSERT_ID=\fP) verifies at none of
these places, but still where borg always verifies (see below).
.sp
Why \fBread\fP is not in the default: for encrypted repositories (all the AEAD ciphersuites),
the chunk id is part of the AEAD additional authenticated data, so a successful decryption
already proves that a holder of the repository key deliberately stored exactly this
ciphertext for exactly this chunk id. A malicious or buggy \fBrepository\fP can therefore not
swap, splice or substitute objects, whether the id is verified on read or not. What the id
check adds is the detection of chunks whose content does not match their id, which only a
malicious or compromised \fBborg client that had your borg key\fP could have written (e.g. to
poison future deduplication). If that is in your threat model \- e.g. because some machines
writing into the repository are not fully trusted \- add \fBread\fP to the list:
Why \fBread\fP is not in the default: in the keyed modes, the envelope already authenticates
every read \- the AEAD tag for the encrypted ciphersuites, the MAC for the (unencrypted)
\fBauthenticated\-*\fP modes \- and the chunk id is part of what that tag is computed over. So
a successful decryption resp. tag check already proves that a holder of the borg key
deliberately stored exactly this payload for exactly this chunk id, and a malicious or
buggy \fBrepository\fP can not swap, splice or substitute objects, whether the id is
verified on read or not. What the id check adds is the detection of chunks whose content
does not match their id, which only a malicious or compromised \fBborg client that had
your borg key\fP could have written (e.g. to poison future deduplication). If that is in
your threat model \- e.g. because some machines writing into the repository are not fully
trusted \- add \fBread\fP to the list:
.INDENT 7.0
.INDENT 3.5
.sp
@@ -255,9 +297,10 @@ Independent of this variable, borg always verifies the chunk id:
in \fBborg check \-\-verify\-data\fP\&. That audit is what makes not verifying elsewhere
defensible, so it is not configurable (there is no \fBverify_data\fP place name).
.IP \(bu 2
for \fBauthenticated\fP and \fBnone\fP mode repositories: there is no AEAD there, so the id
check \fIis\fP the read path\(aqs integrity check and switching it off would remove it
completely. Same for reading borg 1.x repositories (\fBborg transfer\fP).
for \fBnone\-*\fP mode repositories: they have no key, so nothing authenticates a read
there and their unkeyed checksums only detect accidental corruption. The id check is
therefore not optional there: it happens at every place, whatever this variable says.
Same for reading borg 1.x repositories (\fBborg transfer\fP).
.UNINDENT
.TP
.B BORG_BLAKE3_MT_THRESHOLD
@@ -357,6 +400,13 @@ given order, e.g.:
\fBnone\fP: do not try to load an implementation
.UNINDENT
.TP
.B BORG_MOUNT_DATA_CACHE_ENTRIES
Number of decrypted file content chunks \fBborg mount\fP and \fBborg webdav\fP keep
in an in\-memory cache, so that the many small, sequential reads a mounted file
system does for a big file do not re\-fetch and re\-decrypt the same chunk over and
over (default: the cpu count). Additional memory usage can be up to the chunk size
times this number.
.TP
.B BORG_SELFTEST
This can be used to influence borg\(aqs built\-in self\-tests. The default is to execute the tests
at the beginning of each borg command invocation.
@@ -386,9 +436,12 @@ caused EROFS. You will need this to make archives from volume shadow copies
in WSL1 (Windows Subsystem for Linux 1).
.TP
.B authenticated_no_key
Work around a lost passphrase or key for an \fBauthenticated\-*\fP mode repository
(these are only authenticated, but not encrypted).
If the key is missing in the repository config, add \fBkey = anything\fP there.
Work around a lost passphrase or a lost borg key for an \fBauthenticated\-*\fP
mode repository (these are only authenticated, but not encrypted).
If a borg key is found \- an object below \fBkeys/\fP in the repository (repokey)
resp. a key file in the keys directory (keyfile) \- it is not unlocked, so the
passphrase does not matter. If no borg key is found at all, borg proceeds
anyway, without any key material.
.sp
Without the key, borg can not verify anything that needs it: neither the
authentication tag of the repository objects nor the chunk ids. It therefore
@@ -412,12 +465,13 @@ After you have extracted all data you need, you MUST delete the repository:
.INDENT 3.5
.sp
.EX
BORG_WORKAROUNDS=authenticated_no_key borg delete repo
BORG_WORKAROUNDS=authenticated_no_key borg repo\-delete \-\-repo repo
.EE
.UNINDENT
.UNINDENT
.sp
Now you can init a fresh repo. Make sure you do not use the workaround any more.
Now you can create a fresh repository with \fBborg repo\-create\fP\&. Make sure you
do not use the workaround any more.
.UNINDENT
.UNINDENT
.TP
@@ -427,6 +481,10 @@ Now you can init a fresh repo. Make sure you do not use the workaround any more.
.B BORG_CHECK_FORMAT
Giving the default value for \fBborg check \-\-format=X\fP\&.
.TP
.B BORG_DIFF_FORMAT
Giving the default value for \fBborg diff \-\-format=X\fP\&.
Note: \fBborg diff \-\-content\-only\fP uses its own format and ignores this.
.TP
.B BORG_FIND_FORMAT
Giving the default value for \fBborg find \-\-format=X\fP\&.
.TP
@@ -444,6 +502,12 @@ Giving the format of the archive directory names when \fBborg mount\fP or
\fBborg webdav\fP show a whole repository, default: \fB{name}\fP\&. The placeholders
are the ones of \fBborg repo\-list \-\-format\fP; names that are not unique get
\fB\-{id:.8}\fP appended. See \fBborg mount \-\-help\fP\&.
.TP
.B BORG_JSON_INDENT
Indentation of the \fB\-\-json\fP output (default: \fB4\fP).
A number gives that many spaces per nesting level (\fB0\fP still puts every item on
its own line), \fBnone\fP gives compact single\-line JSON, and any other value is used
as the literal indent string (e.g. a tab or the empty string).
.UNINDENT
.TP
.B Some automatic \(dqanswerers\(dq (if set, they automatically answer confirmation questions):
@@ -473,13 +537,15 @@ default directory locations. This means that default paths are \fBplatform\-spec
.IP \(bu 2
Linux: XDG Base Directory Specification paths are used (e.g. \fB~/.config/borg\fP,
\fB~/.cache/borg\fP, \fB~/.local/share/borg\fP). \fBXDG_*\fP environment variables are
honoured (see \%<https://\:specifications\:.freedesktop\:.org/\:basedir-spec/\:0\:.6/\:ar01s03\:.html>).
honoured (see \%<https://\:specifications\:.freedesktop\:.org/\:basedir/\:latest/>).
.IP \(bu 2
macOS: native macOS directories are used by default (e.g. \fB~/Library/Application Support/borg\fP,
\fB~/Library/Caches/borg\fP). \fBXDG_*\fP environment variables are honoured if set.
.IP \(bu 2
Windows: Windows AppData directories are used (e.g. \fBC:\eUsers\e<user>\eAppData\eRoaming\eborg\fP,
\fBC:\eUsers\e<user>\eAppData\eLocal\eborg\fP). \fBXDG_*\fP environment variables are \fBnot\fP honoured.
Windows: local (not roaming) Windows AppData directories are used, e.g.
\fBC:\eUsers\e<user>\eAppData\eLocal\eborg\eborg\fP\&. \fBborg\fP appears twice in that path because
borg does not give platformdirs a separate \(dqapp author\(dq name, so it defaults to the app name.
\fBXDG_*\fP environment variables are \fBnot\fP honoured.
.UNINDENT
.sp
On all platforms, you can override each directory individually using the specific environment
@@ -492,10 +558,10 @@ Default directory locations by platform (when no \fBBORG_*\fP environment variab
.sp
.EX
Directory Linux macOS Windows
Config ~/.config/borg ~/Library/Application Support/borg %APPDATA%\eborg
Cache ~/.cache/borg ~/Library/Caches/borg %LOCALAPPDATA%\eborg\eCache
Data ~/.local/share/borg ~/Library/Application Support/borg %LOCALAPPDATA%\eborg
Runtime /run/user/<uid>/borg ~/Library/Caches/TemporaryItems/borg %TEMP%\eborg
Config ~/.config/borg ~/Library/Application Support/borg %LOCALAPPDATA%\eborg\eborg
Cache ~/.cache/borg ~/Library/Caches/borg %LOCALAPPDATA%\eborg\eborg\eCache
Data ~/.local/share/borg ~/Library/Application Support/borg %LOCALAPPDATA%\eborg\eborg
Runtime /run/user/<uid>/borg ~/Library/Caches/TemporaryItems/borg %LOCALAPPDATA%\eTemp\eborg\eborg
Keys <config_dir>/keys <config_dir>/keys <config_dir>\ekeys
Security <data_dir>/security <data_dir>/security <data_dir>\esecurity
.EE
@@ -504,7 +570,8 @@ Security <data_dir>/security <data_dir>/security <data_dir
.INDENT 7.0
.TP
.B BORG_BASE_DIR
Defaults to \fB$HOME\fP or \fB~$USER\fP or \fB~\fP (in that order).
Not set by default \- then the platform\-specific directories shown in the table above
are used.
If you want to move all borg\-specific folders to a custom path at once, all you need to do is
to modify \fBBORG_BASE_DIR\fP: the other paths for cache, config etc. will adapt accordingly
(assuming you didn\(aqt set them to a different custom value).
@@ -572,21 +639,29 @@ for details.
.UNINDENT
.TP
.B Building:
These are only read by \fBsetup.py\fP while building borg\(aqs C extensions. Each
\fBBORG_*_PREFIX\fP variable names the install prefix of a library that borg links
against: if it is set, \fB$PREFIX/include\fP and \fB$PREFIX/lib\fP are used unconditionally.
If it is not set, the library is located via pkg\-config, and if that does not find it
either, the build fails \- there is no bundled fallback implementation.
.INDENT 7.0
.TP
.B BORG_OPENSSL_NAME
Defines the subdirectory name for OpenSSL (setup.py).
.TP
.B BORG_OPENSSL_PREFIX
Adds given OpenSSL header file directory to the default locations (setup.py).
Prefix of the OpenSSL installation to build libcrypto against.
On Windows, the libraries are expected in \fB$PREFIX\fP itself rather than in
\fB$PREFIX/lib\fP\&. On OpenBSD, this defaults to \fB/usr/local\fP, pkg\-config is not
used and libcrypto is linked statically (borg needs AES\-OCB via the EVP API, which
LibreSSL does not have).
.TP
.B BORG_LIBACL_PREFIX
Adds given prefix directory to the default locations. If an \(aqinclude/acl/libacl.h\(aq is found
Borg will be linked against the system libacl instead of a bundled implementation. (setup.py)
.B BORG_OPENSSL_NAME
OpenBSD only: the OpenSSL flavour to use, i.e. the \fBinclude/\fP and \fBlib/\fP
subdirectory name below \fBBORG_OPENSSL_PREFIX\fP (default: \fBeopenssl35\fP).
.TP
.B BORG_LIBLZ4_PREFIX
Adds given prefix directory to the default locations. If a \(aqinclude/lz4.h\(aq is found Borg
will be linked against the system liblz4 instead of a bundled implementation. (setup.py)
Prefix of the liblz4 installation to build against.
.TP
.B BORG_LIBACL_PREFIX
Linux only: prefix of the libacl installation to build against.
.UNINDENT
.TP
.B Automatic option environment variables:
docs/man/borg-export-tar.1
+1 -1
View File
@@ -29,7 +29,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-export-tar" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-export-tar" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-export-tar \- Export archive contents as a tarball
.SH SYNOPSIS
docs/man/borg-extract.1
+1 -1
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-extract" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-extract" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-extract \- Extracts archive contents.
.SH SYNOPSIS
docs/man/borg-find.1
+22 -13
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-find" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-find" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-find \- Find files across archives.
.SH SYNOPSIS
@@ -130,14 +130,14 @@ read include/exclude patterns from PATTERNFILE, one per line
.EX
# In which archives is this file? Searched / printed from newest to oldest archive.
$ borg find home/user/file.txt
41a2ed21 docs \-rw\-rw\-r\-\- user user 1522 Sun, 2022\-02\-06 21:02:18 home/user/file.txt
20e70e3a docs \-rw\-rw\-r\-\- user user 1440 Sun, 2022\-01\-30 20:47:32 home/user/file.txt
41a2ed21 docs \-rw\-rw\-r\-\- user user 1522 Sun, 2022\-02\-06 21:02:18 +0100 home/user/file.txt
20e70e3a docs \-rw\-rw\-r\-\- user user 1440 Sun, 2022\-01\-30 20:47:32 +0100 home/user/file.txt
# Find all jpg files in the last 3 archives.
$ borg find \(aqsh:**/*.jpg\(aq \-\-last 3
39c8956e photos \-rw\-rw\-r\-\- user user 919337 Sat, 2022\-01\-01 14:20:21 photos/paris/eiffel.jpg
39c8956e photos \-rw\-rw\-r\-\- user user 1023881 Sun, 2022\-02\-06 09:12:44 photos/rome/colosseum.jpg
04061a53 photos \-rw\-rw\-r\-\- user user 919337 Sat, 2022\-01\-01 14:20:21 photos/paris/eiffel.jpg
39c8956e photos \-rw\-rw\-r\-\- user user 919337 Sat, 2022\-01\-01 14:20:21 +0100 photos/paris/eiffel.jpg
39c8956e photos \-rw\-rw\-r\-\- user user 1023881 Sun, 2022\-02\-06 09:12:44 +0100 photos/rome/colosseum.jpg
04061a53 photos \-rw\-rw\-r\-\- user user 919337 Sat, 2022\-01\-01 14:20:21 +0100 photos/paris/eiffel.jpg
# Only print the archive and the path, nothing else.
$ borg find \-\-format \(aq{archiveid:.8} {archivename} {path}{NL}\(aq home/user/file.txt
@@ -168,13 +168,22 @@ $ borg find \-\-format \(aq{archiveid:.8} {archivename} {path}{NL}\(aq \(aqsh:**
{archivename} the archive name (the archives of a series all share the name).
.sp
The following keys are always available:
\- NEWLINE: OS dependent line separator
\- NL: alias of NEWLINE
\- NUL: NUL character for creating print0 / xargs \-0 like output
\- SPACE: space character
\- TAB: tab character
\- CR: carriage return character
\- LF: line feed character
.INDENT 0.0
.IP \(bu 2
NEWLINE: OS dependent line separator
.IP \(bu 2
NL: alias of NEWLINE
.IP \(bu 2
NUL: NUL character for creating print0 / xargs \-0 like output
.IP \(bu 2
SPACE: space character
.IP \(bu 2
TAB: tab character
.IP \(bu 2
CR: carriage return character
.IP \(bu 2
LF: line feed character
.UNINDENT
.sp
Keys available only when finding files in an archive:
.INDENT 0.0
docs/man/borg-import-tar.1
+7 -5
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-import-tar" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-import-tar" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-import-tar \- Create a backup archive from a tarball
.SH SYNOPSIS
@@ -134,7 +134,7 @@ add a comment text to the archive
manually specify the archive creation date/time (yyyy\-mm\-ddThh:mm:ss[(+|\-)HH:MM] format, (+|\-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory.
.TP
.BI \-\-chunker\-params \ PARAMS
specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, NC_LEVEL). default: fastcdc,19,23,21,2
specify the chunker parameters: buzhash,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE or buzhash64,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE,NC_LEVEL or fastcdc,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,NC_LEVEL. default: fastcdc,19,23,21,2
.TP
.BI \-C \ COMPRESSION\fR,\fB \ \-\-compression \ COMPRESSION
select compression algorithm, see the output of the \(dqborg help compression\(dq command for details.
@@ -175,15 +175,17 @@ $ borg export\-tar \-\-sparse disk\-images disk\-images.tar
.UNINDENT
.SS Archives transfer script
.sp
Outputs a script that copies all archives from repo1 to repo2:
Outputs a script that copies all archives from repo1 to repo2
(\fBbash\fP, because it uses process substitution). Remove the \fBecho\fP to
actually run the commands instead of just printing them:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
for N I T in \(gaborg list \-\-format=\(aq{archive} {id} {time:%Y\-%m\-%dT%H:%M:%S}{NL}\(aq\(ga
while read \-r N I T
do
echo \(dqborg \-r repo1 export\-tar \-\-tar\-format=BORG aid:$I \- | borg \-r repo2 import\-tar \-\-timestamp=$T $N \-\(dq
done
done < <(borg \-r repo1 repo\-list \-\-format=\(aq{name} {id} {time:%Y\-%m\-%dT%H:%M:%S}{NL}\(aq)
.EE
.UNINDENT
.UNINDENT
docs/man/borg-info.1
+14 -13
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-info" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-info" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-info \- Show archive details such as disk space used
.SH SYNOPSIS
@@ -91,20 +91,21 @@ consider archives newer than (now \- TIMESPAN), e.g., 7d or 12m.
.INDENT 3.5
.sp
.EX
$ borg info aid:f7dea078
$ borg info aid:059743db
Archive name: source\-backup
Archive fingerprint: f7dea0788dfc026cc2be1c0f5b94beb4e4084eb3402fc40c38d8719b1bf2d943
Archive fingerprint: 059743db538840c04ee323673ac579d0b5433f2741c41f9643975df6370474f0
Comment:
Hostname: mba2020
Username: tw
Time (start): Sat, 2022\-06\-25 20:51:40
Time (end): Sat, 2022\-06\-25 20:51:40
Duration: 0.03 seconds
Command line: /usr/bin/borg \-r path/to/repo create source\-backup src
Utilization of maximum supported archive size: 0%
Number of files: 244
Original size: 13.80 MB
Deduplicated size: 531 B
Hostname: host
Username: user
Tags:
Time (nominal): Fri, 2026\-08\-28 12:25:52 +0200
Time (start): Fri, 2026\-08\-28 12:25:52 +0200
Time (end): Fri, 2026\-08\-28 12:25:52 +0200
Duration: 0.006 seconds
Command line: /usr/bin/borg \-r /path/to/repo create source\-backup src
Working Directory: /home/user
Number of files: 3
Original size: 3.00 MB
.EE
.UNINDENT
.UNINDENT
docs/man/borg-key-add.1
+1 -1
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-key-add" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-key-add" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-key-add \- Add a new borg key (protected by an independent passphrase) to the repository.
.SH SYNOPSIS
docs/man/borg-key-change-location.1
+1 -1
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-key-change-location" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-key-change-location" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-key-change-location \- Changes the location of the borg key used to unlock this repository.
.SH SYNOPSIS
docs/man/borg-key-change-passphrase.1
+20 -11
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-key-change-passphrase" "1" "2026-08-26" "" "borg backup tool"
.TH "borg-key-change-passphrase" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-key-change-passphrase \- Changes the repository key file passphrase.
.SH SYNOPSIS
@@ -56,20 +56,21 @@ $ borg repo\-create \-\-encryption=aes256\-ocb \-\-key\-location=keyfile \-v
Initializing repository at \(dq/path/to/repo\(dq
Enter new passphrase:
Enter same passphrase again:
Do you want your passphrase to be displayed for verification? [yN]: n
Remember your passphrase. Your data will be inaccessible without it.
Key in \(dq/root/.config/borg/keys/mnt_backup\(dq created.
Key in \(dq/root/.config/borg/keys/f23b5f0703c06dc7d9d889b5867496d8cb8ef5b42a5005221d3c7373ec6d6353\(dq created.
Keep this key safe. Your data will be inaccessible without it.
Synchronizing index...
Archives: 0, w/ index: 0, w/ outdated index: 0, w/o index: 0.
Done.
\&...
# Change key file passphrase
$ borg key change\-passphrase \-v
Enter passphrase for key /root/.config/borg/keys/mnt_backup:
Enter passphrase for key /root/.config/borg/keys/f23b5f0703c06dc7d9d889b5867496d8cb8ef5b42a5005221d3c7373ec6d6353:
Enter new passphrase:
Enter same passphrase again:
Do you want your passphrase to be displayed for verification? [yN]: n
Remember your passphrase. Your data will be inaccessible without it.
Key updated
Key location: /root/.config/borg/keys/4881c2f73d9f173bd4c4d30a9f397a596bc742bfa1f652fac3f83cee3f26cb00
.EE
.UNINDENT
.UNINDENT
@@ -77,9 +78,15 @@ Key updated
\fBNote:\fP
.INDENT 0.0
.INDENT 3.5
Automatically placed key files are named after the SHA\-256 hash of their own
contents, not after the repository directory name. Because changing the
passphrase re\-encrypts the key, the key file is rewritten under a new name and
the previous one is removed — that is why the two paths above differ. Use
\fBBORG_KEY_FILE\fP if you want to choose the key file name yourself.
.sp
The key file paths shown above are the defaults for Linux (\fB~/.config/borg/keys/\fP).
On macOS, key files are stored in \fB~/Library/Application Support/borg/keys/\fP\&.
On Windows, they are stored in \fBC:\eUsers\e<user>\eAppData\eRoaming\eborg\ekeys\e\fP\&.
On Windows, they are stored in \fBC:\eUsers\e<user>\eAppData\eLocal\eborg\eborg\ekeys\e\fP\&.
See \fIenv_vars\fP for details.
.UNINDENT
.UNINDENT
@@ -87,10 +94,12 @@ See \fIenv_vars\fP for details.
.INDENT 3.5
.sp
.EX
# Import a previously\-exported key into the specified
# key file (creating or overwriting the output key)
# (keyfile repositories only)
$ BORG_KEY_FILE=/path/to/output\-key borg key import /path/to/exported
# Import a previously\-exported key into a key file, using BORG_KEY_FILE to
# choose the output key file (creating or overwriting it).
# \-\-key\-location=keyfile is required: \(dqborg key import\(dq defaults to
# \-\-key\-location=repokey, which stores the key in the repository and
# ignores BORG_KEY_FILE.
$ BORG_KEY_FILE=/path/to/output\-key borg key import \-\-key\-location=keyfile /path/to/exported
.EE
.UNINDENT
.UNINDENT
docs/man/borg-key-export.1
+1 -1
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-key-export" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-key-export" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-key-export \- Exports a borg key of the repository for backup.
.SH SYNOPSIS
docs/man/borg-key-import.1
+17 -9
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-key-import" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-key-import" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-key-import \- Imports the repository key from backup.
.SH SYNOPSIS
@@ -42,14 +42,22 @@ If the \fB\-\-paper\fP option is given, the import will be an interactive
process in which each line is checked for plausibility before
proceeding to the next line. For this format PATH must not be given.
.sp
For repositories using keyfile encryption, the key file which \fBborg key
import\fP writes to depends on several factors. If the \fBBORG_KEY_FILE\fP
environment variable is set and non\-empty, \fBborg key import\fP creates
or overwrites that file named by \fB$BORG_KEY_FILE\fP\&. Otherwise, \fBborg
key import\fP searches in the \fB$BORG_KEYS_DIR\fP directory for a key file
associated with the repository. If a key file is found in
\fB$BORG_KEYS_DIR\fP, \fBborg key import\fP overwrites it; otherwise, \fBborg
key import\fP creates a new key file in \fB$BORG_KEYS_DIR\fP\&.
Where the imported key is stored is decided by \fB\-\-key\-location\fP:
.INDENT 0.0
.IP \(bu 2
\fBrepokey\fP (the default): the key is stored \fBin the repository\fP, no local
key file is written.
.IP \(bu 2
\fBkeyfile\fP: the key is stored in a local key file.
.UNINDENT
.sp
The key file that \fB\-\-key\-location=keyfile\fP writes to depends on several
factors. If the \fBBORG_KEY_FILE\fP environment variable is set and non\-empty,
\fBborg key import\fP creates or overwrites the file named by \fB$BORG_KEY_FILE\fP\&.
Otherwise, \fBborg key import\fP searches the \fB$BORG_KEYS_DIR\fP directory for a
key file associated with the repository. If one is found there, \fBborg key
import\fP overwrites it; otherwise it creates a new key file in
\fB$BORG_KEYS_DIR\fP\&.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
docs/man/borg-key-list.1
+1 -1
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-key-list" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-key-list" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-key-list \- List the borg keys of the repository.
.SH SYNOPSIS
docs/man/borg-key-remove.1
+1 -1
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-key-remove" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-key-remove" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-key-remove \- Remove a borg key from the repository.
.SH SYNOPSIS
docs/man/borg-key.1
+1 -1
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-key" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-key" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-key \- Manage the keyfile or repokey of a repository
.SH SYNOPSIS
docs/man/borg-list.1
+34 -25
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-list" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-list" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-list \- List archive contents.
.SH SYNOPSIS
@@ -90,35 +90,35 @@ read include/exclude patterns from PATTERNFILE, one per line
.sp
.EX
$ borg list root\-2016\-02\-15
drwxr\-xr\-x root root 0 Mon, 2016\-02\-15 17:44:27 .
drwxrwxr\-x root root 0 Mon, 2016\-02\-15 19:04:49 bin
\-rwxr\-xr\-x root root 1029624 Thu, 2014\-11\-13 00:08:51 bin/bash
lrwxrwxrwx root root 0 Fri, 2015\-03\-27 20:24:26 bin/bzcmp \-> bzdiff
\-rwxr\-xr\-x root root 2140 Fri, 2015\-03\-27 20:24:22 bin/bzdiff
drwxr\-xr\-x root root 0 Mon, 2016\-02\-15 17:44:27 +0100 .
drwxrwxr\-x root root 0 Mon, 2016\-02\-15 19:04:49 +0100 bin
\-rwxr\-xr\-x root root 1029624 Thu, 2014\-11\-13 00:08:51 +0100 bin/bash
lrwxrwxrwx root root 6 Fri, 2015\-03\-27 20:24:26 +0100 bin/bzcmp \-> bzdiff
\-rwxr\-xr\-x root root 2140 Fri, 2015\-03\-27 20:24:22 +0100 bin/bzdiff
\&...
$ borg list root\-2016\-02\-15 \-\-pattern \(dq\- bin/ba*\(dq
drwxr\-xr\-x root root 0 Mon, 2016\-02\-15 17:44:27 .
drwxrwxr\-x root root 0 Mon, 2016\-02\-15 19:04:49 bin
lrwxrwxrwx root root 0 Fri, 2015\-03\-27 20:24:26 bin/bzcmp \-> bzdiff
\-rwxr\-xr\-x root root 2140 Fri, 2015\-03\-27 20:24:22 bin/bzdiff
drwxr\-xr\-x root root 0 Mon, 2016\-02\-15 17:44:27 +0100 .
drwxrwxr\-x root root 0 Mon, 2016\-02\-15 19:04:49 +0100 bin
lrwxrwxrwx root root 6 Fri, 2015\-03\-27 20:24:26 +0100 bin/bzcmp \-> bzdiff
\-rwxr\-xr\-x root root 2140 Fri, 2015\-03\-27 20:24:22 +0100 bin/bzdiff
\&...
$ borg list archiveA \-\-format=\(dq{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NEWLINE}\(dq
drwxrwxr\-x user user 0 Sun, 2015\-02\-01 11:00:00 .
drwxrwxr\-x user user 0 Sun, 2015\-02\-01 11:00:00 code
drwxrwxr\-x user user 0 Sun, 2015\-02\-01 11:00:00 code/myproject
\-rw\-rw\-r\-\- user user 1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.ext
\-rw\-rw\-r\-\- user user 1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.text
drwxrwxr\-x user user 0 2015\-02\-01T11:00:00.000000+01:00 .
drwxrwxr\-x user user 0 2015\-02\-01T11:00:00.000000+01:00 code
drwxrwxr\-x user user 0 2015\-02\-01T11:00:00.000000+01:00 code/myproject
\-rw\-rw\-r\-\- user user 1416192 2015\-02\-01T11:00:00.000000+01:00 code/myproject/file.ext
\-rw\-rw\-r\-\- user user 1416192 2015\-02\-01T11:00:00.000000+01:00 code/myproject/file.text
\&...
$ borg list archiveA \-\-pattern \(aq+ re:\e.ext$\(aq \-\-pattern \(aq\- re:^.*$\(aq
\-rw\-rw\-r\-\- user user 1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.ext
\-rw\-rw\-r\-\- user user 1416192 Sun, 2015\-02\-01 11:00:00 +0100 code/myproject/file.ext
\&...
$ borg list archiveA \-\-pattern \(aq+ re:.ext$\(aq \-\-pattern \(aq\- re:^.*$\(aq
\-rw\-rw\-r\-\- user user 1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.ext
\-rw\-rw\-r\-\- user user 1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.text
\-rw\-rw\-r\-\- user user 1416192 Sun, 2015\-02\-01 11:00:00 +0100 code/myproject/file.ext
\-rw\-rw\-r\-\- user user 1416192 Sun, 2015\-02\-01 11:00:00 +0100 code/myproject/file.text
\&...
# Use \-\-sort\-by with a comma\-separated list; sorts apply stably from last to first.
@@ -156,13 +156,22 @@ $ borg list \-\-format \(aq{mode} {user:>6} {group:>6} {size:<8} {mtime} {path}{
.UNINDENT
.sp
The following keys are always available:
\- NEWLINE: OS dependent line separator
\- NL: alias of NEWLINE
\- NUL: NUL character for creating print0 / xargs \-0 like output
\- SPACE: space character
\- TAB: tab character
\- CR: carriage return character
\- LF: line feed character
.INDENT 0.0
.IP \(bu 2
NEWLINE: OS dependent line separator
.IP \(bu 2
NL: alias of NEWLINE
.IP \(bu 2
NUL: NUL character for creating print0 / xargs \-0 like output
.IP \(bu 2
SPACE: space character
.IP \(bu 2
TAB: tab character
.IP \(bu 2
CR: carriage return character
.IP \(bu 2
LF: line feed character
.UNINDENT
.sp
Keys available only when listing files in an archive:
.INDENT 0.0
docs/man/borg-match-archives.1
+1 -1
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-match-archives" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-match-archives" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-match-archives \- Details regarding match-archives
.SH DESCRIPTION
docs/man/borg-mount.1
+7 -5
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-mount" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-mount" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-mount \- Mounts an archive or an entire repository as a FUSE filesystem.
.SH SYNOPSIS
@@ -76,8 +76,8 @@ On Linux, this can be prevented by remounting the mountpoint with the
\fBnosymfollow\fP VFS mount option, for example:
.INDENT 0.0
.INDENT 3.5
borg mount <repo path> <mountpoint>
mount \-o remount,nosymfollow <repo path> <mountpoint>
borg \-r <repo path> mount <mountpoint>
mount \-o remount,nosymfollow <mountpoint>
.UNINDENT
.UNINDENT
.sp
@@ -100,8 +100,10 @@ Only mount a specific archive, not the whole repository.
Only mount specific paths in a specific archive, not the complete archive.
.UNINDENT
.sp
The command \fBborgfs\fP provides a wrapper for \fBborg mount\fP\&. This can also be
used in fstab entries:
The command \fBborgfs\fP provides a wrapper for \fBborg mount\fP\&. It is invoked as
\fBborgfs [REPOSITORY] MOUNTPOINT [PATH...]\fP, taking the repository as its first
positional argument (if it is not given, \fB\-r\fP / \fBBORG_REPO\fP is used). This can
also be used in fstab entries:
\fB/path/to/repo /mnt/point fuse.borgfs defaults,noauto 0 0\fP
.sp
To allow a regular user to use fstab entries, add the \fBuser\fP option:
docs/man/borg-patterns.1
+11 -7
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-patterns" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-patterns" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-patterns \- Details regarding patterns
.SH DESCRIPTION
@@ -197,11 +197,11 @@ Examples:
.INDENT 3.5
.sp
.EX
# Exclude a directory anywhere in the tree named \(ga\(gasteamapps/common\(ga\(ga
# Exclude a directory anywhere in the tree named steamapps/common
# (and everything below it), regardless of where it appears:
$ borg create \-e \(aqsh:**/steamapps/common/**\(aq archive /
# Exclude the contents of \(ga\(ga/home/user/.cache\(ga\(ga:
# Exclude the contents of /home/user/.cache:
$ borg create \-e \(aqsh:home/user/.cache/**\(aq archive /home/user
$ borg create \-e home/user/.cache/ archive /home/user
@@ -256,12 +256,15 @@ reset.
.TP
.B Exclude pattern prefix \fB\-\fP
Use the prefix \fB\-\fP, followed by a pattern, to define an exclusion.
This has the same effect as the \fB\-\-exclude\fP option.
Borg still recurses into a directory excluded this way, so a later
include pattern can still match files below it.
.TP
.B Exclude no\-recurse pattern prefix \fB!\fP
Use the prefix \fB!\fP, followed by a pattern, to define an exclusion
that does not recurse into subdirectories. This saves time, but
prevents include patterns to match any files in subdirectories.
The \fB\-\-exclude\fP option and the patterns in an \fB\-\-exclude\-from\fP
file give this kind of exclusion, not the recursing one of \fB\-\fP\&.
.TP
.B Include pattern prefix \fB+\fP
Use the prefix \fB+\fP, followed by a pattern, to define inclusions.
@@ -322,9 +325,10 @@ up and thus their user, group, permission, etc. cannot be restored.
.UNINDENT
.UNINDENT
.sp
Patterns (\fB\-\-pattern\fP) and excludes (\fB\-\-exclude\fP) from the command line are
considered first (in the order of appearance). Then patterns from \fB\-\-patterns\-from\fP
are added. Exclusion patterns from \fB\-\-exclude\-from\fP files are appended last.
\fB\-\-pattern\fP, \fB\-\-patterns\-from\fP, \fB\-\-exclude\fP and \fB\-\-exclude\-from\fP all feed the
same single list of patterns, in the order in which they appear on the command line.
The patterns of a pattern file resp. exclude file are inserted where the option naming
that file stands, in the order of the lines in that file.
.sp
Examples:
.INDENT 0.0
docs/man/borg-placeholders.1
+11 -3
View File
@@ -28,13 +28,14 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-placeholders" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-placeholders" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-placeholders \- Details regarding placeholders
.SH DESCRIPTION
.sp
Repository URLs, \fB\-\-name\fP, \fB\-a\fP / \fB\-\-match\-archives\fP, \fB\-\-comment\fP
and \fBBORG_REMOTE_PATH\fP values support these placeholders:
Repository URLs, the archive name arguments (\fBNAME\fP, \fBOLDNAME\fP, \fBNEWNAME\fP,
\fBARCHIVE1\fP, \fBARCHIVE2\fP), \fB\-a\fP / \fB\-\-match\-archives\fP, \fB\-\-comment\fP and
\fBBORG_REMOTE_PATH\fP values support these placeholders:
.INDENT 0.0
.TP
.B {hostname}
@@ -54,12 +55,19 @@ You can also supply your own format string \%<https://\:docs\:.python\:.org/\:3\
The current UTC date and time, by default in ISO\-8601 format.
You can also supply your own format string \%<https://\:docs\:.python\:.org/\:3\:.11/\:library/\:datetime\:.html#\:strftime-and-strptime-behavior>, e.g. {utcnow:%Y\-%m\-%d_%H:%M:%S}
.TP
.B {unixtime}
The current time as a UNIX timestamp, i.e. whole seconds since the epoch,
e.g.: 1735732800
.TP
.B {user}
The user name (or UID, if no name is available) of the user running borg.
.TP
.B {pid}
The current process ID.
.TP
.B {uuid4}
A random UUID (version 4), freshly generated each time placeholders are replaced.
.TP
.B {borgversion}
The version of borg, e.g.: 1.0.8rc1
.TP
docs/man/borg-prune.1
+1 -13
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-prune" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-prune" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-prune \- Prune archives according to specified rules.
.SH SYNOPSIS
@@ -217,18 +217,6 @@ number or time interval of yearly archives to keep
.TP
.BI \-a \ PATTERN\fR,\fB \ \-\-match\-archives \ PATTERN
only consider archives matching all patterns. See \(dqborg help match\-archives\(dq.
.TP
.BI \-\-oldest \ TIMESPAN
consider archives between the oldest archive\(aqs timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-newest \ TIMESPAN
consider archives between the newest archive\(aqs timestamp and (newest \- TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-older \ TIMESPAN
consider archives older than (now \- TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-newer \ TIMESPAN
consider archives newer than (now \- TIMESPAN), e.g., 7d or 12m.
.UNINDENT
.SH EXAMPLES
.sp
docs/man/borg-recreate.1
+27 -18
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-recreate" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-recreate" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-recreate \- Recreate archives.
.SH SYNOPSIS
@@ -51,8 +51,9 @@ the resulting archives will contain only files from those paths.
Note that all paths in an archive are relative, therefore absolute patterns/paths
will \fInot\fP match (\fB\-\-exclude\fP, \fB\-\-exclude\-from\fP, PATHs).
.sp
\fB\-\-chunker\-params\fP will re\-chunk all files in the archive, this can be
used to have upgraded Borg 0.xx archives deduplicate with Borg 1.x archives.
\fB\-\-chunker\-params\fP will re\-chunk all files in the archive. This can be used to
switch existing archives to different chunker parameters (or a different chunker
algorithm), so they deduplicate with archives created using these parameters.
.sp
\fBUSE WITH CAUTION.\fP
Depending on the paths and patterns given, recreate can be used to
@@ -60,9 +61,10 @@ delete files from archives permanently.
When in doubt, use \fB\-\-dry\-run \-\-verbose \-\-list\fP to see how patterns/paths are
interpreted. See \fIlist_item_flags\fP in \fBborg create\fP for details.
.sp
The archive being recreated is only removed after the operation completes. The
archive that is built during the operation exists at the same time at
\(dq<ARCHIVE>.recreate\(dq. The new archive will have a different archive ID.
The archive being recreated is only removed after the new archive has been saved
completely. The new archive is created under the same name as the original one, so
while the operation runs, both exist side by side; they are told apart by their
archive IDs, as the new archive gets a different archive ID.
.sp
With \fB\-\-target\fP the original archive is not replaced, instead a new archive is created.
.sp
@@ -150,7 +152,7 @@ consider archives older than (now \- TIMESPAN), e.g., 7d or 12m.
consider archives newer than (now \- TIMESPAN), e.g., 7d or 12m.
.TP
.BI \-\-target \ TARGET
create a new archive with the name ARCHIVE, do not replace existing archive
create a new archive with the name TARGET, do not replace existing archive
.TP
.BI \-\-comment \ COMMENT
add a comment text to the archive
@@ -162,7 +164,7 @@ manually specify the archive creation date/time (yyyy\-mm\-ddThh:mm:ss[(+|\-)HH:
select compression algorithm, see the output of the \(dqborg help compression\(dq command for details.
.TP
.BI \-\-chunker\-params \ PARAMS
rechunk using given chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, NC_LEVEL) or \fIdefault\fP to use the chunker defaults. default: do not rechunk
rechunk using given chunker parameters: buzhash,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE or buzhash64,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE,NC_LEVEL or fastcdc,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,NC_LEVEL or \fIdefault\fP to use the chunker defaults. default: do not rechunk
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
@@ -170,26 +172,33 @@ rechunk using given chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH
.sp
.EX
# Create a backup with fast, low compression
$ borg create archive /some/files \-\-compression lz4
# Then recompress it — this might take longer, but the backup has already completed,
# so there are no inconsistencies from a long\-running backup job.
$ borg recreate \-a archive \-\-recompress \-\-compression zlib,9
$ borg create archive files \-\-compression lz4
# Then recompress the data already stored in the repository — this might take longer,
# but the backup has already completed, so there are no inconsistencies from a
# long\-running backup job. Note that recompressing existing repository data is the
# job of \(dqborg repo\-compress\(dq, not of \(dqborg recreate\(dq.
$ borg repo\-compress \-\-compression zlib,9 \-\-stats
Recompression stats:
Packs: 2 total, 2 rewritten.
Objects: 5 total, 2 recompressed, 0 already had the desired compression, 3 kept as\-is (recompression brings no gain).
Repository size: 301.59 kB before, 301.53 kB after, shrunk by 60 B.
# Remove unwanted files from all archives in a repository.
# Note the relative path for the \-\-exclude option — archives only contain relative paths.
$ borg recreate \-\-exclude home/icke/Pictures/drunk_photos
# Change the archive comment
$ borg create \-\-comment \(dqThis is a comment\(dq archivename ~
# Change the archive comment. Note that recreate writes a new archive,
# so the archive fingerprint changes.
$ borg create \-\-comment \(dqThis is a comment\(dq archivename files
$ borg info \-a archivename
Name: archivename
Fingerprint: ...
Archive name: archivename
Archive fingerprint: 6cfecdd4e963bbe150c08169407de0353a4c5f2f90221646a9ebb0ce9be2529a
Comment: This is a comment
\&...
$ borg recreate \-\-comment \(dqThis is a better comment\(dq \-a archivename
$ borg info \-a archivename
Name: archivename
Fingerprint: ...
Archive name: archivename
Archive fingerprint: 259b5302a8de9c889fb4915fe5df128f6c22776966db2dc3c7d3c8e741bf45b6
Comment: This is a better comment
\&...
.EE
docs/man/borg-rename.1
+4 -3
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-rename" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-rename" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-rename \- Rename an existing archive.
.SH SYNOPSIS
@@ -58,11 +58,12 @@ specify the new archive name
.EX
$ borg create archivename ~
$ borg repo\-list
archivename Mon, 2016\-02\-15 19:50:19
516c2a16 Sat, 2026\-08\-29 14:39:58 +0200 archivename tw MacBook\-Pro
# renaming rewrites the archive metadata, so the archive ID changes:
$ borg rename archivename newname
$ borg repo\-list
newname Mon, 2016\-02\-15 19:50:19
3aaef11e Sat, 2026\-08\-29 14:39:58 +0200 newname tw MacBook\-Pro
.EE
.UNINDENT
.UNINDENT
docs/man/borg-repo-compress.1
+1 -1
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-repo-compress" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-repo-compress" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-repo-compress \- Repository (re-)compression.
.SH SYNOPSIS
docs/man/borg-repo-create.1
+3 -3
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-repo-create" "1" "2026-08-26" "" "borg backup tool"
.TH "borg-repo-create" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-repo-create \- Creates a new, empty repository.
.SH SYNOPSIS
@@ -68,8 +68,8 @@ Derive a \(dqkey encryption key\(dq from your passphrase
.IP 4. 3
Encrypt and sign the key with the key encryption key
.IP 5. 3
Store the encrypted borg key inside the repository directory (in the repo config).
This is why it is essential to use a secure passphrase.
Store the encrypted borg key in the repository (as an object in the \fBkeys/\fP
namespace of the store). This is why it is essential to use a secure passphrase.
.IP 6. 3
Encrypt and sign your backups to prevent anyone from reading or forging them unless they
have the key and know the passphrase. Make sure to keep a backup of
docs/man/borg-repo-delete.1
+7 -6
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-repo-delete" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-repo-delete" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-repo-delete \- Deletes a repository.
.SH SYNOPSIS
@@ -57,7 +57,7 @@ do not change the repository
output a verbose list of archives
.TP
.B \-\-force
force deletion of corrupted archives; use \fB\-\-force \-\-force\fP if a single \fB\-\-force\fP does not work.
do not ask for confirmation, just delete the repository. this also works if the repository is damaged to a point where its archives can not be listed anymore.
.TP
.B \-\-cache\-only
delete only the local cache for the given repository
@@ -72,10 +72,11 @@ keep the local security info when deleting a repository
.EX
# delete the whole repository and the related local cache:
$ borg repo\-delete
You requested to DELETE the repository completely *including* all archives it contains:
repo Mon, 2016\-02\-15 19:26:54
root\-2016\-02\-15 Mon, 2016\-02\-15 19:36:29
newname Mon, 2016\-02\-15 19:50:19
You requested to DELETE the following repository completely *including* 2 archives it contains:
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
Repository ID: e7046adda9b2a76bb4fac8d707ab7dc12a836391c8c3612cc12d461e713c5bc1
Location: /path/to/repo
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
Type \(aqYES\(aq if you understand this and want to continue: YES
.EE
.UNINDENT
docs/man/borg-repo-info.1
+6 -9
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-repo-info" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-repo-info" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-repo-info \- Show repository information.
.SH SYNOPSIS
@@ -52,15 +52,12 @@ format output as JSON
.sp
.EX
$ borg repo\-info
Repository ID: 0e85a7811022326c067acb2a7181d5b526b7d2f61b34470fb8670c440a67f1a9
Location: /Users/tw/w/borg/path/to/repo
Repository ID: 0a2744f216526be75ae14a5fa5b123127bb218558219f6203e09e4f220e45903
Location: /path/to/repo
Repository version: 4
Encrypted: Yes (repokey, aes256\-ocb, sha256)
Cache: /Users/tw/.cache/borg/0e85a7811022326c067acb2a7181d5b526b7d2f61b34470fb8670c440a67f1a9
Security dir: /Users/tw/.config/borg/security/0e85a7811022326c067acb2a7181d5b526b7d2f61b34470fb8670c440a67f1a9
Original size: 152.14 MB
Deduplicated size: 30.38 MB
Unique chunks: 654
Total chunks: 3302
Security directory: /home/user/.local/share/borg/security/0a2744f216526be75ae14a5fa5b123127bb218558219f6203e09e4f220e45903
Cache: /home/user/.cache/borg/0a2744f216526be75ae14a5fa5b123127bb218558219f6203e09e4f220e45903
.EE
.UNINDENT
.UNINDENT
docs/man/borg-repo-list.1
+27 -17
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-repo-list" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-repo-list" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-repo-list \- List the archives contained in a repository.
.SH SYNOPSIS
@@ -50,7 +50,7 @@ only print the archive IDs, nothing else
repository is Borg 1.x
.TP
.BI \-\-format \ FORMAT
specify format for archive listing (default: \(dq{archive:<36} {time} [{id}]{NL}\(dq)
specify format for archive listing (default: \(dq{id:.8} {time} {archive:<15} {tags:<10} {username:<10} {hostname:<10} {comment:.40}{NL}\(dq)
.TP
.B \-\-json
Format output as JSON. The form of \fB\-\-format\fP is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text.
@@ -91,12 +91,12 @@ consider only soft\-deleted archives.
.sp
.EX
$ borg repo\-list
151b1a57 Mon, 2024\-09\-23 22:57:11 +0200 docs tw MacBook\-Pro this is a comment
3387a079 Thu, 2024\-09\-26 09:07:07 +0200 scripts tw MacBook\-Pro
ca774425 Thu, 2024\-09\-26 10:05:23 +0200 scripts tw MacBook\-Pro
ba56c4a5 Thu, 2024\-09\-26 10:12:45 +0200 src tw MacBook\-Pro
7567b79a Thu, 2024\-09\-26 10:15:07 +0200 scripts tw MacBook\-Pro
21ab3600 Thu, 2024\-09\-26 10:15:17 +0200 docs tw MacBook\-Pro
76fcb5c7 Sat, 2026\-08\-29 14:36:22 +0200 docs tw MacBook\-Pro this is a comment
19356ae3 Sat, 2026\-08\-29 14:36:23 +0200 scripts tw MacBook\-Pro
7dd5756a Sat, 2026\-08\-29 14:36:23 +0200 scripts tw MacBook\-Pro
99b712ef Sat, 2026\-08\-29 14:36:23 +0200 src tw MacBook\-Pro
7698cd9e Sat, 2026\-08\-29 14:36:24 +0200 scripts tw MacBook\-Pro
f49f8762 Sat, 2026\-08\-29 14:36:24 +0200 docs tw MacBook\-Pro
\&...
.EE
.UNINDENT
@@ -118,8 +118,9 @@ ArchiveBar
# {VAR:NUMBER} \- pad to NUMBER columns.
# Strings are left\-aligned, numbers are right\-aligned.
# Note: time columns except \(ga\(gaisomtime\(ga\(ga, \(ga\(gaisoctime\(ga\(ga and \(ga\(gaisoatime\(ga\(ga cannot be padded.
$ borg repo\-list \-\-format \(aq{archive:36} {time} [{id}]{NL}\(aq /path/to/repo
# Note: the time keys (time, start, end) can not be padded \- for them, the
# format spec is a strftime format string, e.g. {time:%Y\-%m\-%d}.
$ borg repo\-list \-\-format \(aq{archive:36} {time} [{id}]{NL}\(aq
ArchiveFoo Thu, 2021\-12\-09 10:22:28 [0b8e9...3b274]
\&...
.EE
@@ -127,13 +128,22 @@ ArchiveFoo Thu, 2021\-12\-09 10:22:28 [0b8e9...3b274]
.UNINDENT
.sp
The following keys are always available:
\- NEWLINE: OS dependent line separator
\- NL: alias of NEWLINE
\- NUL: NUL character for creating print0 / xargs \-0 like output
\- SPACE: space character
\- TAB: tab character
\- CR: carriage return character
\- LF: line feed character
.INDENT 0.0
.IP \(bu 2
NEWLINE: OS dependent line separator
.IP \(bu 2
NL: alias of NEWLINE
.IP \(bu 2
NUL: NUL character for creating print0 / xargs \-0 like output
.IP \(bu 2
SPACE: space character
.IP \(bu 2
TAB: tab character
.IP \(bu 2
CR: carriage return character
.IP \(bu 2
LF: line feed character
.UNINDENT
.sp
Keys available only when listing archives in a repository:
.INDENT 0.0
docs/man/borg-repo-space.1
+1 -1
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-repo-space" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-repo-space" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-repo-space \- Manages reserved space in the repository.
.SH SYNOPSIS
docs/man/borg-serve.1
+20 -5
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-serve" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-serve" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-serve \- Starts in server mode. This command is usually not used manually.
.SH SYNOPSIS
@@ -56,7 +56,9 @@ Please note that, in legacy mode, \fIborg serve\fP does not support providing a
repository via the \fI\-\-repo\fP option or the \fIBORG_REPO\fP environment variable \- it is the
borg client that specifies the repository to use.
.sp
The \-\-permissions option enforces repository permissions:
The \-\-permissions option enforces repository permissions. It only applies to
\fB\-\-rest\fP mode; in legacy mode it is ignored, because legacy (borg 1.x) repositories
have no permission system:
.INDENT 0.0
.IP \(bu 2
\fIall\fP: All permissions are granted. (Default; the permissions system is not used.)
@@ -91,7 +93,7 @@ Restrict repository access to PATH. Can be specified multiple times to allow the
Restrict repository access. Only the repository located at PATH (no subdirectories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike \fB\-\-restrict\-to\-path\fP, subdirectories are not accessible; PATH must point directly to a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there.
.TP
.B \-\-permissions
Set repository permission mode. Overrides BORG_REPO_PERMISSIONS environment variable.
(with \-\-rest) set repository permission mode. Overrides BORG_REPO_PERMISSIONS environment variable.
.UNINDENT
.SH EXAMPLES
.sp
@@ -107,8 +109,18 @@ such as \fB\-\-verbose\fP, \fB\-\-info\fP, \fB\-\-debug\fP, \fB\-\-debug\-topic\
.IP \(bu 2
\fB\-\-lock\-wait\fP to allow the client to control how long to wait before
giving up and aborting the operation when another process is holding a lock.
.IP \(bu 2
\fB\-\-backend\fP to allow the client to choose \fIwhich\fP repository it wants to
use (see \fBborg serve \-\-rest\fP). The forced command keeps pinning the
restrictions: the client\-given backend is validated against
\fB\-\-restrict\-to\-path\fP / \fB\-\-restrict\-to\-repository\fP\&.
.UNINDENT
.sp
Notably, \fB\-\-rest\fP is \fInot\fP in the allowlist, so the forced command pins the
mode (current \fBrest://\fP repositories vs. legacy Borg 1.x repositories), and
neither are \fB\-\-restrict\-to\-path\fP, \fB\-\-restrict\-to\-repository\fP, \fB\-\-umask\fP
and \fB\-\-permissions\fP\&.
.sp
Environment variables (such as BORG_XXX) contained in the original
command sent by the client are \fInot\fP interpreted, but ignored. If BORG_XXX environment
variables should be set on the \fBborg serve\fP side, then these must be set in system\-specific
@@ -120,12 +132,15 @@ locations like \fB/etc/environment\fP or in the forced command itself (example b
# Allow an SSH keypair to run only borg, and only have access to /path/to/repo.
# Use key options to disable unneeded and potentially dangerous SSH functionality.
# This will help to secure an automated remote backup system.
# \-\-rest serves a current (rest://) repository; without it, a legacy Borg 1.x
# repository would be served. The client supplies \-\-backend FILE:<path>,
# which is validated against \-\-restrict\-to\-path.
$ cat ~/.ssh/authorized_keys
command=\(dqborg serve \-\-restrict\-to\-path /path/to/repo\(dq,restrict ssh\-rsa AAAAB3[...]
command=\(dqborg serve \-\-rest \-\-restrict\-to\-path /path/to/repo\(dq,restrict ssh\-rsa AAAAB3[...]
# Specify repository permissions for an SSH keypair.
$ cat ~/.ssh/authorized_keys
command=\(dqborg serve \-\-permissions=read\-only\(dq,restrict ssh\-rsa AAAAB3[...]
command=\(dqborg serve \-\-rest \-\-permissions=read\-only\(dq,restrict ssh\-rsa AAAAB3[...]
# Set a BORG_XXX environment variable on the \(dqborg serve\(dq side
$ cat ~/.ssh/authorized_keys
docs/man/borg-tag.1
+1 -1
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-tag" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-tag" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-tag \- Manage tags.
.SH SYNOPSIS
docs/man/borg-transfer.1
+56 -9
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-transfer" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-transfer" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-transfer \- archives transfer from other repository, optionally upgrade data format
.SH SYNOPSIS
@@ -46,13 +46,56 @@ the same COMPRESSION mode as in the SRC_REPO \- borg will use that COMPRESSION f
any case) and keep data compressed \(dqas is\(dq (saves time as no data compression is needed).
.sp
If you want to globally change compression while transferring archives to the DST_REPO,
give \fB\-\-compress=WANTED_COMPRESSION \-\-recompress=always\fP\&.
give \fB\-\-compression=WANTED_COMPRESSION \-\-recompress=always\fP\&.
.sp
The default is to transfer all archives.
.sp
You could use the misc. archive filter options to limit which archives it will
transfer, e.g. using the \fB\-a\fP option. This is recommended for big
repositories with multiple data sets to keep the runtime per invocation lower.
.SS Incremental transfer
.sp
Transfer only copies what is missing in the DST_REPO, so you can run the same command
repeatedly (e.g. from a cron job) to keep DST_REPO up to date \- each run will only
transfer what was added to SRC_REPO since the previous run.
.sp
This works on two levels:
.INDENT 0.0
.IP \(bu 2
archive level: if the DST_REPO already has an archive with the same name and timestamp
(or the same name and archive ID), that archive is skipped and borg prints
\(dqarchive is already present in destination repo, skipping.\(dq.
.IP \(bu 2
chunk level: for archives that are copied, only the chunks not yet present in the
DST_REPO are read from the SRC_REPO and stored \- deduplication works against
everything transferred before.
.UNINDENT
.sp
The archive filter options can be used as usual, so multiple invocations with different
filters are fine, e.g.:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
borg \-\-repo=DST_REPO transfer \-\-other\-repo=SRC_REPO \-a \(aqsh:daily\-*\(aq
borg \-\-repo=DST_REPO transfer \-\-other\-repo=SRC_REPO \-a \(aqsh:myserver\-*\(aq
.EE
.UNINDENT
.UNINDENT
.sp
Some things to keep in mind:
.INDENT 0.0
.IP \(bu 2
Interrupting a transfer is safe: an archive only becomes visible in the DST_REPO after
it was copied completely, so an interrupted archive is simply transferred again by the
next run. The chunks stored by the interrupted run are reused, so the retry is cheap \-
unless you run \fBborg compact\fP on the DST_REPO in between, which would remove the
chunks that are not (yet) referenced by an archive.
.IP \(bu 2
Transfer only adds archives, it never deletes any. If you want old archives to expire
in the DST_REPO, run \fBborg prune\fP (and \fBborg compact\fP) against the DST_REPO
separately.
.UNINDENT
.SS General purpose archive transfer
.sp
Transfer borg2 archives into a related other borg2 repository:
@@ -83,11 +126,11 @@ borg \-\-repo=DST_REPO repo\-create \-\-encryption=DST_ENC \-\-other\-repo=SRC_R
# to continue using lz4 compression as you did in SRC_REPO:
borg \-\-repo=DST_REPO transfer \-\-other\-repo=SRC_REPO \-\-from\-borg1 \e
\-\-compress=lz4 \-\-recompress=never
\-\-compression=lz4 \-\-recompress=never
# alternatively, to recompress everything to zstd,3:
borg \-\-repo=DST_REPO transfer \-\-other\-repo=SRC_REPO \-\-from\-borg1 \e
\-\-compress=zstd,3 \-\-recompress=always
\-\-compression=zstd,3 \-\-recompress=always
# to re\-chunk using different chunker parameters:
borg \-\-repo=DST_REPO transfer \-\-other\-repo=SRC_REPO \e
@@ -120,7 +163,7 @@ select compression algorithm, see the output of the \(dqborg help compression\(d
recompress data chunks according to \fIMODE\fP and \fB\-\-compression\fP\&. Possible modes are \fIalways\fP: recompress unconditionally; and \fInever\fP: do not recompress (faster: re\-uses compressed data chunks w/o change).If no MODE is given, \fIalways\fP will be used. Not passing \-\-recompress is equivalent to \(dq\-\-recompress never\(dq.
.TP
.BI \-\-chunker\-params \ PARAMS
rechunk using given chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, NC_LEVEL) or \fIdefault\fP to use the chunker defaults. default: do not rechunk
rechunk using given chunker parameters: buzhash,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE or buzhash64,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE,NC_LEVEL or fastcdc,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,NC_LEVEL or \fIdefault\fP to use the chunker defaults. default: do not rechunk
.UNINDENT
.SS Archive filters
.INDENT 0.0
@@ -157,7 +200,9 @@ locations and passphrases first:
.INDENT 3.5
.sp
.EX
export BORG_REPO=ssh://borg2@borgbackup/./tests/b20
# The destination is a Borg 2 repository: use a rest:// (or local) location,
# ssh:// is only supported for the legacy Borg 1.x source repository.
export BORG_REPO=rest://borg2@borgbackup/tests/b20
export BORG_PASSPHRASE=\(aqyour\-borg2\-repo\-passphrase\(aq
export BORG_OTHER_REPO=ssh://borg2@borgbackup/./tests/b1x
export BORG_OTHER_PASSPHRASE=\(aqyour\-borg1\-repo\-passphrase\(aq
@@ -180,7 +225,8 @@ export BORG_OTHER_PASSPHRASE=\(aqyour\-borg1\-repo\-passphrase\(aq
# between old archives (copied with borg transfer) and future ones.
# The AEAD cipher does not matter (everything must be re\-encrypted and
# re\-authenticated anyway); you could also choose chacha20\-poly1305.
$ borg repo\-create \-e aes256\-ocb
# \-\-from\-borg1 is required so the other repository is opened as a Borg 1.x repository.
$ borg repo\-create \-\-from\-borg1 \-e aes256\-ocb
# 2. Check what and how much it would transfer:
$ borg transfer \-\-from\-borg1 \-\-dry\-run
@@ -211,7 +257,8 @@ $ borg transfer \-\-from\-borg1 \-\-dry\-run
# use for all future Borg 2.0 archives.
# The AEAD cipher does not matter (everything must be re\-encrypted and
# re\-authenticated anyway); you could also choose \-e chacha20\-poly1305 \-i blake3.
$ borg repo\-create \-e aes256\-ocb \-i blake3
# \-\-from\-borg1 is required so the other repository is opened as a Borg 1.x repository.
$ borg repo\-create \-\-from\-borg1 \-e aes256\-ocb \-i blake3
$ export CHUNKER_PARAMS=\(dqfastcdc,19,23,21,2\(dq
# 2. Check what and how much it would transfer:
@@ -239,7 +286,7 @@ On \fBmacOS\fP, Borg 1.x stored key files in \fB~/.config/borg/keys/\fP,
but Borg 2 defaults to \fB~/Library/Application Support/borg/keys/\fP\&.
.sp
On \fBWindows\fP, Borg 1.x used XDG\-style paths (e.g. \fB~/.config/borg/keys/\fP),
while Borg 2 defaults to \fBC:\eUsers\e<user>\eAppData\eRoaming\eborg\ekeys\e\fP\&.
while Borg 2 defaults to \fBC:\eUsers\e<user>\eAppData\eLocal\eborg\eborg\ekeys\e\fP\&.
.sp
If Borg 2 cannot find your key file, you have several options:
.INDENT 0.0
docs/man/borg-umount.1
+5 -5
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-umount" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-umount" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-umount \- Unmounts the FUSE filesystem.
.SH SYNOPSIS
@@ -74,9 +74,9 @@ $ borg umount /tmp/mymountpoint
# and provides a versioned view on files.
$ borg mount \-o versions /tmp/mymountpoint
$ ls \-l /tmp/mymountpoint/home/user/doc.txt/
total 24
\-rw\-rw\-r\-\- 1 user group 12357 Aug 26 21:19 doc.cda00bc9.txt
\-rw\-rw\-r\-\- 1 user group 12204 Aug 26 21:04 doc.fa760f28.txt
total 47
\-rw\-r\-\-r\-\- 1 user group 12167 Aug 28 23:14 doc.00001.txt
\-rw\-r\-\-r\-\- 1 user group 11444 Aug 28 23:15 doc.00002.txt
$ borg umount /tmp/mymountpoint
# Archive filters are supported.
@@ -86,7 +86,7 @@ $ borg mount \-o versions \-\-match\-archives \(aqsh:*\-my\-home\(aq \-\-last 10
# Exclusion options are supported.
# These can speed up mounting and lower memory needs significantly.
$ borg mount /path/to/repo /tmp/mymountpoint only/that/path
$ borg mount \-r /path/to/repo /tmp/mymountpoint only/that/path
$ borg mount \-\-exclude \(aq...\(aq /tmp/mymountpoint
.EE
.UNINDENT
docs/man/borg-undelete.1
+2 -2
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-undelete" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-undelete" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-undelete \- Undeletes archives.
.SH SYNOPSIS
@@ -48,7 +48,7 @@ undeleted.
.sp
You can undelete multiple archives by specifying a match pattern using
the \fB\-\-match\-archives PATTERN\fP option (for more information on these
patterns, see \fIborg_patterns\fP).
patterns, see \(dqborg help match\-archives\(dq).
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
docs/man/borg-version.1
+10 -7
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-version" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-version" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-version \- Displays the Borg client and server versions.
.SH SYNOPSIS
@@ -49,13 +49,13 @@ Examples:
.INDENT 3.5
.sp
.EX
# local repository (client uses 1.4.0 alpha version)
$ borg version /mnt/backup
1.4.0a / 1.4.0a
# local repository
$ borg \-r /mnt/backup version
2.0.0 / 2.0.0
# legacy remote repository (client uses 1.4.0 alpha, server uses 1.2.7 release)
$ borg version \-\-from\-borg1 ssh://borg@borgbackup:repo
1.4.0a / 1.2.7
# legacy remote repository (client uses 2.0.0, server uses 1.4.5 release)
$ borg \-r ssh://borg@borgbackup/repo version \-\-from\-borg1
2.0.0 / 1.4.5
.EE
.UNINDENT
.UNINDENT
@@ -72,6 +72,9 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
.TP
.B \-\-json
format output as JSON
.TP
.B \-\-from\-borg1
repository is Borg 1.x
.UNINDENT
.SH SEE ALSO
.sp
docs/man/borg-webdav.1
+1 -1
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-webdav" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-webdav" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-webdav \- Serve archive contents via a read-only WebDAV / HTTP server on localhost.
.SH SYNOPSIS
docs/man/borg-with-lock.1
+1 -1
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-with-lock" "1" "2026-08-23" "" "borg backup tool"
.TH "borg-with-lock" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg-with-lock \- Runs a user-specified command with the repository lock held.
.SH SYNOPSIS
docs/man/borg.1
+351 -83
View File
@@ -29,7 +29,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg" "1" "2026-08-26" "" "borg backup tool"
.TH "borg" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borg \- deduplicating and encrypting backup tool
.SH SYNOPSIS
@@ -97,26 +97,37 @@ size (the amount of unique data not shared with other archives):
.EX
Repository: /path/to/repo
Archive name: docs
Archive fingerprint: bcd1b53f9b4991b7afc2b339f851b7ffe3c6d030688936fe4552eccc1877718d
Time (start): Sat, 2022\-06\-25 20:21:43
Time (end): Sat, 2022\-06\-25 20:21:43
Duration: 0.07 seconds
Utilization of maximum archive size: 0%
Number of files: 699
Original size: 31.14 MB
Deduplicated size: 502 B
Archive fingerprint: 74efb3f0c9c05f8b7c822ba859919b480578a3457fd4965c2cee64fbdb631262
Time (nominal): Fri, 2026\-08\-28 12:24:24 +0200
Time (start): Fri, 2026\-08\-28 12:24:24 +0200
Time (end): Fri, 2026\-08\-28 12:24:24 +0200
Duration: 0.008 seconds
Number of files: 100
Original size: 1.99 MB
Deduplicated size: 703 B
Time spent in hashing: 0.000 seconds
Time spent in chunking: 0.000 seconds
Added files: 1
Unchanged files: 99
Modified files: 0
Error files: 0
Files changed while reading: 0
\&...
.EE
.UNINDENT
.UNINDENT
.sp
(some more lines with statistics about the repository store accesses follow)
.IP 4. 3
List all archives in the repository:
List all archives in the repository (the first column is the beginning of the
archive ID):
.INDENT 3.0
.INDENT 3.5
.sp
.EX
$ borg \-r /path/to/repo repo\-list
docs Sat, 2022\-06\-25 20:21:14 [b80e24d2...b179f298]
docs Sat, 2022\-06\-25 20:21:43 [bcd1b53f...1877718d]
3affe017 Fri, 2026\-08\-28 12:24:10 +0200 docs user machine
74efb3f0 Fri, 2026\-08\-28 12:24:24 +0200 docs user machine
.EE
.UNINDENT
.UNINDENT
@@ -126,9 +137,9 @@ List the contents of the first archive:
.INDENT 3.5
.sp
.EX
$ borg \-r /path/to/repo list aid:b80e24d2
drwxr\-xr\-x user group 0 Mon, 2016\-02\-15 18:22:30 home/user/Documents
\-rw\-r\-\-r\-\- user group 7961 Mon, 2016\-02\-15 18:22:30 home/user/Documents/Important.doc
$ borg \-r /path/to/repo list aid:3affe017
drwxr\-xr\-x user group 0 Fri, 2026\-08\-28 12:22:30 +0200 home/user/Documents
\-rw\-r\-\-r\-\- user group 7961 Fri, 2026\-08\-28 12:22:30 +0200 home/user/Documents/Important.doc
\&...
.EE
.UNINDENT
@@ -139,7 +150,7 @@ Restore the first archive by extracting the files relative to the current direct
.INDENT 3.5
.sp
.EX
$ borg \-r /path/to/repo extract aid:b80e24d2
$ borg \-r /path/to/repo extract aid:3affe017
.EE
.UNINDENT
.UNINDENT
@@ -149,15 +160,17 @@ Delete the first archive (please note that this does \fBnot\fP free repository d
.INDENT 3.5
.sp
.EX
$ borg \-r /path/to/repo delete aid:b80e24d2
$ borg \-r /path/to/repo delete aid:3affe017
.EE
.UNINDENT
.UNINDENT
.sp
Be careful if you use an archive NAME (and not an archive ID), as it might match multiple archives.
Always use \fB\-\-dry\-run\fP and \fB\-\-list\fP first!
If you use an archive NAME (and not an archive ID), Borg will abort if the name matches multiple
archives (as with the two \fIdocs\fP archives here); use \fBaid:<archive\-id>\fP to delete one specific
archive, or \fB\-a PATTERN\fP to delete multiple archives. Always use \fB\-\-dry\-run\fP and \fB\-\-list\fP first!
.IP 8. 3
Recover disk space by compacting the segment files in the repository:
Recover disk space by removing objects that are not referenced by any
archive any more:
.INDENT 3.0
.INDENT 3.5
.sp
@@ -182,7 +195,7 @@ get other informational messages.
.SS Positional Arguments and Options: Order matters
.sp
Borg only supports taking options (\fB\-s\fP and \fB\-\-progress\fP in the example)
either to the left or to the right of all positional arguments (\fBrepo::archive\fP and \fBpath\fP
either to the left or to the right of all positional arguments (\fBarchive\fP and \fBpath\fP
in the example), but not in between them:
.INDENT 0.0
.INDENT 3.5
@@ -208,7 +221,9 @@ This is due to a problem in the argparse module: \%<https://\:bugs\:.python\:.or
Also, paths like \fB~/path/to/repo\fP or \fB~other/path/to/repo\fP work (this is
expanded by your shell).
.sp
Note: You may also prepend \fBfile://\fP to a filesystem path to use URL style.
Note: You may also prepend \fBfile://\fP to an absolute filesystem path to use URL
style, e.g. \fBfile:///abs/path/to/repo\fP\&. This only works for absolute paths —
\fBfile://rel/path\fP is rejected; use a plain relative path (see above) instead.
.sp
Note: UNC paths (\fB//server/share/path\fP, \fB\e\eserver\eshare\epath\fP) are not
supported — mount the share (on Windows: map it to a drive letter, e.g.
@@ -218,21 +233,46 @@ supported — mount the share (on Windows: map it to a drive letter, e.g.
.sp
\fBrest://user@host:port//abs/path/to/repo\fP — absolute path
.sp
\fBrest://user@host:port/rel/path/to/repo\fP — path relative to the current directory
\fBrest://user@host:port/rel/path/to/repo\fP — path relative to the remote login directory
.sp
\fBRemote repositories\fP accessed via SSH \%<user@\:host> (legacy borg RPC protocol):
.sp
\fBssh://user@host:port//abs/path/to/repo\fP — absolute path
.sp
\fBssh://user@host:port/rel/path/to/repo\fP — path relative to the current directory
\fBssh://user@host:port/rel/path/to/repo\fP — path relative to the remote login directory
.sp
For current (non\-legacy) repositories, \fBssh://\fP is rejected; use \fBrest://\fP
instead, which can also tunnel over ssh (see above). \fBssh://\fP remains available
only for legacy borg 1.x repositories, e.g. via
\fBborg transfer \-\-from\-borg1 \-\-other\-repo ssh://...\fP\&.
.sp
\fBRemote repositories\fP accessed via SFTP:
.sp
\fBsftp://user@host:port//abs/path/to/repo\fP — absolute path
.sp
\fBsftp://user@host:port/rel/path/to/repo\fP — path relative to the current directory
\fBsftp://user@host:port/rel/path/to/repo\fP — path relative to the remote login directory
.sp
For SSH and SFTP URLs, the \fBuser@\fP and \fB:port\fP parts are optional.
For REST, SSH and SFTP URLs, the \fBuser@\fP and \fB:port\fP parts are optional, but the
path is required: a URL without one, e.g. \fBrest://host\fP or \fBrest://host/\fP, is
rejected. Mind the difference between one and two slashes after the host: one slash
means a path relative to the directory the remote login lands in (usually the remote
user\(aqs home directory), two slashes mean an absolute path.
.sp
\fBRemote repositories\fP accessed directly via HTTP(S), talking to a borgstore REST
server:
.sp
\fBhttp://host:port\fP — plain HTTP
.sp
\fBhttps://user:password@host:port\fP — HTTPS, optionally with credentials embedded in the URL
.sp
For \fBhttp://\fP and \fBhttps://\fP URLs, \fBuser:password@\fP and \fB:port\fP are optional.
Authentication is HTTP Basic auth: credentials come from the URL if given, otherwise
from the \fBBORGSTORE_REST_USERNAME\fP / \fBBORGSTORE_REST_PASSWORD\fP environment
variables; prefer \fBhttps://\fP over \fBhttp://\fP whenever credentials are used, since
Basic auth sends them on every request. A URL path after the host is optional and,
unlike \fBrest://\fP, is not a remote filesystem path — it does not follow the
one\-vs\-two\-slash rule above and is only needed to reach the server through a reverse
proxy mounted below a sub\-path.
.sp
\fBRemote repositories\fP accessed via rclone:
.sp
@@ -253,7 +293,7 @@ If you frequently need the same repository URL, it is a good idea to set the
.INDENT 3.5
.sp
.EX
export BORG_REPO=\(aqssh://user@host:port/rel/path/to/repo\(aq
export BORG_REPO=\(aqrest://user@host:port/rel/path/to/repo\(aq
.EE
.UNINDENT
.UNINDENT
@@ -273,6 +313,45 @@ Archive names must not contain the \fB/\fP (slash) character. For simplicity,
also avoid spaces or other characters that have special meaning to the
shell or in a filesystem (\fBborg mount\fP uses the archive name as a directory
name).
.\" This file is the man page variant of docs/usage/usage_general.rst.inc and must
.\" not define the labels that variant defines - otherwise Sphinx warns about
.\" duplicate labels. archive-specification.rst.inc carries its label inside the
.\" file, so skip that line here.
.
.SS Specifying an archive
.sp
How to refer to an archive depends on whether you use archive series or not.
.sp
\fBBy ID:\fP if you use archive series, many or all archives will have the same name, thus
you need to refer to a single archive by its archive ID (see \fBborg repo\-list\fP
output):
.INDENT 0.0
.INDENT 3.5
.sp
.EX
borg info aid:f7dea078
.EE
.UNINDENT
.UNINDENT
.sp
The \fBaid:\fP prefix does a prefix match on the archive ID (the hex representation
of the archive fingerprint). You only need to give enough hex digits to uniquely
identify the archive. This is useful when archive names are ambiguous or when
you want to refer to an archive by its immutable ID.
.sp
\fBBy name:\fP if you don\(aqt use archive series, but do it old\-style by giving every archive
a unique name, you can refer to an archive by its name:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
borg info my\-backup\-202512312359
.EE
.UNINDENT
.UNINDENT
.sp
For more details on archive matching patterns (including shell\-style globs,
regular expressions, and matching by user/host/tags), see \fIborg_match\-archives\fP\&.
.SS Logging
.sp
Borg writes all log output to stderr by default. However, output on stderr does
@@ -396,6 +475,106 @@ or generic warning (rc 1) code instead (like Borg 1 did), set the
\fBBORG_EXIT_CODES=legacy\fP environment variable.
.sp
For a list of all specific error and warning codes, see \fImsgid\fP\&.
.SS Configuration Precedence
.INDENT 0.0
.INDENT 3.5
From lowest to highest:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP 1. 3
Defaults defined in the source code.
.IP 2. 3
Default config file (\fB$BORG_CONFIG_DIR/default.yaml\fP).
.IP 3. 3
\fB\-\-config\fP file(s) (in the order given).
.IP 4. 3
Full config environment variable: (\fBBORG_CONFIG\fP).
.IP 5. 3
Environment variables (e.g. \fBBORG_LOG_LEVEL\fP).
.IP 6. 3
Command\-line arguments in order left to right (might include config files).
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Configuration files
.sp
Borg supports reading options from YAML configuration files. This is
implemented via jsonargparse \%<https://\:jsonargparse\:.readthedocs\:.io/>
and works for all options that can also be set on the command line.
.INDENT 0.0
.TP
.B Default configuration file
\fB$BORG_CONFIG_DIR/default.yaml\fP is loaded automatically on every Borg
invocation if it exists. You do not need to pass \fB\-\-config\fP explicitly
for this file.
.TP
.B \fB\-\-config PATH\fP
Load additional options from the YAML file at \fIPATH\fP\&.
Options in this file take precedence over the default config file but are
overridden by explicit command\-line arguments. This option can be used
multiple times, with later files overriding earlier ones.
.TP
.B \fB\-\-print_config\fP
Print the current effective configuration (all options in YAML format) to
stdout and exit. This reflects the merged result of the default config
file, any \fB\-\-config\fP file, environment variables, and command\-line
arguments. The output can be used as a starting point for a config file.
.sp
\fB\-\-print_config\fP is a common option, so it must be given \fIbefore\fP the
subcommand name — the subcommand\(aqs own options still show up in the output.
.TP
.B File format
Config files are YAML documents. Top\-level keys are option names
(without leading \fB\-\-\fP and with \fB\-\fP replaced by \fB_\fP).
Nested keys correspond to subcommands.
.sp
Example \fBdefault.yaml\fP:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
# apply to all borg commands:
log_level: info
show_rc: true
# options specific to \(dqborg create\(dq:
create:
compression: zstd,3
stats: true
.EE
.UNINDENT
.UNINDENT
.sp
The top\-level keys set options that are common to all commands (equivalent
to placing them before the subcommand on the command line). Keys nested
under a subcommand name (e.g. \fBcreate:\fP) are only applied when that
subcommand is invoked.
.sp
\fBborgfs\fP reads the same config files, but as it has no subcommands, it uses
the top\-level keys and the keys of the \fBmount:\fP section (\fBborgfs\fP is the
\fBborg mount\fP command, and its keys win over the top\-level ones); all other
subcommand sections are ignored.
.UNINDENT
.sp
\fBNote:\fP
.INDENT 0.0
.INDENT 3.5
\fB\-\-print_config\fP shows the merged effective configuration and is a
convenient way to check what values Borg will actually use, and to
generate contents for your borg config file(s):
.INDENT 0.0
.INDENT 3.5
.sp
.EX
borg \-\-repo /backup/main \-\-print_config create \-\-compression zstd,3
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Environment Variables
.\" IMPORTANT: this file is auto-generated from borg's built-in help, do not edit!
.
@@ -417,6 +596,10 @@ Similar to BORG_REPO, but gives the default for \fB\-\-other\-repo\fP\&.
When set, use the value to answer the passphrase question for encrypted repositories.
It is used when a passphrase is needed to access an encrypted repo as well as when a new
passphrase should be initially set when initializing an encrypted repo.
BORG_PASSPHRASE, BORG_PASSCOMMAND and BORG_PASSPHRASE_FD are mutually exclusive:
if more than one of them is set, borg refuses to guess and aborts with
\(dqMore than one passphrase environment variable is set\(dq. The same applies to the
\fBBORG_OTHER_*\fP variants (which are a separate, independent group).
See also BORG_NEW_PASSPHRASE.
.TP
.B BORG_PASSCOMMAND (and BORG_OTHER_PASSCOMMAND)
@@ -425,7 +608,7 @@ passphrase question for encrypted repositories.
It is used when a passphrase is needed to access an encrypted repo as well as when a new
passphrase should be initially set when initializing an encrypted repo. Note that the command
is executed without a shell. So variables, like \fB$HOME\fP will work, but \fB~\fP won\(aqt.
If BORG_PASSPHRASE is also set, it takes precedence.
Mutually exclusive with BORG_PASSPHRASE and BORG_PASSPHRASE_FD, see there.
See also BORG_NEW_PASSPHRASE.
.TP
.B BORG_PASSPHRASE_FD (and BORG_OTHER_PASSPHRASE_FD)
@@ -434,12 +617,12 @@ from. Programs starting borg may choose to open an anonymous pipe
and use it to pass a passphrase. This is safer than passing via
BORG_PASSPHRASE, because on some systems (e.g. Linux) environment
can be examined by other processes.
If BORG_PASSPHRASE or BORG_PASSCOMMAND are also set, they take precedence.
Mutually exclusive with BORG_PASSPHRASE and BORG_PASSCOMMAND, see there.
.TP
.B BORG_NEW_PASSPHRASE
When set, use the value to answer the passphrase question when a \fBnew\fP passphrase is asked for.
This variable is checked first. If it is not set, BORG_PASSPHRASE and BORG_PASSCOMMAND will also
be checked.
This variable is checked first. If it is not set, BORG_PASSPHRASE, BORG_PASSCOMMAND and
BORG_PASSPHRASE_FD are checked (in that order).
Main use case for this is to fully automate \fBborg key change\-passphrase\fP\&.
.TP
.B BORG_DISPLAY_PASSPHRASE
@@ -553,6 +736,42 @@ cache entries for backup sources other than the current sources.
When set to a numeric value, this determines the maximum \(dqtime to live\(dq for the files cache
entries (default: 2). The files cache is used to determine quickly whether a file is unchanged.
.TP
.B BORG_STORE_CACHE
When set, borg keeps a local writethrough cache of the repository\(aqs \fBpacks/\fP
namespace: on a cache miss the whole pack is fetched once and later reads of the
objects inside that pack are served from the cache. Use this for slow or
high\-latency repositories.
Set it to \fB1\fP to use \fB$BORG_CACHE_DIR/storecache\fP, or to a directory path to
use that directory (it is created if it does not exist). Packs are named by
content hash, so one cache directory can safely hold packs of multiple repositories.
If it is not set, no such caching happens.
.TP
.B BORG_PACK_CACHE_SIZE
When set to a numeric value, limit the pack cache to that many bytes.
Only has an effect if BORG_STORE_CACHE is set.
.TP
.B BORG_PACK_MAX_SIZE
When set to a numeric value, cap packs (the repository objects that batch up many
chunks, see the internals documentation about pack files) at that many bytes
instead of the default of 50000000.
Smaller packs mean more (but smaller) repository objects and more
fine\-grained uploads; bigger packs mean fewer objects and fewer stores.
.TP
.B BORG_PACK_MAX_COUNT
When set to a numeric value, cap packs at that many objects per pack.
If BORG_PACK_MAX_SIZE is not also set, packs are then bound by count only.
.TP
.B BORG_PACK_ASYNC
When set to \fBno\fP, disable the background thread that stores a finished pack
while the next one is being assembled, and store packs synchronously instead.
This is mainly a debugging aid.
.TP
.B BORG_PACK_TRACE
When set to \fByes\fP, print one\-character lifecycle markers of the background
pack store\-thread to stderr (\fB<\fP thread started, \fBH\fP hashing starts,
\fBS\fP storing starts, \fB>\fP thread finished). This is a debugging aid to
visualize how pack stores overlap with the assembly of the next pack.
.TP
.B BORG_ASSERT_ID
Comma\-separated list of the places where borg shall verify that a chunk\(aqs content matches
its chunk id (\fBchunkid == id_hash(content)\fP) after decrypting and decompressing it.
@@ -594,15 +813,17 @@ more afterwards. (Re\-chunking in \fBborg transfer\fP is covered by \fBtransfer\
An unknown place name is an error. An empty value (\fBBORG_ASSERT_ID=\fP) verifies at none of
these places, but still where borg always verifies (see below).
.sp
Why \fBread\fP is not in the default: for encrypted repositories (all the AEAD ciphersuites),
the chunk id is part of the AEAD additional authenticated data, so a successful decryption
already proves that a holder of the repository key deliberately stored exactly this
ciphertext for exactly this chunk id. A malicious or buggy \fBrepository\fP can therefore not
swap, splice or substitute objects, whether the id is verified on read or not. What the id
check adds is the detection of chunks whose content does not match their id, which only a
malicious or compromised \fBborg client that had your borg key\fP could have written (e.g. to
poison future deduplication). If that is in your threat model \- e.g. because some machines
writing into the repository are not fully trusted \- add \fBread\fP to the list:
Why \fBread\fP is not in the default: in the keyed modes, the envelope already authenticates
every read \- the AEAD tag for the encrypted ciphersuites, the MAC for the (unencrypted)
\fBauthenticated\-*\fP modes \- and the chunk id is part of what that tag is computed over. So
a successful decryption resp. tag check already proves that a holder of the borg key
deliberately stored exactly this payload for exactly this chunk id, and a malicious or
buggy \fBrepository\fP can not swap, splice or substitute objects, whether the id is
verified on read or not. What the id check adds is the detection of chunks whose content
does not match their id, which only a malicious or compromised \fBborg client that had
your borg key\fP could have written (e.g. to poison future deduplication). If that is in
your threat model \- e.g. because some machines writing into the repository are not fully
trusted \- add \fBread\fP to the list:
.INDENT 7.0
.INDENT 3.5
.sp
@@ -622,9 +843,10 @@ Independent of this variable, borg always verifies the chunk id:
in \fBborg check \-\-verify\-data\fP\&. That audit is what makes not verifying elsewhere
defensible, so it is not configurable (there is no \fBverify_data\fP place name).
.IP \(bu 2
for \fBauthenticated\fP and \fBnone\fP mode repositories: there is no AEAD there, so the id
check \fIis\fP the read path\(aqs integrity check and switching it off would remove it
completely. Same for reading borg 1.x repositories (\fBborg transfer\fP).
for \fBnone\-*\fP mode repositories: they have no key, so nothing authenticates a read
there and their unkeyed checksums only detect accidental corruption. The id check is
therefore not optional there: it happens at every place, whatever this variable says.
Same for reading borg 1.x repositories (\fBborg transfer\fP).
.UNINDENT
.TP
.B BORG_BLAKE3_MT_THRESHOLD
@@ -724,6 +946,13 @@ given order, e.g.:
\fBnone\fP: do not try to load an implementation
.UNINDENT
.TP
.B BORG_MOUNT_DATA_CACHE_ENTRIES
Number of decrypted file content chunks \fBborg mount\fP and \fBborg webdav\fP keep
in an in\-memory cache, so that the many small, sequential reads a mounted file
system does for a big file do not re\-fetch and re\-decrypt the same chunk over and
over (default: the cpu count). Additional memory usage can be up to the chunk size
times this number.
.TP
.B BORG_SELFTEST
This can be used to influence borg\(aqs built\-in self\-tests. The default is to execute the tests
at the beginning of each borg command invocation.
@@ -753,9 +982,12 @@ caused EROFS. You will need this to make archives from volume shadow copies
in WSL1 (Windows Subsystem for Linux 1).
.TP
.B authenticated_no_key
Work around a lost passphrase or key for an \fBauthenticated\-*\fP mode repository
(these are only authenticated, but not encrypted).
If the key is missing in the repository config, add \fBkey = anything\fP there.
Work around a lost passphrase or a lost borg key for an \fBauthenticated\-*\fP
mode repository (these are only authenticated, but not encrypted).
If a borg key is found \- an object below \fBkeys/\fP in the repository (repokey)
resp. a key file in the keys directory (keyfile) \- it is not unlocked, so the
passphrase does not matter. If no borg key is found at all, borg proceeds
anyway, without any key material.
.sp
Without the key, borg can not verify anything that needs it: neither the
authentication tag of the repository objects nor the chunk ids. It therefore
@@ -779,12 +1011,13 @@ After you have extracted all data you need, you MUST delete the repository:
.INDENT 3.5
.sp
.EX
BORG_WORKAROUNDS=authenticated_no_key borg delete repo
BORG_WORKAROUNDS=authenticated_no_key borg repo\-delete \-\-repo repo
.EE
.UNINDENT
.UNINDENT
.sp
Now you can init a fresh repo. Make sure you do not use the workaround any more.
Now you can create a fresh repository with \fBborg repo\-create\fP\&. Make sure you
do not use the workaround any more.
.UNINDENT
.UNINDENT
.TP
@@ -794,6 +1027,10 @@ Now you can init a fresh repo. Make sure you do not use the workaround any more.
.B BORG_CHECK_FORMAT
Giving the default value for \fBborg check \-\-format=X\fP\&.
.TP
.B BORG_DIFF_FORMAT
Giving the default value for \fBborg diff \-\-format=X\fP\&.
Note: \fBborg diff \-\-content\-only\fP uses its own format and ignores this.
.TP
.B BORG_FIND_FORMAT
Giving the default value for \fBborg find \-\-format=X\fP\&.
.TP
@@ -811,6 +1048,12 @@ Giving the format of the archive directory names when \fBborg mount\fP or
\fBborg webdav\fP show a whole repository, default: \fB{name}\fP\&. The placeholders
are the ones of \fBborg repo\-list \-\-format\fP; names that are not unique get
\fB\-{id:.8}\fP appended. See \fBborg mount \-\-help\fP\&.
.TP
.B BORG_JSON_INDENT
Indentation of the \fB\-\-json\fP output (default: \fB4\fP).
A number gives that many spaces per nesting level (\fB0\fP still puts every item on
its own line), \fBnone\fP gives compact single\-line JSON, and any other value is used
as the literal indent string (e.g. a tab or the empty string).
.UNINDENT
.TP
.B Some automatic \(dqanswerers\(dq (if set, they automatically answer confirmation questions):
@@ -840,13 +1083,15 @@ default directory locations. This means that default paths are \fBplatform\-spec
.IP \(bu 2
Linux: XDG Base Directory Specification paths are used (e.g. \fB~/.config/borg\fP,
\fB~/.cache/borg\fP, \fB~/.local/share/borg\fP). \fBXDG_*\fP environment variables are
honoured (see \%<https://\:specifications\:.freedesktop\:.org/\:basedir-spec/\:0\:.6/\:ar01s03\:.html>).
honoured (see \%<https://\:specifications\:.freedesktop\:.org/\:basedir/\:latest/>).
.IP \(bu 2
macOS: native macOS directories are used by default (e.g. \fB~/Library/Application Support/borg\fP,
\fB~/Library/Caches/borg\fP). \fBXDG_*\fP environment variables are honoured if set.
.IP \(bu 2
Windows: Windows AppData directories are used (e.g. \fBC:\eUsers\e<user>\eAppData\eRoaming\eborg\fP,
\fBC:\eUsers\e<user>\eAppData\eLocal\eborg\fP). \fBXDG_*\fP environment variables are \fBnot\fP honoured.
Windows: local (not roaming) Windows AppData directories are used, e.g.
\fBC:\eUsers\e<user>\eAppData\eLocal\eborg\eborg\fP\&. \fBborg\fP appears twice in that path because
borg does not give platformdirs a separate \(dqapp author\(dq name, so it defaults to the app name.
\fBXDG_*\fP environment variables are \fBnot\fP honoured.
.UNINDENT
.sp
On all platforms, you can override each directory individually using the specific environment
@@ -859,10 +1104,10 @@ Default directory locations by platform (when no \fBBORG_*\fP environment variab
.sp
.EX
Directory Linux macOS Windows
Config ~/.config/borg ~/Library/Application Support/borg %APPDATA%\eborg
Cache ~/.cache/borg ~/Library/Caches/borg %LOCALAPPDATA%\eborg\eCache
Data ~/.local/share/borg ~/Library/Application Support/borg %LOCALAPPDATA%\eborg
Runtime /run/user/<uid>/borg ~/Library/Caches/TemporaryItems/borg %TEMP%\eborg
Config ~/.config/borg ~/Library/Application Support/borg %LOCALAPPDATA%\eborg\eborg
Cache ~/.cache/borg ~/Library/Caches/borg %LOCALAPPDATA%\eborg\eborg\eCache
Data ~/.local/share/borg ~/Library/Application Support/borg %LOCALAPPDATA%\eborg\eborg
Runtime /run/user/<uid>/borg ~/Library/Caches/TemporaryItems/borg %LOCALAPPDATA%\eTemp\eborg\eborg
Keys <config_dir>/keys <config_dir>/keys <config_dir>\ekeys
Security <data_dir>/security <data_dir>/security <data_dir>\esecurity
.EE
@@ -871,7 +1116,8 @@ Security <data_dir>/security <data_dir>/security <data_dir
.INDENT 7.0
.TP
.B BORG_BASE_DIR
Defaults to \fB$HOME\fP or \fB~$USER\fP or \fB~\fP (in that order).
Not set by default \- then the platform\-specific directories shown in the table above
are used.
If you want to move all borg\-specific folders to a custom path at once, all you need to do is
to modify \fBBORG_BASE_DIR\fP: the other paths for cache, config etc. will adapt accordingly
(assuming you didn\(aqt set them to a different custom value).
@@ -939,21 +1185,29 @@ for details.
.UNINDENT
.TP
.B Building:
These are only read by \fBsetup.py\fP while building borg\(aqs C extensions. Each
\fBBORG_*_PREFIX\fP variable names the install prefix of a library that borg links
against: if it is set, \fB$PREFIX/include\fP and \fB$PREFIX/lib\fP are used unconditionally.
If it is not set, the library is located via pkg\-config, and if that does not find it
either, the build fails \- there is no bundled fallback implementation.
.INDENT 7.0
.TP
.B BORG_OPENSSL_NAME
Defines the subdirectory name for OpenSSL (setup.py).
.TP
.B BORG_OPENSSL_PREFIX
Adds given OpenSSL header file directory to the default locations (setup.py).
Prefix of the OpenSSL installation to build libcrypto against.
On Windows, the libraries are expected in \fB$PREFIX\fP itself rather than in
\fB$PREFIX/lib\fP\&. On OpenBSD, this defaults to \fB/usr/local\fP, pkg\-config is not
used and libcrypto is linked statically (borg needs AES\-OCB via the EVP API, which
LibreSSL does not have).
.TP
.B BORG_LIBACL_PREFIX
Adds given prefix directory to the default locations. If an \(aqinclude/acl/libacl.h\(aq is found
Borg will be linked against the system libacl instead of a bundled implementation. (setup.py)
.B BORG_OPENSSL_NAME
OpenBSD only: the OpenSSL flavour to use, i.e. the \fBinclude/\fP and \fBlib/\fP
subdirectory name below \fBBORG_OPENSSL_PREFIX\fP (default: \fBeopenssl35\fP).
.TP
.B BORG_LIBLZ4_PREFIX
Adds given prefix directory to the default locations. If a \(aqinclude/lz4.h\(aq is found Borg
will be linked against the system liblz4 instead of a bundled implementation. (setup.py)
Prefix of the liblz4 installation to build against.
.TP
.B BORG_LIBACL_PREFIX
Linux only: prefix of the libacl installation to build against.
.UNINDENT
.TP
.B Automatic option environment variables:
@@ -1006,12 +1260,17 @@ repository, e.g., zfs, btrfs, ext4, apfs.
Borg now uses the \fBborgstore\fP package to implement the key/value store it
uses for the repository.
.sp
It currently uses the \fBfile:\fP store (posixfs backend) either with a local
directory or via SSH and a remote \fBborg serve\fP agent using borgstore on the
remote side.
For a local repository (or a locally mounted network filesystem) it uses the
\fBfile:\fP store (posixfs backend). For a remote repository it uses the \fBrest:\fP
store, talking to a \fBborg serve \-\-rest\fP process on the remote side (which in
turn uses borgstore there). Other backends (\fBsftp:\fP, \fBrclone:\fP, \fBs3:\fP/
\fBb2:\fP) do not need a filesystem on the repository side at all.
.sp
This means that it will store each chunk into a separate filesystem file
(for more details, see the \fBborgstore\fP project).
Borg does not store each chunk as a separate store object. It groups many chunks
into \fIpack files\fP of up to about 50 MB and stores each pack as one object; reading
a single chunk is a partial read at a known offset inside its pack. Thus, the
repository holds far fewer objects than it has chunks (see \fIpacks\fP in the
Internals chapter for the details).
.sp
This has some pros and cons (compared to legacy Borg 1.x segment files):
.sp
@@ -1020,13 +1279,10 @@ Pros:
.IP \(bu 2
Simplicity and better maintainability of the Borg code.
.IP \(bu 2
Sometimes faster, less I/O, better scalability: e.g., borg compact can just
remove unused chunks by deleting a single file and does not need to read
and rewrite segment files to free space.
.IP \(bu 2
In the future, easier to adapt to other kinds of storage:
borgstore\(aqs backends are quite simple to implement.
\fBsftp:\fP and \fBrclone:\fP backends already exist, others might be easy to add.
The repository is just a key/value store, so it is easy to adapt to other kinds
of storage: borgstore\(aqs backends are quite simple to implement.
\fBsftp:\fP, \fBrclone:\fP and \fBs3:\fP/\fBb2:\fP backends already exist, others might
be easy to add.
.IP \(bu 2
Parallel repository access with less locking is easier to implement.
.UNINDENT
@@ -1034,9 +1290,9 @@ Parallel repository access with less locking is easier to implement.
Cons:
.INDENT 0.0
.IP \(bu 2
The repository filesystem will have to deal with a large number of files (there
are provisions in borgstore against having too many files in a single directory
by using a nested directory structure).
Individual chunks cannot be deleted from a pack file; \fBborg compact\fP can only
remove a pack once none of its chunks are referenced any more, so space is not
always reclaimed immediately.
.IP \(bu 2
Greater filesystem space overhead (depends on the allocation block size — modern
filesystems like zfs are rather clever here, using a variable block size).
@@ -1048,7 +1304,7 @@ Sometimes slower, due to less sequential and more random access operations.
To display quantities, Borg takes care of respecting the
usual conventions of scale. Disk sizes are displayed in decimal \%<https://\:en\:.wikipedia\:.org/\:wiki/\:Decimal>, using powers of ten (so
\fBkB\fP means 1000 bytes). For memory usage, binary prefixes \%<https://\:en\:.wikipedia\:.org/\:wiki/\:Binary_prefix> are used, and are
indicated using the IEC binary prefixes \%<https://\:en\:.wikipedia\:.org/\:wiki/\:IEC_80000-13#\:Prefixes_for_binary_multiples>,
indicated using the IEC binary prefixes \%<https://\:en\:.wikipedia\:.org/\:wiki/\:Binary_prefix#\:IEC_standard_prefixes>,
using powers of two (so \fBKiB\fP means 1024 bytes).
.SS Date and Time
.sp
@@ -1100,14 +1356,26 @@ server to get the approximate resource usage.
.IP \(bu 2
\fBborg prune/borg delete archive:\fP quick, low CPU usage
.IP \(bu 2
\fBborg delete repo:\fP done on the server
\fBborg repo\-delete:\fP low CPU usage, it just removes the repository\(aqs objects
.IP \(bu 2
\fBborg compact:\fP medium CPU usage
.IP \(bu 2
\fBborg check:\fP medium CPU usage, but depends on options given
.UNINDENT
.sp
It will not use more than 100% of one CPU core as the code is currently single\-threaded.
Most of Borg is single\-threaded, but some parts do use more than one CPU core:
.INDENT 7.0
.IP \(bu 2
zstd compresses a chunk multi\-threaded by default (only for chunks of at
least 768 KiB, using at most 4 threads); see \fBBORG_ZSTD_MT_WORKERS\fP\&.
.IP \(bu 2
the BLAKE3 based id\-hash / MAC modes hash multi\-threaded for inputs from
256 KiB on; see \fBBORG_BLAKE3_MT_THRESHOLD\fP\&.
.IP \(bu 2
\fBborg create\fP hands each finished pack file to a background thread, so
hashing and storing a pack overlaps with processing the next one.
.UNINDENT
.sp
Especially higher zlib and lzma compression levels use significant amounts
of CPU cycles. Crypto might be cheap on the CPU (if hardware\-accelerated) or
expensive (if not).
docs/man/borgfs.1
+1 -1
View File
@@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borgfs" "1" "2026-08-28" "" "borg backup tool"
.TH "borgfs" "1" "2026-08-29" "" "borg backup tool"
.SH Name
borgfs \- Mounts an archive or an entire repository as a FUSE filesystem.
.SH SYNOPSIS
docs/usage/benchmark_cpu.rst.inc
+1 -1
View File
@@ -72,7 +72,7 @@ By default all benchmarks run. Give one or more of --chunking, --hashing,
Some algorithms use multiple threads only above a size threshold, so the
hashes and the compressors are measured at more than one buffer size: the
hashes at 64MiB (a borg pack) and 2MiB (a typical borg chunk), both above
hashes at 64MiB (roughly pack-sized) and 2MiB (a typical borg chunk), both above
blake3's threshold, the compressors at 2MiB and 128kiB, which is below
zstd's. Within a section every row processes the same total number of
bytes - 1 GiB, or 10 MiB for the compressors - so the throughput column is
docs/usage/benchmark_crud.rst.inc
+9 -6
View File
@@ -52,15 +52,16 @@ Description
This command benchmarks borg CRUD (create, read, update, delete) operations.
It creates input data below the given PATH and backs up this data into the given REPO.
The REPO must already exist (it could be a fresh empty repo or an existing repo, the
It creates input data below the given PATH and backs up this data into the repository
given via -r/--repo (or the BORG_REPO environment variable).
The repository must already exist (it could be a fresh empty repo or an existing repo, the
command will create / read / update / delete some archives named borg-benchmark-crud\* there.
Make sure you have free space there; you will need about 1 GB each (+ overhead).
If your repository is encrypted and borg needs a passphrase to unlock the key, use::
BORG_PASSPHRASE=mysecret borg benchmark crud REPO PATH
BORG_PASSPHRASE=mysecret borg -r REPO benchmark crud PATH
Measurements are done with different input file sizes and counts.
The file contents are very artificial (either all zero or all random),
@@ -81,9 +82,11 @@ U- == borg create (2nd archive creation of unchanged input files, measure files
U-Z- == needs to check the 2 all-zero chunks' existence in the repo.
U-R- == needs to check existence of a lot of different chunks in the repo.
D- == borg delete archive (delete last remaining archive, measure deletion + compaction)
D-Z- == few chunks to delete / few segments to compact/remove.
D-R- == many chunks to delete / many segments to compact/remove.
D- == borg delete archive (soft-delete the last remaining archive, measure deletion)
Deletion only removes the archive from the archives list, it does not free any
repository space - that is what borg compact does (not measured here).
D-Z- == all-zero files archive.
D-R- == random files archive.
Please note that there might be quite some variance in these measurements.
Try multiple measurements and having a otherwise idle machine (and network, if you use it).
docs/usage/check.rst.inc
+24 -15
View File
@@ -97,13 +97,18 @@ Description
The check command verifies the consistency of a repository and its archives.
It consists of two major steps:
1. Checking the consistency of the repository itself. This includes checking
the file magic headers, and both the metadata and data of all objects in
the repository. The read data is checked by size and hash. Bit rot and other
types of accidental damage can be detected this way. Running the repository
check can be split into multiple partial checks using ``--max-duration``.
When checking an ssh:// remote repository, please note that the checks run on
the server and do not cause significant network traffic.
1. Checking the consistency of the repository itself. The objects in the ``index/``
and ``packs/`` namespaces are named by the sha256 hash of their content, so such
an object is intact if and only if the hash of its content still equals its name.
The check verifies the (small) index objects first and, only if they are intact,
all packs. It also cross-checks the chunk index against the packs present in the
repository to detect referenced but missing packs. Bit rot and other types of
accidental damage can be detected this way, but as sha256 content-addressing is
not a MAC, this step does not detect tampering. Running the repository check can
be split into multiple partial checks using ``--max-duration``.
For rest:// repositories, the server computes the hashes, so the pack contents do
not have to travel over the network. For other remote backends, borg usually has
to read (download) the objects to hash them.
2. Checking consistency and correctness of the archive metadata and optionally
archive data (requires ``--verify-data``). This includes ensuring that the
@@ -111,7 +116,9 @@ It consists of two major steps:
all chunks referencing files (items) in the archive exist. This requires
reading archive and file metadata, but not data. To scan for archives whose
entries were lost from the archive directory, pass ``--find-lost-archives``.
It requires reading all data and is hence very time-consuming.
It has to look at the metadata of every object in the repository (only for the
archive metadata objects it finds that way, it also reads the object data), so
it is very time-consuming for big repositories.
To additionally cryptographically verify the file (content) data integrity,
pass ``--verify-data``, which is even more time-consuming.
@@ -146,11 +153,13 @@ verification per week. Partial repository checks run neither archive checks
nor repair mode, so ``--max-duration`` requires ``--repository-only`` and
cannot be combined with ``--archives-only`` or ``--repair``.
**Warning:** Please note that partial repository checks (i.e., running with
``--max-duration``) can only perform non-cryptographic checksum checks on the
repository files. Enabling partial repository checks excludes archive checks
for the same reason. Therefore, partial checks may be useful only with very large
repositories where a full check would take too long.
**Note:** A partial repository check verifies the repository files in exactly the
same way as a full repository check does - the difference is only how many of them
one run gets to. What a partial run does not do are the archive checks: because
``--max-duration`` requires ``--repository-only``, neither the archive metadata
checks nor the cryptographic data verification of ``--verify-data`` run. Partial
checks are therefore mostly useful for very large repositories where a full check
would take too long.
The ``--verify-data`` option will perform a full integrity verification of data,
which means reading the data from the repository, decrypting and decompressing it.
@@ -168,8 +177,8 @@ tells Borg to search for lost archive metadata. If Borg encounters any archive
metadata that does not match an archive directory entry (including
soft-deleted archives), it means that an entry was lost.
Unless ``borg compact`` is called, these archives can be fully restored with
``--repair``. Please note that ``--find-lost-archives`` must read a lot of
data from the repository and is thus very time-consuming. You cannot use
``--repair``. Please note that ``--find-lost-archives`` must look at every
object in the repository and is thus very time-consuming. You cannot use
``--find-lost-archives`` with ``--repository-only``.
You can influence how the archive part of the ``Analyzing archive ...`` output is
docs/usage/create.rst.inc
+8 -8
View File
@@ -39,7 +39,7 @@ borg create
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--stdin-mode M`` | set mode to M in archive for stdin data (default: 0660) |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--content-from-command`` | interpret PATH as a command and store its stdout. See also the section 'Reading from stdin' below. |
| | ``--content-from-command`` | interpret PATH as a command and store its stdout. See also the section 'Reading backup data from stdin' below. |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--paths-from-stdin`` | read DELIM-separated list of paths to back up from stdin. All control is external: it will back up all files given - no more, no less. |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -47,7 +47,7 @@ borg create
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--paths-from-shell-command`` | interpret PATH as shell command and treat its output as ``--paths-from-stdin`` |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--paths-delimiter DELIM`` | set path delimiter for ``--paths-from-stdin`` and ``--paths-from-command`` (default: ``\n``) |
| | ``--paths-delimiter DELIM`` | set path delimiter for ``--paths-from-stdin``, ``--paths-from-command`` and ``--paths-from-shell-command`` (default: ``\n``) |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
@@ -146,11 +146,11 @@ borg create
--stdin-user USER set user USER in archive for stdin data (default: do not store user/uid)
--stdin-group GROUP set group GROUP in archive for stdin data (default: do not store group/gid)
--stdin-mode M set mode to M in archive for stdin data (default: 0660)
--content-from-command interpret PATH as a command and store its stdout. See also the section 'Reading from stdin' below.
--content-from-command interpret PATH as a command and store its stdout. See also the section 'Reading backup data from stdin' below.
--paths-from-stdin read DELIM-separated list of paths to back up from stdin. All control is external: it will back up all files given - no more, no less.
--paths-from-command interpret PATH as command and treat its output as ``--paths-from-stdin``
--paths-from-shell-command interpret PATH as shell command and treat its output as ``--paths-from-stdin``
--paths-delimiter DELIM set path delimiter for ``--paths-from-stdin`` and ``--paths-from-command`` (default: ``\n``)
--paths-delimiter DELIM set path delimiter for ``--paths-from-stdin``, ``--paths-from-command`` and ``--paths-from-shell-command`` (default: ``\n``)
:ref:`common_options`
@@ -227,8 +227,8 @@ objects only once, under the path given first (like for any other root given twi
When specifying '-' as a path, borg will read data from standard input and create a
file named 'stdin' in the created archive from that data. In some cases, it is more
appropriate to use --content-from-command. See the section *Reading from stdin*
below for details.
appropriate to use --content-from-command. See the section
*Reading backup data from stdin* below for details.
The archive will consume almost no disk space for files or parts of files that
have already been stored in other archives.
@@ -406,6 +406,7 @@ Other flags used include:
- '+' = included, item would be backed up (if not in dry-run mode)
- '-' = excluded, item would not be / was not backed up
- 'i' = backup data was read from standard input (stdin)
- 'x' = skipped due to ``--exclude-dataless`` (file is flagged DATALESS)
- '?' = missing status code (if you see this, please file a bug report!)
Errors and (incomplete) archives
@@ -419,8 +420,7 @@ At the end of the backup, if there were any such issues, borg will exit with
a non-zero exit code (usually 1 for warnings).
**The archive is still saved even if warnings or errors occurred**, but it will
only contain the data borg was able to read successfully. It is like a
checkpoint (see below), but with a user-given name.
only contain the data borg was able to read successfully.
You should always check the backup logs and the exit code of the borg command.
docs/usage/delete.rst.inc
+1 -1
View File
@@ -95,4 +95,4 @@ When in doubt, use ``--dry-run --list`` to see what would be deleted.
You can delete multiple archives by specifying a match pattern using
the ``--match-archives PATTERN`` option (for more information on these
patterns, see :ref:`borg_patterns`).
patterns, see "borg help match-archives").
docs/usage/diff.rst.inc
+22 -13
View File
@@ -116,6 +116,7 @@ Examples:
...
The following keys are always available:
- NEWLINE: OS dependent line separator
- NL: alias of NEWLINE
- NUL: NUL character for creating print0 / xargs -0 like output
@@ -154,25 +155,33 @@ What is compared
For each matching item in both archives, Borg reports:
- Content changes: total added/removed bytes within files. If chunker parameters are comparable,
Borg compares chunk IDs quickly; otherwise, it compares the content.
- Metadata changes: user, group, mode, and other metadata shown inline, like
"[old_mode -> new_mode]" for mode changes. Use ``--content-only`` to suppress metadata changes.
- Added/removed items: printed as "added SIZE path" or "removed SIZE path".
Borg compares chunk IDs quickly; otherwise, it compares the content. In the latter case, borg
can only tell that a file was modified, not by how much: no byte counts are given for it, the
text output shows "modified: (can't get size)" instead.
- Metadata changes: user, group, mode, and other metadata shown inline as "[old -> new]", like
"[-rw-r--r-- -> -rwxr-xr-x]" for a mode change. Use ``--content-only`` to suppress metadata changes.
- Added/removed items: printed as "added: SIZE path" or "removed: SIZE path".
Output formats
++++++++++++++
The default (text) output shows one line per changed path, e.g.::
+135 B -252 B [ -rw-r--r-- -> -rwxr-xr-x ] path/to/file
modified: +23 B -5 B [-rwxr-xr-x -> -rw-r--r--] path/to/file
added: 4 B path/to/added-file
removed: 5 B path/to/removed-file
JSON Lines output (``--json-lines``) prints one JSON object per changed path, e.g.::
JSON Lines output (``--json-lines``) prints one JSON object per changed path, with a list of
change objects. Each change object has a "type" plus type-specific data: content changes
("added", "removed", "modified") carry "added"/"removed" byte counts - except for a
"modified" that was determined by comparing the content, which carries no counts at all;
metadata changes ("changed mode", "changed owner", "mtime", ...) carry the old and new
values as "item1" and "item2". Example::
{"path": "PATH", "changes": [
{"type": "modified", "added": BYTES, "removed": BYTES},
{"type": "mode", "old_mode": "-rw-r--r--", "new_mode": "-rwxr-xr-x"},
{"type": "added", "size": SIZE},
{"type": "removed", "size": SIZE}
]}
{"changes": [{"added": 23, "removed": 5, "type": "modified"}], "path": "path/to/file"}
{"changes": [{"type": "modified"}], "path": "path/to/other-file"}
{"changes": [{"item1": "-rw-r--r--", "item2": "-rwxr-xr-x", "type": "changed mode"}], "path": "some/file"}
{"changes": [{"added": 4, "removed": 0, "type": "added"}], "path": "path/to/added-file"}
{"changes": [{"added": 0, "removed": 5, "type": "removed"}], "path": "path/to/removed-file"}
Sorting
++++++++
@@ -192,4 +201,4 @@ Supported fields include:
Performance considerations
++++++++++++++++++++++++++
diff automatically detects whether the archives were created with the same chunker
parameters. If so, only chunk IDs are compared, which is very fast.
parameters. If so, only chunk IDs are compared, which is very fast.
docs/usage/find.rst.inc
+2 -1
View File
@@ -141,6 +141,7 @@ Examples:
{archivename} the archive name (the archives of a series all share the name).
The following keys are always available:
- NEWLINE: OS dependent line separator
- NL: alias of NEWLINE
- NUL: NUL character for creating print0 / xargs -0 like output
@@ -191,4 +192,4 @@ Keys available only when finding files in an archive:
- archiveid: internal ID of the archive
- archivename: name of the archive
- extra: prepends {target} with " -> " for soft links and " link to " for hard links
- extra: prepends {target} with " -> " for soft links and " link to " for hard links
docs/usage/general/environment.rst.inc
+29 -25
View File
@@ -186,15 +186,17 @@ General:
An unknown place name is an error. An empty value (``BORG_ASSERT_ID=``) verifies at none of
these places, but still where borg always verifies (see below).
Why ``read`` is not in the default: for encrypted repositories (all the AEAD ciphersuites),
the chunk id is part of the AEAD additional authenticated data, so a successful decryption
already proves that a holder of the repository key deliberately stored exactly this
ciphertext for exactly this chunk id. A malicious or buggy **repository** can therefore not
swap, splice or substitute objects, whether the id is verified on read or not. What the id
check adds is the detection of chunks whose content does not match their id, which only a
malicious or compromised **borg client that had your borg key** could have written (e.g. to
poison future deduplication). If that is in your threat model - e.g. because some machines
writing into the repository are not fully trusted - add ``read`` to the list::
Why ``read`` is not in the default: in the keyed modes, the envelope already authenticates
every read - the AEAD tag for the encrypted ciphersuites, the MAC for the (unencrypted)
``authenticated-*`` modes - and the chunk id is part of what that tag is computed over. So
a successful decryption resp. tag check already proves that a holder of the borg key
deliberately stored exactly this payload for exactly this chunk id, and a malicious or
buggy **repository** can not swap, splice or substitute objects, whether the id is
verified on read or not. What the id check adds is the detection of chunks whose content
does not match their id, which only a malicious or compromised **borg client that had
your borg key** could have written (e.g. to poison future deduplication). If that is in
your threat model - e.g. because some machines writing into the repository are not fully
trusted - add ``read`` to the list::
BORG_ASSERT_ID=read,repair,transfer,rechunk
@@ -206,9 +208,10 @@ General:
- in ``borg check --verify-data``. That audit is what makes not verifying elsewhere
defensible, so it is not configurable (there is no ``verify_data`` place name).
- for ``authenticated`` and ``none`` mode repositories: there is no AEAD there, so the id
check *is* the read path's integrity check and switching it off would remove it
completely. Same for reading borg 1.x repositories (``borg transfer``).
- for ``none-*`` mode repositories: they have no key, so nothing authenticates a read
there and their unkeyed checksums only detect accidental corruption. The id check is
therefore not optional there: it happens at every place, whatever this variable says.
Same for reading borg 1.x repositories (``borg transfer``).
BORG_BLAKE3_MT_THRESHOLD
When set to a numeric value, chunks of at least that many KiB get their id computed by
multi-threaded BLAKE3, smaller ones single-threaded (default: 256, i.e. 256KiB).
@@ -325,13 +328,12 @@ General:
in WSL1 (Windows Subsystem for Linux 1).
authenticated_no_key
Work around a lost passphrase for an ``authenticated-*`` mode repository
(these are only authenticated, but not encrypted).
Borg still has to find the repository's borg key - an object below ``keys/``
in the repository (repokey) resp. a key file in the keys directory (keyfile) -
but it does not unlock it any more, so the passphrase does not matter. If the
borg key itself is gone, this workaround does not help: borg then fails with
"No key entry found ...".
Work around a lost passphrase or a lost borg key for an ``authenticated-*``
mode repository (these are only authenticated, but not encrypted).
If a borg key is found - an object below ``keys/`` in the repository (repokey)
resp. a key file in the keys directory (keyfile) - it is not unlocked, so the
passphrase does not matter. If no borg key is found at all, borg proceeds
anyway, without any key material.
Without the key, borg can not verify anything that needs it: neither the
authentication tag of the repository objects nor the chunk ids. It therefore
@@ -399,8 +401,10 @@ Directories and files:
honoured (see https://specifications.freedesktop.org/basedir/latest/).
- macOS: native macOS directories are used by default (e.g. ``~/Library/Application Support/borg``,
``~/Library/Caches/borg``). ``XDG_*`` environment variables are honoured if set.
- Windows: Windows AppData directories are used (e.g. ``C:\Users\<user>\AppData\Roaming\borg``,
``C:\Users\<user>\AppData\Local\borg``). ``XDG_*`` environment variables are **not** honoured.
- Windows: local (not roaming) Windows AppData directories are used, e.g.
``C:\Users\<user>\AppData\Local\borg\borg``. ``borg`` appears twice in that path because
borg does not give platformdirs a separate "app author" name, so it defaults to the app name.
``XDG_*`` environment variables are **not** honoured.
On all platforms, you can override each directory individually using the specific environment
variables described below. You can also set ``BORG_BASE_DIR`` to force borg to use
@@ -409,10 +413,10 @@ Directories and files:
Default directory locations by platform (when no ``BORG_*`` environment variables are set)::
Directory Linux macOS Windows
Config ~/.config/borg ~/Library/Application Support/borg %APPDATA%\borg
Cache ~/.cache/borg ~/Library/Caches/borg %LOCALAPPDATA%\borg\Cache
Data ~/.local/share/borg ~/Library/Application Support/borg %LOCALAPPDATA%\borg
Runtime /run/user/<uid>/borg ~/Library/Caches/TemporaryItems/borg %TEMP%\borg
Config ~/.config/borg ~/Library/Application Support/borg %LOCALAPPDATA%\borg\borg
Cache ~/.cache/borg ~/Library/Caches/borg %LOCALAPPDATA%\borg\borg\Cache
Data ~/.local/share/borg ~/Library/Application Support/borg %LOCALAPPDATA%\borg\borg
Runtime /run/user/<uid>/borg ~/Library/Caches/TemporaryItems/borg %LOCALAPPDATA%\Temp\borg\borg
Keys <config_dir>/keys <config_dir>/keys <config_dir>\keys
Security <data_dir>/security <data_dir>/security <data_dir>\security
docs/usage/import-tar.rst.inc
+38 -38
View File
@@ -12,43 +12,43 @@ borg import-tar
.. class:: borg-options-table
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **positional arguments** |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``NAME`` | specify the archive name |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``TARFILE`` | input tar file. "-" to read from stdin instead. |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **options** |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--tar-filter`` | filter program to pipe data through |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-s``, ``--stats`` | print statistics for the created archive |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--list`` | output verbose list of items (files, dirs, ...) |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--filter STATUSCHARS`` | only display items with the given status characters |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--json`` | output stats as JSON (implies --stats) |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--ignore-zeros`` | ignore zero-filled blocks in the input tarball |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Archive options** |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--comment COMMENT`` | add a comment text to the archive |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--timestamp TIMESTAMP`` | manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory. |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--chunker-params PARAMS`` | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, NC_LEVEL). default: fastcdc,19,23,21,2 |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--digests ALGOS`` | compute these hash digests over the full content of each file and store them into the archive items. Comma-separated list of hash algorithm names, e.g. "blake3", or "none". default: none |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **positional arguments** |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``NAME`` | specify the archive name |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``TARFILE`` | input tar file. "-" to read from stdin instead. |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **options** |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--tar-filter`` | filter program to pipe data through |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-s``, ``--stats`` | print statistics for the created archive |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--list`` | output verbose list of items (files, dirs, ...) |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--filter STATUSCHARS`` | only display items with the given status characters |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--json`` | output stats as JSON (implies --stats) |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--ignore-zeros`` | ignore zero-filled blocks in the input tarball |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Archive options** |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--comment COMMENT`` | add a comment text to the archive |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--timestamp TIMESTAMP`` | manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory. |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--chunker-params PARAMS`` | specify the chunker parameters: buzhash,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE or buzhash64,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE,NC_LEVEL or fastcdc,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,NC_LEVEL. default: fastcdc,19,23,21,2 |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--digests ALGOS`` | compute these hash digests over the full content of each file and store them into the archive items. Comma-separated list of hash algorithm names, e.g. "blake3", or "none". default: none |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. raw:: html
@@ -81,7 +81,7 @@ borg import-tar
Archive options
--comment COMMENT add a comment text to the archive
--timestamp TIMESTAMP manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory.
--chunker-params PARAMS specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, NC_LEVEL). default: fastcdc,19,23,21,2
--chunker-params PARAMS specify the chunker parameters: buzhash,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE or buzhash64,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE,NC_LEVEL or fastcdc,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,NC_LEVEL. default: fastcdc,19,23,21,2
-C COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details.
--digests ALGOS compute these hash digests over the full content of each file and store them into the archive items. Comma-separated list of hash algorithm names, e.g. "blake3", or "none". default: none
docs/usage/key_import.rst.inc
+13 -8
View File
@@ -59,11 +59,16 @@ If the ``--paper`` option is given, the import will be an interactive
process in which each line is checked for plausibility before
proceeding to the next line. For this format PATH must not be given.
For repositories using keyfile encryption, the key file which ``borg key
import`` writes to depends on several factors. If the ``BORG_KEY_FILE``
environment variable is set and non-empty, ``borg key import`` creates
or overwrites that file named by ``$BORG_KEY_FILE``. Otherwise, ``borg
key import`` searches in the ``$BORG_KEYS_DIR`` directory for a key file
associated with the repository. If a key file is found in
``$BORG_KEYS_DIR``, ``borg key import`` overwrites it; otherwise, ``borg
key import`` creates a new key file in ``$BORG_KEYS_DIR``.
Where the imported key is stored is decided by ``--key-location``:
- ``repokey`` (the default): the key is stored **in the repository**, no local
key file is written.
- ``keyfile``: the key is stored in a local key file.
The key file that ``--key-location=keyfile`` writes to depends on several
factors. If the ``BORG_KEY_FILE`` environment variable is set and non-empty,
``borg key import`` creates or overwrites the file named by ``$BORG_KEY_FILE``.
Otherwise, ``borg key import`` searches the ``$BORG_KEYS_DIR`` directory for a
key file associated with the repository. If one is found there, ``borg key
import`` overwrites it; otherwise it creates a new key file in
``$BORG_KEYS_DIR``.
docs/usage/list.rst.inc
+2 -1
View File
@@ -109,6 +109,7 @@ Examples:
...
The following keys are always available:
- NEWLINE: OS dependent line separator
- NL: alias of NEWLINE
- NUL: NUL character for creating print0 / xargs -0 like output
@@ -188,4 +189,4 @@ Note: ``--sort-by`` needs to read all (matching) items into memory before it can
print anything, so listing a huge archive this way needs a lot of memory and
delays the first output line. Without ``--sort-by``, items are streamed and their
order is undefined. If memory usage is a problem, consider
``borg list --format ... | sort`` instead.
``borg list --format ... | sort`` instead.
docs/usage/mount.rst.inc
+6 -4
View File
@@ -147,8 +147,8 @@ still not unique get ``-{id:.8}`` appended.
On Linux, this can be prevented by remounting the mountpoint with the
``nosymfollow`` VFS mount option, for example:
borg mount <repo path> <mountpoint>
mount -o remount,nosymfollow <repo path> <mountpoint>
borg -r <repo path> mount <mountpoint>
mount -o remount,nosymfollow <mountpoint>
Alternatively, access the mounted archive from an appropriately isolated
environment (for example, a container or ``chroot``).
@@ -163,8 +163,10 @@ Performance tips:
- Only mount a specific archive, not the whole repository.
- Only mount specific paths in a specific archive, not the complete archive.
The command ``borgfs`` provides a wrapper for ``borg mount``. This can also be
used in fstab entries:
The command ``borgfs`` provides a wrapper for ``borg mount``. It is invoked as
``borgfs [REPOSITORY] MOUNTPOINT [PATH...]``, taking the repository as its first
positional argument (if it is not given, ``-r`` / ``BORG_REPO`` is used). This can
also be used in fstab entries:
``/path/to/repo /mnt/point fuse.borgfs defaults,noauto 0 0``
To allow a regular user to use fstab entries, add the ``user`` option:
docs/usage/prune.rst.inc
-12
View File
@@ -63,14 +63,6 @@ borg prune
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. 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 or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. raw:: html
@@ -112,10 +104,6 @@ borg prune
Archive filters
-a PATTERN, --match-archives PATTERN only consider archives matching all patterns. 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 or 12m.
--newer TIMESPAN consider archives newer than (now - TIMESPAN), e.g., 7d or 12m.
Description
docs/usage/recreate.rst.inc
+72 -70
View File
@@ -12,69 +12,69 @@ borg recreate
.. class:: borg-options-table
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **positional arguments** |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``PATH`` | paths to recreate; patterns are supported |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **options** |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--list`` | output verbose list of items (files, dirs, ...) |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--filter STATUSCHARS`` | only display items with the given status characters (listed in borg create --help) |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-n``, ``--dry-run`` | do not change anything |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-s``, ``--stats`` | print statistics at end |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Include/Exclude options** |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--pattern PATTERN`` | include/exclude paths matching PATTERN |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--patterns-from PATTERNFILE`` | read include/exclude patterns from PATTERNFILE, one per line |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--exclude-caches`` | exclude directories that contain a CACHEDIR.TAG file (https://www.bford.info/cachedir/spec.html) |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--exclude-if-present NAME`` | exclude directories that are tagged by containing a filesystem object with the given NAME |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--keep-exclude-tags`` | if tag objects are specified with ``--exclude-if-present``, do not omit the tag objects themselves from the backup archive |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Archive filters** — Archive filters can be applied to repository targets. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. See "borg help match-archives". |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--first N`` | consider the first N archives after other filters are applied |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--last N`` | consider the last N archives after other filters are applied |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--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 or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--target TARGET`` | create a new archive with the name ARCHIVE, do not replace existing archive |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--comment COMMENT`` | add a comment text to the archive |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--timestamp TIMESTAMP`` | manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--chunker-params PARAMS`` | rechunk using given chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, NC_LEVEL) or `default` to use the chunker defaults. default: do not rechunk |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **positional arguments** |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``PATH`` | paths to recreate; patterns are supported |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **options** |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--list`` | output verbose list of items (files, dirs, ...) |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--filter STATUSCHARS`` | only display items with the given status characters (listed in borg create --help) |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-n``, ``--dry-run`` | do not change anything |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-s``, ``--stats`` | print statistics at end |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Include/Exclude options** |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--pattern PATTERN`` | include/exclude paths matching PATTERN |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--patterns-from PATTERNFILE`` | read include/exclude patterns from PATTERNFILE, one per line |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--exclude-caches`` | exclude directories that contain a CACHEDIR.TAG file (https://www.bford.info/cachedir/spec.html) |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--exclude-if-present NAME`` | exclude directories that are tagged by containing a filesystem object with the given NAME |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--keep-exclude-tags`` | if tag objects are specified with ``--exclude-if-present``, do not omit the tag objects themselves from the backup archive |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Archive filters** — Archive filters can be applied to repository targets. |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archives matching all patterns. See "borg help match-archives". |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--first N`` | consider the first N archives after other filters are applied |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--last N`` | consider the last N archives after other filters are applied |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--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 or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g., 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--target TARGET`` | create a new archive with the name TARGET, do not replace existing archive |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--comment COMMENT`` | add a comment text to the archive |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--timestamp TIMESTAMP`` | manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory. |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--chunker-params PARAMS`` | rechunk using given chunker parameters: buzhash,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE or buzhash64,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE,NC_LEVEL or fastcdc,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,NC_LEVEL or `default` to use the chunker defaults. default: do not rechunk |
+-----------------------------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. raw:: html
@@ -119,11 +119,11 @@ borg recreate
--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 or 12m.
--newer TIMESPAN consider archives newer than (now - TIMESPAN), e.g., 7d or 12m.
--target TARGET create a new archive with the name ARCHIVE, do not replace existing archive
--target TARGET create a new archive with the name TARGET, do not replace existing archive
--comment COMMENT add a comment text to the archive
--timestamp TIMESTAMP manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory.
-C COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details.
--chunker-params PARAMS rechunk using given chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, NC_LEVEL) or `default` to use the chunker defaults. default: do not rechunk
--chunker-params PARAMS rechunk using given chunker parameters: buzhash,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE or buzhash64,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE,NC_LEVEL or fastcdc,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,NC_LEVEL or `default` to use the chunker defaults. default: do not rechunk
Description
@@ -144,8 +144,9 @@ the resulting archives will contain only files from those paths.
Note that all paths in an archive are relative, therefore absolute patterns/paths
will *not* match (``--exclude``, ``--exclude-from``, PATHs).
``--chunker-params`` will re-chunk all files in the archive, this can be
used to have upgraded Borg 0.xx archives deduplicate with Borg 1.x archives.
``--chunker-params`` will re-chunk all files in the archive. This can be used to
switch existing archives to different chunker parameters (or a different chunker
algorithm), so they deduplicate with archives created using these parameters.
**USE WITH CAUTION.**
Depending on the paths and patterns given, recreate can be used to
@@ -153,9 +154,10 @@ delete files from archives permanently.
When in doubt, use ``--dry-run --verbose --list`` to see how patterns/paths are
interpreted. See :ref:`list_item_flags` in ``borg create`` for details.
The archive being recreated is only removed after the operation completes. The
archive that is built during the operation exists at the same time at
"<ARCHIVE>.recreate". The new archive will have a different archive ID.
The archive being recreated is only removed after the new archive has been saved
completely. The new archive is created under the same name as the original one, so
while the operation runs, both exist side by side; they are told apart by their
archive IDs, as the new archive gets a different archive ID.
With ``--target`` the original archive is not replaced, instead a new archive is created.
docs/usage/repo-create.rst.inc
+2 -2
View File
@@ -84,8 +84,8 @@ Borg will:
2. Create a borg key (which contains some random secrets. See :ref:`key_files`).
3. Derive a "key encryption key" from your passphrase
4. Encrypt and sign the key with the key encryption key
5. Store the encrypted borg key inside the repository directory (in the repo config).
This is why it is essential to use a secure passphrase.
5. Store the encrypted borg key in the repository (as an object in the ``keys/``
namespace of the store). This is why it is essential to use a secure passphrase.
6. Encrypt and sign your backups to prevent anyone from reading or forging them unless they
have the key and know the passphrase. Make sure to keep a backup of
your key **outside** the repository - do not lock yourself out by
docs/usage/repo-delete.rst.inc
+18 -18
View File
@@ -12,23 +12,23 @@ borg repo-delete
.. class:: borg-options-table
+-------------------------------------------------------+--------------------------+------------------------------------------------------------------------------------------------------+
| **options** |
+-------------------------------------------------------+--------------------------+------------------------------------------------------------------------------------------------------+
| | ``-n``, ``--dry-run`` | do not change the repository |
+-------------------------------------------------------+--------------------------+------------------------------------------------------------------------------------------------------+
| | ``--list`` | output a verbose list of archives |
+-------------------------------------------------------+--------------------------+------------------------------------------------------------------------------------------------------+
| | ``--force`` | force deletion of corrupted archives; use ``--force --force`` if a single ``--force`` does not work. |
+-------------------------------------------------------+--------------------------+------------------------------------------------------------------------------------------------------+
| | ``--cache-only`` | delete only the local cache for the given repository |
+-------------------------------------------------------+--------------------------+------------------------------------------------------------------------------------------------------+
| | ``--keep-security-info`` | keep the local security info when deleting a repository |
+-------------------------------------------------------+--------------------------+------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-------------------------------------------------------+--------------------------+------------------------------------------------------------------------------------------------------+
+-------------------------------------------------------+--------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **options** |
+-------------------------------------------------------+--------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-n``, ``--dry-run`` | do not change the repository |
+-------------------------------------------------------+--------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--list`` | output a verbose list of archives |
+-------------------------------------------------------+--------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--force`` | do not ask for confirmation, just delete the repository. this also works if the repository is damaged to a point where its archives can not be listed anymore. |
+-------------------------------------------------------+--------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--cache-only`` | delete only the local cache for the given repository |
+-------------------------------------------------------+--------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--keep-security-info`` | keep the local security info when deleting a repository |
+-------------------------------------------------------+--------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-------------------------------------------------------+--------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. raw:: html
@@ -45,7 +45,7 @@ borg repo-delete
options
-n, --dry-run do not change the repository
--list output a verbose list of archives
--force force deletion of corrupted archives; use ``--force --force`` if a single ``--force`` does not work.
--force do not ask for confirmation, just delete the repository. this also works if the repository is damaged to a point where its archives can not be listed anymore.
--cache-only delete only the local cache for the given repository
--keep-security-info keep the local security info when deleting a repository
docs/usage/repo-list.rst.inc
+5 -3
View File
@@ -105,12 +105,14 @@ Examples:
# {VAR:NUMBER} - pad to NUMBER columns.
# Strings are left-aligned, numbers are right-aligned.
# Note: time columns except ``isomtime``, ``isoctime`` and ``isoatime`` cannot be padded.
$ borg repo-list --format '{archive:36} {time} [{id}]{NL}' /path/to/repo
# Note: the time keys (time, start, end) can not be padded - for them, the
# format spec is a strftime format string, e.g. {time:%Y-%m-%d}.
$ borg repo-list --format '{archive:36} {time} [{id}]{NL}'
ArchiveFoo Thu, 2021-12-09 10:22:28 [0b8e9...3b274]
...
The following keys are always available:
- NEWLINE: OS dependent line separator
- NL: alias of NEWLINE
- NUL: NUL character for creating print0 / xargs -0 like output
@@ -137,4 +139,4 @@ Keys available only when listing archives in a repository:
- username: username of user who created this archive
- size: size of this archive (data plus metadata, not considering compression and deduplication)
- nfiles: count of files in this archive
- nfiles: count of files in this archive
docs/usage/serve.rst.inc
+5 -3
View File
@@ -23,7 +23,7 @@ borg serve
+-------------------------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--restrict-to-repository PATH`` | Restrict repository access. Only the repository located at PATH (no subdirectories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path``, subdirectories are not accessible; PATH must point directly to a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there. |
+-------------------------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--permissions`` | Set repository permission mode. Overrides BORG_REPO_PERMISSIONS environment variable. |
| | ``--permissions`` | (with --rest) set repository permission mode. Overrides BORG_REPO_PERMISSIONS environment variable. |
+-------------------------------------------------------+-----------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
@@ -47,7 +47,7 @@ borg serve
--backend BACKEND_URL (with --rest) backend URL of the repository to serve, e.g. FILE:/path/to/repo.
--restrict-to-path PATH Restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all subdirectories is granted implicitly; PATH does not need to point directly to a repository.
--restrict-to-repository PATH Restrict repository access. Only the repository located at PATH (no subdirectories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path``, subdirectories are not accessible; PATH must point directly to a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there.
--permissions Set repository permission mode. Overrides BORG_REPO_PERMISSIONS environment variable.
--permissions (with --rest) set repository permission mode. Overrides BORG_REPO_PERMISSIONS environment variable.
:ref:`common_options`
@@ -74,7 +74,9 @@ Please note that, in legacy mode, `borg serve` does not support providing a spec
repository via the `--repo` option or the `BORG_REPO` environment variable - it is the
borg client that specifies the repository to use.
The --permissions option enforces repository permissions:
The --permissions option enforces repository permissions. It only applies to
``--rest`` mode; in legacy mode it is ignored, because legacy (borg 1.x) repositories
have no permission system:
- `all`: All permissions are granted. (Default; the permissions system is not used.)
- `no-delete`: Allow reading and writing; disallow deleting and overwriting data.
docs/usage/transfer.rst.inc
+5 -5
View File
@@ -27,7 +27,7 @@ borg transfer
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--recompress MODE`` | recompress data chunks according to `MODE` and ``--compression``. Possible modes are `always`: recompress unconditionally; and `never`: do not recompress (faster: re-uses compressed data chunks w/o change).If no MODE is given, `always` will be used. Not passing --recompress is equivalent to "--recompress never". |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--chunker-params PARAMS`` | rechunk using given chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, NC_LEVEL) or `default` to use the chunker defaults. default: do not rechunk |
| | ``--chunker-params PARAMS`` | rechunk using given chunker parameters: buzhash,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE or buzhash64,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE,NC_LEVEL or fastcdc,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,NC_LEVEL or `default` to use the chunker defaults. default: do not rechunk |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
@@ -71,7 +71,7 @@ borg transfer
--upgrader UPGRADER use the upgrader to convert transferred data (default: no conversion)
-C COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details.
--recompress MODE recompress data chunks according to `MODE` and ``--compression``. Possible modes are `always`: recompress unconditionally; and `never`: do not recompress (faster: re-uses compressed data chunks w/o change).If no MODE is given, `always` will be used. Not passing --recompress is equivalent to "--recompress never".
--chunker-params PARAMS rechunk using given chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, NC_LEVEL) or `default` to use the chunker defaults. default: do not rechunk
--chunker-params PARAMS rechunk using given chunker parameters: buzhash,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE or buzhash64,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,WINDOW_SIZE,NC_LEVEL or fastcdc,CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,NC_LEVEL or `default` to use the chunker defaults. default: do not rechunk
:ref:`common_options`
@@ -101,7 +101,7 @@ the same COMPRESSION mode as in the SRC_REPO - borg will use that COMPRESSION fo
any case) and keep data compressed "as is" (saves time as no data compression is needed).
If you want to globally change compression while transferring archives to the DST_REPO,
give ``--compress=WANTED_COMPRESSION --recompress=always``.
give ``--compression=WANTED_COMPRESSION --recompress=always``.
The default is to transfer all archives.
@@ -166,11 +166,11 @@ to the above, but you need the ``--from-borg1`` option::
# to continue using lz4 compression as you did in SRC_REPO:
borg --repo=DST_REPO transfer --other-repo=SRC_REPO --from-borg1 \
--compress=lz4 --recompress=never
--compression=lz4 --recompress=never
# alternatively, to recompress everything to zstd,3:
borg --repo=DST_REPO transfer --other-repo=SRC_REPO --from-borg1 \
--compress=zstd,3 --recompress=always
--compression=zstd,3 --recompress=always
# to re-chunk using different chunker parameters:
borg --repo=DST_REPO transfer --other-repo=SRC_REPO \
docs/usage/undelete.rst.inc
+1 -1
View File
@@ -94,4 +94,4 @@ undeleted.
You can undelete multiple archives by specifying a match pattern using
the ``--match-archives PATTERN`` option (for more information on these
patterns, see :ref:`borg_patterns`).
patterns, see "borg help match-archives").
docs/usage/version.rst.inc
+18 -15
View File
@@ -12,15 +12,17 @@ borg version
.. class:: borg-options-table
+-------------------------------------------------------+------------+-----------------------+
| **options** |
+-------------------------------------------------------+------------+-----------------------+
| | ``--json`` | format output as JSON |
+-------------------------------------------------------+------------+-----------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-------------------------------------------------------+------------+-----------------------+
+-------------------------------------------------------+------------------+------------------------+
| **options** |
+-------------------------------------------------------+------------------+------------------------+
| | ``--json`` | format output as JSON |
+-------------------------------------------------------+------------------+------------------------+
| | ``--from-borg1`` | repository is Borg 1.x |
+-------------------------------------------------------+------------------+------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-------------------------------------------------------+------------------+------------------------+
.. raw:: html
@@ -36,6 +38,7 @@ borg version
options
--json format output as JSON
--from-borg1 repository is Borg 1.x
:ref:`common_options`
@@ -54,13 +57,13 @@ the remote Borg is queried, and its version is displayed as the server version.
Examples::
# local repository (client uses 1.4.0 alpha version)
$ borg version /mnt/backup
1.4.0a / 1.4.0a
# local repository
$ borg -r /mnt/backup version
2.0.0 / 2.0.0
# legacy remote repository (client uses 1.4.0 alpha, server uses 1.2.7 release)
$ borg version --from-borg1 ssh://borg@borgbackup:repo
1.4.0a / 1.2.7
# legacy remote repository (client uses 2.0.0, server uses 1.4.5 release)
$ borg -r ssh://borg@borgbackup/repo version --from-borg1
2.0.0 / 1.4.5
Due to the version tuple format used in Borg client/server negotiation, only
a simplified version is displayed (as provided by borg.version.format_version).