diff --git a/docs/changes.rst b/docs/changes.rst
index fbf263eda..7de719e29 100644
--- a/docs/changes.rst
+++ b/docs/changes.rst
@@ -414,7 +414,7 @@ Compatibility notes:
Change Log
==========
-Version 1.4.1 (2025-04-xx)
+Version 1.4.1 (2025-04-19)
--------------------------
For upgrade and compatibility hints, please also read the section "Upgrade Notes"
@@ -428,7 +428,8 @@ New features:
create a non-directory file at that place is still supported.
- compact: support --dry-run (do nothing) to simplify scripting, #8300
- add {unixtime} placeholder, #8522
-- macOS: retrieve `birthtime` in nanosecond precision via system call, #8724
+- macOS: retrieve birthtime in nanosecond precision via system call, #8724
+- implement padme chunk size obfuscation (SPEC 250), #8705
Fixes:
@@ -456,7 +457,7 @@ Fixes:
Other changes:
- support and test on Python 3.13
-- use Cython 3.0.11
+- use Cython 3.0.12
- filter LibreSSL related warnings on OpenBSD
- docs:
@@ -475,7 +476,6 @@ Other changes:
- FAQ: Why is backing up an unmodified FAT filesystem slow on Linux?
- FAQ: Why are backups slow on a Linux server that is a member of a windows domain?
- FAQ: add entry about pure-python msgpack warning, #8323
- - modify docs for automated backup to append to SYSTEMD_WANTS
- modify docs for automated backup to append to SYSTEMD_WANTS rather than overwrite, #8641
- fix udev rule priority in automated-local.rst, #8639
- clarify requirements when using command line options with special characters within a shell, #8628
@@ -489,9 +489,9 @@ Other changes:
- github CI: windows msys2 build: broken, disable it for now, #8264
- improve borg check --repair healing tests, #8302
- fix hourly prune test failure due to local timezone
+ - ignore `com.apple.provenance` xattr (macOS specific)
- vagrant:
- - misc. cleanups/updates
- pyenv: only use Python 3.11.12, use this for binary build
- macos: give more memory
- install rust on BSD
diff --git a/docs/man/borg-benchmark-crud.1 b/docs/man/borg-benchmark-crud.1
index 491d97cca..88adaec19 100644
--- a/docs/man/borg-benchmark-crud.1
+++ b/docs/man/borg-benchmark-crud.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-BENCHMARK-CRUD" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
.SH SYNOPSIS
@@ -47,11 +47,9 @@ If your repository is encrypted and borg needs a passphrase to unlock the key, u
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
BORG_PASSPHRASE=mysecret borg benchmark crud REPO PATH
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
diff --git a/docs/man/borg-benchmark.1 b/docs/man/borg-benchmark.1
index 5dfa690d1..fe927b87e 100644
--- a/docs/man/borg-benchmark.1
+++ b/docs/man/borg-benchmark.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-BENCHMARK" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-benchmark \- benchmark command
.SH SYNOPSIS
diff --git a/docs/man/borg-break-lock.1 b/docs/man/borg-break-lock.1
index e448d58bc..e92c92d7b 100644
--- a/docs/man/borg-break-lock.1
+++ b/docs/man/borg-break-lock.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-BREAK-LOCK" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg.
.SH SYNOPSIS
diff --git a/docs/man/borg-check.1 b/docs/man/borg-check.1
index bb666ef51..e61c4be0c 100644
--- a/docs/man/borg-check.1
+++ b/docs/man/borg-check.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-CHECK" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-check \- Check repository consistency
.SH SYNOPSIS
@@ -161,7 +161,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
.B REPOSITORY_OR_ARCHIVE
repository or archive to check consistency of
.UNINDENT
-.SS optional arguments
+.SS options
.INDENT 0.0
.TP
.B \-\-repository\-only
diff --git a/docs/man/borg-common.1 b/docs/man/borg-common.1
index 0602449c6..002109ad3 100644
--- a/docs/man/borg-common.1
+++ b/docs/man/borg-common.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-COMMON" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-common \- Common options of Borg commands
.SH SYNOPSIS
diff --git a/docs/man/borg-compact.1 b/docs/man/borg-compact.1
index 6df1a4926..ee063ee3c 100644
--- a/docs/man/borg-compact.1
+++ b/docs/man/borg-compact.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-COMPACT" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-compact \- compact segment files in the repository
.SH SYNOPSIS
@@ -66,9 +66,12 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
.B REPOSITORY
repository to compact
.UNINDENT
-.SS optional arguments
+.SS options
.INDENT 0.0
.TP
+.B \-n\fP,\fB \-\-dry\-run
+do nothing
+.TP
.B \-\-cleanup\-commits
cleanup commit\-only 17\-byte segment files
.TP
@@ -79,15 +82,13 @@ set minimum threshold for saved space in PERCENT (Default: 10)
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
# compact segments and free repo disk space
$ borg compact /path/to/repo
# same as above plus clean up 17byte commit\-only segments
$ borg compact \-\-cleanup\-commits /path/to/repo
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.SH SEE ALSO
diff --git a/docs/man/borg-compression.1 b/docs/man/borg-compression.1
index a4e9a95c1..d4275b9f4 100644
--- a/docs/man/borg-compression.1
+++ b/docs/man/borg-compression.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-COMPRESSION" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-compression \- Details regarding compression
.SH DESCRIPTION
@@ -78,7 +78,8 @@ Use a built\-in heuristic to decide per chunk whether to compress or not.
The heuristic tries with lz4 whether the data is compressible.
For incompressible data, it will not use compression (uses \(dqnone\(dq).
For compressible data, it uses the given C[,L] compression \- with C[,L]
-being any valid compression specifier.
+being any valid compression specifier. This can be helpful for media files
+which often cannot be compressed much more.
.TP
.B obfuscate,SPEC,C[,L]
Use compressed\-size obfuscation to make fingerprinting attacks based on
@@ -103,16 +104,14 @@ Available factors:
.INDENT 7.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
1: 0.01 .. 100
2: 0.1 .. 1,000
3: 1 .. 10,000
4: 10 .. 100,000
5: 100 .. 1,000,000
6: 1,000 .. 10,000,000
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
@@ -120,14 +119,12 @@ Example probabilities for SPEC \fB1\fP:
.INDENT 7.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
90 % 0.01 .. 0.1
9 % 0.1 .. 1
0.9 % 1 .. 10
0.09% 10 .. 100
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
@@ -135,25 +132,35 @@ Example probabilities for SPEC \fB1\fP:
.INDENT 7.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
110: 1kiB (2 ^ (SPEC \- 100))
\&...
120: 1MiB
\&...
123: 8MiB (max.)
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
+.sp
+\fIPadmé padding\fP (deterministic)
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.EX
+250: pads to sums of powers of 2, max 12% overhead
+.EE
+.UNINDENT
+.UNINDENT
+.sp
+Uses the Padmé algorithm to deterministically pad the compressed size to a sum of
+powers of 2, limiting overhead to 12%. See for details.
.UNINDENT
.sp
Examples:
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
borg create \-\-compression lz4 REPO::ARCHIVE data
borg create \-\-compression zstd REPO::ARCHIVE data
borg create \-\-compression zstd,10 REPO::ARCHIVE data
@@ -164,8 +171,8 @@ borg create \-\-compression auto,lzma ...
borg create \-\-compression obfuscate,110,none ...
borg create \-\-compression obfuscate,3,auto,zstd,10 ...
borg create \-\-compression obfuscate,2,zstd,6 ...
-.ft P
-.fi
+borg create \-\-compression obfuscate,250,zstd,3 ...
+.EE
.UNINDENT
.UNINDENT
.SH AUTHOR
diff --git a/docs/man/borg-config.1 b/docs/man/borg-config.1
index 0f833a5b5..585054c47 100644
--- a/docs/man/borg-config.1
+++ b/docs/man/borg-config.1
@@ -27,7 +27,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-CONFIG" 1 "2024-07-02" "" "borg backup tool"
+.TH "BORG-CONFIG" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-config \- get, set, and delete values in a repository or cache config file
.SH SYNOPSIS
@@ -39,7 +39,7 @@ This command gets and sets options in a local repository or cache config file.
For security reasons, this command only works on local repositories.
.sp
To delete a config value entirely, use \fB\-\-delete\fP\&. To list the values
-of the configuration file or the default values, use \fB\-\-list\fP\&. To get and existing
+of the configuration file or the default values, use \fB\-\-list\fP\&. To get an existing
key, pass only the key name. To set a key, pass both the key name and
the new value. Keys can be specified in the format \(dqsection.name\(dq or
simply \(dqname\(dq; the section will default to \(dqrepository\(dq and \(dqcache\(dq for
@@ -62,7 +62,7 @@ name of config key
.B VALUE
new value for key
.UNINDENT
-.SS optional arguments
+.SS options
.INDENT 0.0
.TP
.B \-c\fP,\fB \-\-cache
@@ -87,8 +87,7 @@ making changes!
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
# find cache directory
$ cd ~/.cache/borg/$(borg config /path/to/repo id)
@@ -97,8 +96,7 @@ $ borg config /path/to/repo additional_free_space 2G
# make a repo append\-only
$ borg config /path/to/repo append_only 1
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.SH SEE ALSO
diff --git a/docs/man/borg-create.1 b/docs/man/borg-create.1
index 9f51f695a..cb31fb955 100644
--- a/docs/man/borg-create.1
+++ b/docs/man/borg-create.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-CREATE" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-create \- Create new archive
.SH SYNOPSIS
@@ -137,7 +137,7 @@ name of archive to create (must be also a valid directory name)
.B PATH
paths to archive
.UNINDENT
-.SS optional arguments
+.SS options
.INDENT 0.0
.TP
.B \-n\fP,\fB \-\-dry\-run
@@ -198,7 +198,7 @@ include/exclude paths matching PATTERN
read include/exclude patterns from PATTERNFILE, one per line
.TP
.B \-\-exclude\-caches
-exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.bford.info/cachedir/spec.html\fP)
+exclude directories that contain a CACHEDIR.TAG file ( )
.TP
.BI \-\-exclude\-if\-present \ NAME
exclude directories that are tagged by containing a filesystem object with the given NAME
@@ -276,8 +276,7 @@ select compression algorithm, see the output of the \(dqborg help compression\(d
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
# Backup ~/Documents into an archive named \(dqmy\-documents\(dq
$ borg create /path/to/repo::my\-documents ~/Documents
@@ -362,8 +361,7 @@ $ find ~ \-size \-1000k \-print0 | borg create \e
\-\-paths\-from\-stdin \e
\-\-paths\-delimiter \(dq\e0\(dq \e
/path/to/repo::smallfiles\-handle\-newline
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.SH NOTES
@@ -454,11 +452,9 @@ pipe directly to borg:
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
backup\-vm \-\-id myvm \-\-stdout | borg create REPO::ARCHIVE \-
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
@@ -469,11 +465,9 @@ to the command:
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
borg create \-\-content\-from\-command REPO::ARCHIVE \-\- backup\-vm \-\-id myvm \-\-stdout
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
diff --git a/docs/man/borg-delete.1 b/docs/man/borg-delete.1
index 7b27551dc..16bfdf3c2 100644
--- a/docs/man/borg-delete.1
+++ b/docs/man/borg-delete.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-DELETE" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-delete \- Delete an existing repository or archives
.SH SYNOPSIS
@@ -71,7 +71,7 @@ repository or archive to delete
.B ARCHIVE
archives to delete
.UNINDENT
-.SS optional arguments
+.SS options
.INDENT 0.0
.TP
.B \-n\fP,\fB \-\-dry\-run
@@ -120,8 +120,7 @@ consider last N archives after other filters were applied
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
# delete a single backup archive:
$ borg delete /path/to/repo::Monday
# actually free disk space:
@@ -143,8 +142,7 @@ 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
Type \(aqYES\(aq if you understand this and want to continue: YES
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.SH SEE ALSO
diff --git a/docs/man/borg-diff.1 b/docs/man/borg-diff.1
index 4b90a5806..c699d289a 100644
--- a/docs/man/borg-diff.1
+++ b/docs/man/borg-diff.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-DIFF" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-diff \- Diff contents of two archives
.SH SYNOPSIS
@@ -66,7 +66,7 @@ ARCHIVE2 name (no repository location allowed)
.B PATH
paths of items inside the archives to compare; patterns are supported
.UNINDENT
-.SS optional arguments
+.SS options
.INDENT 0.0
.TP
.B \-\-numeric\-owner
@@ -106,8 +106,7 @@ read include/exclude patterns from PATTERNFILE, one per line
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
$ borg init \-e=none testrepo
$ mkdir testdir
$ cd testdir
@@ -146,8 +145,7 @@ $ borg diff \-\-json\-lines testrepo::archive1 archive3
{\(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}]
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.SH SEE ALSO
diff --git a/docs/man/borg-export-tar.1 b/docs/man/borg-export-tar.1
index 6ae06740e..fdce602a6 100644
--- a/docs/man/borg-export-tar.1
+++ b/docs/man/borg-export-tar.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-EXPORT-TAR" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-export-tar \- Export archive contents as a tarball
.SH SYNOPSIS
@@ -91,7 +91,7 @@ output tar file. \(dq\-\(dq to write to stdout instead.
.B PATH
paths to extract; patterns are supported
.UNINDENT
-.SS optional arguments
+.SS options
.INDENT 0.0
.TP
.B \-\-tar\-filter
@@ -122,8 +122,7 @@ Remove the specified number of leading path elements. Paths with fewer elements
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
# export as uncompressed tar
$ borg export\-tar /path/to/repo::Monday Monday.tar
@@ -139,8 +138,7 @@ $ borg export\-tar /path/to/repo::Monday \- | curl \-\-data\-binary @\- https://
# remote extraction via \(dqtarpipe\(dq
$ borg export\-tar /path/to/repo::Monday \- | ssh somewhere \(dqcd extracted; tar x\(dq
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.SH SEE ALSO
diff --git a/docs/man/borg-extract.1 b/docs/man/borg-extract.1
index 5e332510d..94c5866e0 100644
--- a/docs/man/borg-extract.1
+++ b/docs/man/borg-extract.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-EXTRACT" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-extract \- Extract archive contents
.SH SYNOPSIS
@@ -72,7 +72,7 @@ archive to extract
.B PATH
paths to extract; patterns are supported
.UNINDENT
-.SS optional arguments
+.SS options
.INDENT 0.0
.TP
.B \-\-list
@@ -127,8 +127,7 @@ Remove the specified number of leading path elements. Paths with fewer elements
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
# Extract entire archive
$ borg extract /path/to/repo::my\-files
@@ -146,8 +145,7 @@ $ borg extract /path/to/repo::my\-files home/USERNAME/src \-\-exclude \(aq*.o\(a
# Restore a raw device (must not be active/in use/mounted at that time)
$ borg extract \-\-stdout /path/to/repo::my\-sdx | dd of=/dev/sdx bs=10M
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.SH SEE ALSO
diff --git a/docs/man/borg-import-tar.1 b/docs/man/borg-import-tar.1
index 15020681a..e3844f59e 100644
--- a/docs/man/borg-import-tar.1
+++ b/docs/man/borg-import-tar.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-IMPORT-TAR" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-import-tar \- Create a backup archive from a tarball
.SH SYNOPSIS
@@ -86,7 +86,7 @@ name of archive to create (must be also a valid directory name)
.B TARFILE
input tar file. \(dq\-\(dq to read from stdin instead.
.UNINDENT
-.SS optional arguments
+.SS options
.INDENT 0.0
.TP
.B \-\-tar\-filter
diff --git a/docs/man/borg-info.1 b/docs/man/borg-info.1
index cece570e4..bdf40910a 100644
--- a/docs/man/borg-info.1
+++ b/docs/man/borg-info.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-INFO" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-info \- Show archive details such as disk space used
.SH SYNOPSIS
@@ -59,7 +59,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
.B REPOSITORY_OR_ARCHIVE
repository or archive to display information about
.UNINDENT
-.SS optional arguments
+.SS options
.INDENT 0.0
.TP
.B \-\-json
@@ -87,8 +87,7 @@ consider last N archives after other filters were applied
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
$ borg info /path/to/repo::2017\-06\-29T11:00\-srv
Archive name: 2017\-06\-29T11:00\-srv
Archive fingerprint: b2f1beac2bd553b34e06358afa45a3c1689320d39163890c5bbbd49125f00fe5
@@ -141,8 +140,7 @@ All archives: 121.82 TB 112.41 TB 215.42 GB
Unique chunks Total chunks
Chunk index: 1015213 626934122
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.SH SEE ALSO
diff --git a/docs/man/borg-init.1 b/docs/man/borg-init.1
index 84cd8353b..930863483 100644
--- a/docs/man/borg-init.1
+++ b/docs/man/borg-init.1
@@ -1,3 +1,4 @@
+'\" t
.\" Man page generated from reStructuredText.
.
.
@@ -27,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-INIT" 1 "2024-07-02" "" "borg backup tool"
+.TH "BORG-INIT" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-init \- Initialize an empty repository
.SH SYNOPSIS
@@ -47,11 +48,9 @@ Use \fBrepokey\fP:
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
borg init \-\-encryption repokey /path/to/repo
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
@@ -59,11 +58,9 @@ Or \fBrepokey\-blake2\fP depending on which is faster on your client machines (s
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
borg init \-\-encryption repokey\-blake2 /path/to/repo
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
@@ -133,9 +130,8 @@ the hashing is done on your local machine.
.\" nanorst: inline-fill
.
.TS
-center;
-|l|l|l|l|.
-_
+box center;
+l|l|l|l.
T{
Hash/MAC
T} T{
@@ -170,7 +166,6 @@ T} T{
\fIrepokey\-blake2\fP
\fIkeyfile\-blake2\fP
T}
-_
.TE
.\" nanorst: inline-replace
.
@@ -225,7 +220,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
.B REPOSITORY
repository to create
.UNINDENT
-.SS optional arguments
+.SS options
.INDENT 0.0
.TP
.BI \-e \ MODE\fR,\fB \ \-\-encryption \ MODE
@@ -244,8 +239,7 @@ create the parent directories of the repository directory, if they are missing.
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
# Local repository, repokey encryption, BLAKE2b (often faster, since Borg 1.1)
$ borg init \-\-encryption=repokey\-blake2 /path/to/repo
@@ -259,8 +253,7 @@ $ borg init \-\-encryption=repokey\-blake2 user@hostname:backup
# Remote repository (accesses a remote borg via ssh)
# keyfile: stores the (encrypted) key into ~/.config/borg/keys/
$ borg init \-\-encryption=keyfile user@hostname:backup
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.SH SEE ALSO
diff --git a/docs/man/borg-key-change-passphrase.1 b/docs/man/borg-key-change-passphrase.1
index a8fe3ed05..40a75cc32 100644
--- a/docs/man/borg-key-change-passphrase.1
+++ b/docs/man/borg-key-change-passphrase.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-KEY-CHANGE-PASSPHRASE" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-key-change-passphrase \- Change repository key file passphrase
.SH SYNOPSIS
@@ -52,8 +52,7 @@ REPOSITORY
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
# Create a key file protected repository
$ borg init \-\-encryption=keyfile \-v /path/to/repo
Initializing repository at \(dq/path/to/repo\(dq
@@ -78,8 +77,7 @@ Key updated
# key file (creating or overwriting the output key)
# (keyfile repositories only)
$ BORG_KEY_FILE=/path/to/output\-key borg key import /path/to/repo /path/to/exported
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
@@ -87,14 +85,12 @@ Fully automated using environment variables:
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
$ BORG_NEW_PASSPHRASE=old borg init \-e=repokey repo
# now \(dqold\(dq is the current passphrase.
$ BORG_PASSPHRASE=old BORG_NEW_PASSPHRASE=new borg key change\-passphrase repo
# now \(dqnew\(dq is the current passphrase.
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.SH SEE ALSO
diff --git a/docs/man/borg-key-export.1 b/docs/man/borg-key-export.1
index 6a16fd582..f9669d88e 100644
--- a/docs/man/borg-key-export.1
+++ b/docs/man/borg-key-export.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-KEY-EXPORT" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-key-export \- Export the repository key for backup
.SH SYNOPSIS
@@ -61,8 +61,7 @@ Examples:
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
borg key export /path/to/repo > encrypted\-key\-backup
borg key export \-\-paper /path/to/repo > encrypted\-key\-backup.txt
borg key export \-\-qr\-html /path/to/repo > encrypted\-key\-backup.html
@@ -70,8 +69,7 @@ borg key export \-\-qr\-html /path/to/repo > encrypted\-key\-backup.html
borg key export /path/to/repo encrypted\-key\-backup
borg key export \-\-paper /path/to/repo encrypted\-key\-backup.txt
borg key export \-\-qr\-html /path/to/repo encrypted\-key\-backup.html
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.SH OPTIONS
@@ -85,7 +83,7 @@ REPOSITORY
.B PATH
where to store the backup
.UNINDENT
-.SS optional arguments
+.SS options
.INDENT 0.0
.TP
.B \-\-paper
diff --git a/docs/man/borg-key-import.1 b/docs/man/borg-key-import.1
index 4bd55c9a6..f2bd6d752 100644
--- a/docs/man/borg-key-import.1
+++ b/docs/man/borg-key-import.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-KEY-IMPORT" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-key-import \- Import the repository key from backup
.SH SYNOPSIS
@@ -60,7 +60,7 @@ REPOSITORY
.B PATH
path to the backup (\(aq\-\(aq to read from stdin)
.UNINDENT
-.SS optional arguments
+.SS options
.INDENT 0.0
.TP
.B \-\-paper
diff --git a/docs/man/borg-key-migrate-to-repokey.1 b/docs/man/borg-key-migrate-to-repokey.1
index 606151420..94fbfea77 100644
--- a/docs/man/borg-key-migrate-to-repokey.1
+++ b/docs/man/borg-key-migrate-to-repokey.1
@@ -27,7 +27,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-MIGRATE-TO-REPOKEY" 1 "2024-07-02" "" "borg backup tool"
+.TH "BORG-KEY-MIGRATE-TO-REPOKEY" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-key-migrate-to-repokey \- Migrate passphrase -> repokey
.SH SYNOPSIS
diff --git a/docs/man/borg-key.1 b/docs/man/borg-key.1
index 3f777d44b..df193d996 100644
--- a/docs/man/borg-key.1
+++ b/docs/man/borg-key.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-KEY" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-key \- Manage a keyfile or repokey of a repository
.SH SYNOPSIS
diff --git a/docs/man/borg-list.1 b/docs/man/borg-list.1
index f8869679a..d86269d79 100644
--- a/docs/man/borg-list.1
+++ b/docs/man/borg-list.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-LIST" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-list \- List archive or repository contents
.SH SYNOPSIS
@@ -50,7 +50,7 @@ repository or archive to list contents of
.B PATH
paths to list; patterns are supported
.UNINDENT
-.SS optional arguments
+.SS options
.INDENT 0.0
.TP
.B \-\-consider\-checkpoints
@@ -105,8 +105,7 @@ read include/exclude patterns from PATTERNFILE, one per line
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
$ borg list /path/to/repo
Monday Mon, 2016\-02\-15 19:15:11
repo Mon, 2016\-02\-15 19:26:54
@@ -145,21 +144,20 @@ $ borg list /path/to/repo/::archiveA \-\-pattern \(aq+ re:.ext$\(aq \-\-pattern
\-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
\&...
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.SH NOTES
.SS The FORMAT specifier syntax
.sp
-The \fB\-\-format\fP option uses python\(aqs \fI\%format string syntax\fP\&.
+The \fB\-\-format\fP option uses python\(aqs format string syntax
+\&.
.sp
Examples:
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
$ borg list \-\-format \(aq{archive}{NL}\(aq /path/to/repo
ArchiveFoo
ArchiveBar
@@ -179,8 +177,7 @@ $ borg list \-\-format \(aq{mode} {user:6} {group:6} {size:8} {mtime} {path}{ext
$ borg list \-\-format \(aq{mode} {user:>6} {group:>6} {size:<8} {mtime} {path}{extra}{NL}\(aq /path/to/repo::ArchiveFoo
\-rw\-rw\-r\-\- user user 1024 Thu, 2021\-12\-09 10:22:17 file\-foo
\&...
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
diff --git a/docs/man/borg-mount.1 b/docs/man/borg-mount.1
index 99bb2703f..874f3e3e8 100644
--- a/docs/man/borg-mount.1
+++ b/docs/man/borg-mount.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-MOUNT" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-mount \- Mount archive or an entire repository as a FUSE filesystem
.SH SYNOPSIS
@@ -35,10 +35,29 @@ borg-mount \- Mount archive or an entire repository as a FUSE filesystem
borg [common options] mount [options] REPOSITORY_OR_ARCHIVE MOUNTPOINT [PATH...]
.SH DESCRIPTION
.sp
-This command mounts an archive as a FUSE filesystem. This can be useful for
-browsing an archive or restoring individual files. Unless the \fB\-\-foreground\fP
-option is given the command will run in the background until the filesystem
-is \fBumounted\fP\&.
+This command mounts a repository or an archive as a FUSE filesystem.
+This can be useful for browsing or restoring individual files.
+.sp
+When restoring, take into account that the current FUSE implementation does
+not support special fs flags and ACLs.
+.sp
+When mounting a repository, the top directories will be named like the
+archives and the directory structure below these will be loaded on\-demand from
+the repository when entering these directories, so expect some delay.
+.sp
+Unless the \fB\-\-foreground\fP option is given the command will run in the
+background until the filesystem is \fBumounted\fP\&.
+.sp
+Performance tips:
+.INDENT 0.0
+.IP \(bu 2
+when doing a \(dqwhole repository\(dq mount:
+do not enter archive dirs if not needed, this avoids on\-demand loading.
+.IP \(bu 2
+only mount a specific archive, not the whole repository.
+.IP \(bu 2
+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:
@@ -90,8 +109,8 @@ When the daemonized process receives a signal or crashes, it does not unmount.
Unmounting in these cases could cause an active rsync or similar process
to unintentionally delete data.
.sp
-When running in the foreground ^C/SIGINT unmounts cleanly, but other
-signals or crashes do not.
+When running in the foreground, ^C/SIGINT cleanly unmounts the filesystem,
+but other signals or crashes do not.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -107,7 +126,7 @@ where to mount filesystem
.B PATH
paths to extract; patterns are supported
.UNINDENT
-.SS optional arguments
+.SS options
.INDENT 0.0
.TP
.B \-\-consider\-checkpoints
diff --git a/docs/man/borg-patterns.1 b/docs/man/borg-patterns.1
index e61faaa09..1ae304d28 100644
--- a/docs/man/borg-patterns.1
+++ b/docs/man/borg-patterns.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-PATTERNS" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-patterns \- Details regarding patterns
.SH DESCRIPTION
@@ -52,7 +52,8 @@ style for a specific pattern, prefix it with two characters followed
by a colon \(aq:\(aq (i.e. \fBfm:path/*\fP, \fBsh:path/**\fP).
.INDENT 0.0
.TP
-.B \fI\%Fnmatch\fP, selector \fIfm:\fP
+.B Fnmatch
+, selector \fIfm:\fP
This is the default style for \fB\-\-exclude\fP and \fB\-\-exclude\-from\fP\&.
These patterns use a variant of shell pattern syntax, with \(aq*\(aq matching
any number of characters, \(aq?\(aq matching any single character, \(aq[...]\(aq
@@ -82,8 +83,9 @@ path and any substring match is sufficient. It is strongly recommended to
anchor patterns to the start (\(aq^\(aq), to the end (\(aq$\(aq) or both. Path
separators (backslash for Windows and \(aq/\(aq on other systems) in paths are
always normalized to a forward slash (\(aq/\(aq) before applying a pattern. The
-regular expression syntax is described in the \fI\%Python documentation for
-the re module\fP\&.
+regular expression syntax is described in the Python documentation for
+the re module
+\&.
.TP
.B Path prefix, selector \fIpp:\fP
This pattern style is useful to match whole sub\-directories. The pattern
@@ -122,6 +124,15 @@ Exclusions can be passed via the command line option \fB\-\-exclude\fP\&. When u
from within a shell, the patterns should be quoted to protect them from
expansion.
.sp
+Patterns matching special characters, e.g. white space, within a shell may
+require adjustments, such as putting quotation marks around the arguments.
+Example:
+Using bash, the following command line option would match and exclude \(dqitem name\(dq:
+\fB\-\-pattern=\(aq\-path/item name\(aq\fP
+Note that when patterns are used within a pattern file directly read by borg,
+e.g. when using \fB\-\-exclude\-from\fP or \fB\-\-patterns\-from\fP, there is no shell
+involved and thus no quotation marks are required.
+.sp
The \fB\-\-exclude\-from\fP option permits loading exclusion patterns from a text
file with one pattern per line. Lines empty or starting with the number sign
(\(aq#\(aq) after removing whitespace on both ends are ignored. The optional style
@@ -136,8 +147,7 @@ Examples:
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
# Exclude \(aq/home/user/file.o\(aq but not \(aq/home/user/file.odt\(aq:
$ borg create \-e \(aq*.o\(aq backup /
@@ -167,8 +177,7 @@ sh:home/*/.thumbnails
some file with spaces.txt
EOF
$ borg create \-\-exclude\-from exclude.txt backup /
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
@@ -222,8 +231,7 @@ Example:
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
# Define the recursion root
R /
# Exclude all iso files in any directory
@@ -240,8 +248,7 @@ R /
# Exclude all other files and directories
# that are not specifically included earlier.
\- **
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
@@ -266,16 +273,14 @@ Examples:
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
# backup pics, but not the ones from 2018, except the good ones:
# note: using = is essential to avoid cmdline argument parsing issues.
borg create \-\-pattern=+pics/2018/good \-\-pattern=\-pics/2018 repo::arch pics
# use a file with patterns:
borg create \-\-patterns\-from patterns.lst repo::arch
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
@@ -283,8 +288,7 @@ The patterns.lst file could look like that:
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
# \(dqsh:\(dq pattern style is the default, so the following line is not needed:
P sh
R /
@@ -301,8 +305,7 @@ R /
\- home/*
# don\(aqt even look in /proc
! proc
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
@@ -310,13 +313,11 @@ You can specify recursion roots either on the command line or in a patternfile:
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
# these two commands do the same thing
borg create \-\-exclude home/bobby/junk repo::arch /home/bobby /home/susan
borg create \-\-patterns\-from patternfile.lst repo::arch
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
@@ -324,8 +325,7 @@ The patternfile:
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
# note that excludes use fm: by default and patternfiles use sh: by default.
# therefore, we need to specify fm: to have the same exact behavior.
P fm
@@ -333,8 +333,7 @@ R /home/bobby
R /home/susan
\- home/bobby/junk
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
diff --git a/docs/man/borg-placeholders.1 b/docs/man/borg-placeholders.1
index 8f47a2fcd..c28631e9d 100644
--- a/docs/man/borg-placeholders.1
+++ b/docs/man/borg-placeholders.1
@@ -27,7 +27,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-PLACEHOLDERS" 1 "2024-07-02" "" "borg backup tool"
+.TH "BORG-PLACEHOLDERS" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-placeholders \- Details regarding placeholders
.SH DESCRIPTION
@@ -47,11 +47,13 @@ The full name of the machine in reverse domain name notation.
.TP
.B {now}
The current local date and time, by default in ISO\-8601 format.
-You can also supply your own \fI\%format string\fP, e.g. {now:%Y\-%m\-%d_%H:%M:%S}
+You can also supply your own format string
+, e.g. {now:%Y\-%m\-%d_%H:%M:%S}
.TP
.B {utcnow}
The current UTC date and time, by default in ISO\-8601 format.
-You can also supply your own \fI\%format string\fP, e.g. {utcnow:%Y\-%m\-%d_%H:%M:%S}
+You can also supply your own format string
+, e.g. {utcnow:%Y\-%m\-%d_%H:%M:%S}
.TP
.B {user}
The user name (or UID, if no name is available) of the user running borg.
@@ -76,11 +78,9 @@ If literal curly braces need to be used, double them for escaping:
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
borg create /path/to/repo::{{literal_text}}
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
@@ -88,13 +88,11 @@ Examples:
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
borg create /path/to/repo::{hostname}\-{user}\-{utcnow} ...
borg create /path/to/repo::{hostname}\-{now:%Y\-%m\-%d_%H:%M:%S} ...
borg prune \-\-glob\-archives \(aq{hostname}\-*\(aq ...
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
diff --git a/docs/man/borg-prune.1 b/docs/man/borg-prune.1
index 82682ce73..bea17ad4a 100644
--- a/docs/man/borg-prune.1
+++ b/docs/man/borg-prune.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-PRUNE" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-prune \- Prune repository archives according to specified rules
.SH SYNOPSIS
@@ -42,7 +42,8 @@ Important: Repository disk space is \fBnot\fP freed until you run \fBborg compac
.sp
This command is normally used by automated backup scripts wanting to keep a
certain number of historic backups. This retention policy is commonly referred to as
-\fI\%GFS\fP
+GFS
+
(Grandfather\-father\-son) backup rotation scheme.
.sp
Also, prune automatically removes checkpoint archives (incomplete archives left
@@ -76,9 +77,13 @@ starts is used for pruning purposes. Dates and times are interpreted in
the local timezone, and weeks go from Monday to Sunday. Specifying a
negative number of archives to keep means that there is no limit. As of borg
1.2.0, borg will retain the oldest archive if any of the secondly, minutely,
-hourly, daily, weekly, monthly, or yearly rules was not otherwise able to meet
-its retention target. This enables the first chronological archive to continue
-aging until it is replaced by a newer archive that meets the retention criteria.
+hourly, daily, weekly, monthly, quarterly, or yearly rules was not otherwise
+able to meet its retention target. This enables the first chronological archive
+to continue aging until it is replaced by a newer archive that meets the
+retention criteria.
+.sp
+The \fB\-\-keep\-13weekly\fP and \fB\-\-keep\-3monthly\fP rules are two different
+strategies for keeping archives every quarter year.
.sp
The \fB\-\-keep\-last N\fP option is doing the same as \fB\-\-keep\-secondly N\fP (and it will
keep the last N archives under the assumption that you do not create more than one
@@ -97,7 +102,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
.B REPOSITORY
repository to prune
.UNINDENT
-.SS optional arguments
+.SS options
.INDENT 0.0
.TP
.B \-n\fP,\fB \-\-dry\-run
@@ -133,6 +138,12 @@ number of weekly archives to keep
.B \-m\fP,\fB \-\-keep\-monthly
number of monthly archives to keep
.TP
+.B \-\-keep\-13weekly
+number of quarterly archives to keep (13 week strategy)
+.TP
+.B \-\-keep\-3monthly
+number of quarterly archives to keep (3 month strategy)
+.TP
.B \-y\fP,\fB \-\-keep\-yearly
number of yearly archives to keep
.TP
@@ -166,8 +177,7 @@ first so you will see what it would do without it actually doing anything.
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
# Keep 7 end of day and 4 additional end of week archives.
# Do a dry\-run without actually deleting anything.
$ borg prune \-v \-\-list \-\-dry\-run \-\-keep\-daily=7 \-\-keep\-weekly=4 /path/to/repo
@@ -185,8 +195,7 @@ $ borg prune \-v \-\-list \-\-keep\-daily=7 \-\-keep\-weekly=4 \-\-keep\-monthly
# Keep all backups in the last 10 days, 4 additional end of week archives,
# and an end of month archive for every month:
$ borg prune \-v \-\-list \-\-keep\-within=10d \-\-keep\-weekly=4 \-\-keep\-monthly=\-1 /path/to/repo
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
diff --git a/docs/man/borg-recreate.1 b/docs/man/borg-recreate.1
index f7d8041d8..834bcbce7 100644
--- a/docs/man/borg-recreate.1
+++ b/docs/man/borg-recreate.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-RECREATE" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-recreate \- Re-create archives
.SH SYNOPSIS
@@ -97,7 +97,7 @@ repository or archive to recreate
.B PATH
paths to recreate; patterns are supported
.UNINDENT
-.SS optional arguments
+.SS options
.INDENT 0.0
.TP
.B \-\-list
@@ -128,7 +128,7 @@ include/exclude paths matching PATTERN
read include/exclude patterns from PATTERNFILE, one per line
.TP
.B \-\-exclude\-caches
-exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.bford.info/cachedir/spec.html\fP)
+exclude directories that contain a CACHEDIR.TAG file ( )
.TP
.BI \-\-exclude\-if\-present \ NAME
exclude directories that are tagged by containing a filesystem object with the given NAME
@@ -164,8 +164,7 @@ rechunk using given chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
# Make old (Attic / Borg 0.xx) archives deduplicate with Borg 1.x archives.
# Archives created with Borg 1.1+ and the default chunker params are skipped
# (archive ID stays the same).
@@ -194,8 +193,7 @@ Name: archivename
Fingerprint: ...
Comment: This is a better comment
\&...
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.SH SEE ALSO
diff --git a/docs/man/borg-rename.1 b/docs/man/borg-rename.1
index baca3705c..61c2d609e 100644
--- a/docs/man/borg-rename.1
+++ b/docs/man/borg-rename.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-RENAME" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-rename \- Rename an existing archive
.SH SYNOPSIS
@@ -54,8 +54,7 @@ the new archive name to use
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
$ borg create /path/to/repo::archivename ~
$ borg list /path/to/repo
archivename Mon, 2016\-02\-15 19:50:19
@@ -63,8 +62,7 @@ archivename Mon, 2016\-02\-15 19:50:19
$ borg rename /path/to/repo::archivename newname
$ borg list /path/to/repo
newname Mon, 2016\-02\-15 19:50:19
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.SH SEE ALSO
diff --git a/docs/man/borg-serve.1 b/docs/man/borg-serve.1
index 4227b4d21..cd01d253f 100644
--- a/docs/man/borg-serve.1
+++ b/docs/man/borg-serve.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-SERVE" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-serve \- Start in server mode. This command is usually not used manually.
.SH SYNOPSIS
@@ -39,7 +39,7 @@ This command starts a repository server process. This command is usually not use
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
-.SS optional arguments
+.SS options
.INDENT 0.0
.TP
.BI \-\-restrict\-to\-path \ PATH
@@ -77,8 +77,7 @@ locations like \fB/etc/environment\fP or in the forced command itself (example b
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
# Allow an SSH keypair to only run 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.
@@ -88,8 +87,7 @@ command=\(dqborg serve \-\-restrict\-to\-path /path/to/repo\(dq,restrict ssh\-rs
# Set a BORG_XXX environment variable on the \(dqborg serve\(dq side
$ cat ~/.ssh/authorized_keys
command=\(dqexport BORG_XXX=value; borg serve [...]\(dq,restrict ssh\-rsa [...]
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
@@ -108,7 +106,8 @@ in this case.
.UNINDENT
.UNINDENT
.sp
-Details about sshd usage: \fI\%sshd(8)\fP
+Details about sshd usage: sshd(8)
+
.SS SSH Configuration
.sp
\fBborg serve\fP\(aqs pipes (\fBstdin\fP/\fBstdout\fP/\fBstderr\fP) are connected to the \fBsshd\fP process on the server side. In the event that the SSH connection between \fBborg serve\fP and the client is disconnected or stuck abnormally (for example, due to a network outage), it can take a long time for \fBsshd\fP to notice the client is disconnected. In the meantime, \fBsshd\fP continues running, and as a result so does the \fBborg serve\fP process holding the lock on the repository. This can cause subsequent \fBborg\fP operations on the remote repository to fail with the error: \fBFailed to create/acquire the lock\fP\&.
@@ -119,13 +118,11 @@ Either in the client side\(aqs \fB~/.ssh/config\fP file, or in the client\(aqs \
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
Host backupserver
ServerAliveInterval 10
ServerAliveCountMax 30
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
@@ -137,12 +134,10 @@ On the server side\(aqs \fBsshd\fP configuration file (typically \fB/etc/ssh/ssh
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
ClientAliveInterval 10
ClientAliveCountMax 30
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
diff --git a/docs/man/borg-umount.1 b/docs/man/borg-umount.1
index b777e78ea..7f7d93cab 100644
--- a/docs/man/borg-umount.1
+++ b/docs/man/borg-umount.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-UMOUNT" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-umount \- un-mount the FUSE filesystem
.SH SYNOPSIS
@@ -52,8 +52,7 @@ mountpoint of the filesystem to umount
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
# Mounting the repository shows all archives.
# Archives are loaded lazily, expect some delay when navigating to an archive
# for the first time.
@@ -94,16 +93,14 @@ export BORG_REPO=/path/to/repo
borg mount :: /tmp/mymountpoint
# Mount some specific archive:
borg mount ::root\-2016\-02\-15 /tmp/mymountpoint
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.SS borgfs
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
$ echo \(aq/mnt/backup /tmp/myrepo fuse.borgfs defaults,noauto 0 0\(aq >> /etc/fstab
$ echo \(aq/mnt/backup::root\-2016\-02\-15 /tmp/myarchive fuse.borgfs defaults,noauto 0 0\(aq >> /etc/fstab
$ mount /tmp/myrepo
@@ -112,8 +109,7 @@ $ ls /tmp/myrepo
root\-2016\-02\-01 root\-2016\-02\-2015
$ ls /tmp/myarchive
bin boot etc home lib lib64 lost+found media mnt opt root sbin srv tmp usr var
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
diff --git a/docs/man/borg-upgrade.1 b/docs/man/borg-upgrade.1
index 3584a188e..2df231d48 100644
--- a/docs/man/borg-upgrade.1
+++ b/docs/man/borg-upgrade.1
@@ -27,7 +27,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-UPGRADE" 1 "2024-07-02" "" "borg backup tool"
+.TH "BORG-UPGRADE" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-upgrade \- upgrade a repository from a previous version
.SH SYNOPSIS
@@ -86,7 +86,7 @@ If you routinely do this you might not want to enable this upgrade
reverse the upgrade by issuing \fBborg upgrade \-\-disable\-tam REPO\fP\&.
.sp
See
-\fI\%https://borgbackup.readthedocs.io/en/stable/changes.html#pre\-1\-0\-9\-manifest\-spoofing\-vulnerability\fP
+
for details.
.SS Attic and Borg 0.xx to Borg 1.x
.sp
@@ -118,11 +118,9 @@ make sure the cache files are also removed:
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
borg delete borg
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
@@ -148,7 +146,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
.B REPOSITORY
path to the repository to be upgraded
.UNINDENT
-.SS optional arguments
+.SS options
.INDENT 0.0
.TP
.B \-n\fP,\fB \-\-dry\-run
@@ -179,8 +177,7 @@ add TAM authentication for all archives.
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
# Upgrade the borg repository to the most recent version.
$ borg upgrade \-v /path/to/repo
making a hardlink copy in /path/to/repo.before\-upgrade\-2016\-02\-15\-20:51:55
@@ -190,8 +187,7 @@ converting repo index /path/to/repo/index.0
converting 1 segments...
converting borg 0.xx to borg current
no key file found for repository
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.SS Upgrading a passphrase encrypted attic repo
diff --git a/docs/man/borg-version.1 b/docs/man/borg-version.1
index 35cf0c9c8..14cc29dc8 100644
--- a/docs/man/borg-version.1
+++ b/docs/man/borg-version.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-VERSION" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-version \- Display the borg client / borg server version
.SH SYNOPSIS
@@ -47,8 +47,7 @@ Examples:
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
# local repo (client uses 1.4.0 alpha version)
$ borg version /mnt/backup
1.4.0a / 1.4.0a
@@ -56,8 +55,7 @@ $ borg version /mnt/backup
# remote repo (client uses 1.4.0 alpha, server uses 1.2.7 release)
$ borg version ssh://borg@borgbackup:repo
1.4.0a / 1.2.7
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
diff --git a/docs/man/borg-with-lock.1 b/docs/man/borg-with-lock.1
index fc1e81352..1b5fe23c5 100644
--- a/docs/man/borg-with-lock.1
+++ b/docs/man/borg-with-lock.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORG-WITH-LOCK" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg-with-lock \- run a user specified command with the repository lock held
.SH SYNOPSIS
@@ -39,11 +39,9 @@ This command runs a user\-specified command while locking the repository. For ex
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
$ borg with\-lock /mnt/borgrepo rsync \-av /mnt/borgrepo /somewhere/else/borgrepo
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
diff --git a/docs/man/borg.1 b/docs/man/borg.1
index 8418b7dd5..b3f0aa4bc 100644
--- a/docs/man/borg.1
+++ b/docs/man/borg.1
@@ -1,3 +1,4 @@
+'\" t
.\" Man page generated from reStructuredText.
.
.
@@ -27,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" 1 "2024-07-02" "" "borg backup tool"
+.TH "BORG" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borg \- deduplicating and encrypting backup tool
.SH SYNOPSIS
@@ -58,11 +59,9 @@ Before a backup can be made a repository has to be initialized:
.INDENT 3.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
$ borg init \-\-encryption=repokey /path/to/repo
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.IP 2. 3
@@ -71,11 +70,9 @@ Backup the \fB~/src\fP and \fB~/Documents\fP directories into an archive called
.INDENT 3.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
$ borg create /path/to/repo::Monday ~/src ~/Documents
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.IP 3. 3
@@ -83,11 +80,9 @@ The next day create a new archive called \fITuesday\fP:
.INDENT 3.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
$ borg create \-\-stats /path/to/repo::Tuesday ~/src ~/Documents
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
@@ -98,8 +93,7 @@ data (not shared with other archives):
.INDENT 3.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
Archive name: Tuesday
Archive fingerprint: bd31004d58f51ea06ff735d2e5ac49376901b21d58035f8fb05dbf866566e3c2
@@ -116,8 +110,7 @@ All archives: 8.33 MB 8.34 MB 4.19 MB
Unique chunks Total chunks
Chunk index: 132 261
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.IP 4. 3
@@ -125,13 +118,11 @@ List all archives in the repository:
.INDENT 3.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
$ borg list /path/to/repo
Monday Mon, 2016\-02\-15 19:14:44
Tuesday Tue, 2016\-02\-16 19:15:11
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.IP 5. 3
@@ -139,14 +130,12 @@ List the contents of the \fIMonday\fP archive:
.INDENT 3.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
$ borg list /path/to/repo::Monday
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
\&...
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.IP 6. 3
@@ -154,11 +143,9 @@ Restore the \fIMonday\fP archive by extracting the files relative to the current
.INDENT 3.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
$ borg extract /path/to/repo::Monday
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.IP 7. 3
@@ -166,11 +153,9 @@ Delete the \fIMonday\fP archive (please note that this does \fBnot\fP free repo
.INDENT 3.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
$ borg delete /path/to/repo::Monday
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.IP 8. 3
@@ -178,11 +163,9 @@ Recover disk space by compacting the segment files in the repo:
.INDENT 3.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
$ borg compact /path/to/repo
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.UNINDENT
@@ -206,18 +189,16 @@ in the example), but not in between them:
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
borg create \-s \-\-progress repo::archive path # good and preferred
borg create repo::archive path \-s \-\-progress # also works
borg create \-s repo::archive path \-\-progress # works, but ugly
borg create repo::archive \-s \-\-progress path # BAD
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
-This is due to a problem in the argparse module: \fI\%https://bugs.python.org/issue15112\fP
+This is due to a problem in the argparse module:
.SS Repository URLs
.sp
\fBLocal filesystem\fP (or locally mounted network filesystem):
@@ -231,13 +212,21 @@ expanded by your shell).
.sp
Note: you may also prepend a \fBfile://\fP to a filesystem path to get URL style.
.sp
-\fBRemote repositories\fP accessed via ssh \fI\%user@host\fP:
+\fBRemote repositories\fP accessed via ssh :
.sp
-\fBuser@host:/path/to/repo\fP \- remote repo, absolute path
+\fBssh://user@host:port/path/to/repo\fP \- remote repo, absolute path, port can be given
.sp
-\fBssh://user@host:port/path/to/repo\fP \- same, alternative syntax, port can be given
+\fBuser@host:/path/to/repo\fP \- remote repo, absolute path, deprecated syntax
.sp
-\fBRemote repositories with relative paths\fP can be given using this syntax:
+\fBRemote repositories with relative paths, URL style syntax with port\fP:
+.sp
+\fBssh://user@host:port/./path/to/repo\fP \- path relative to current directory
+.sp
+\fBssh://user@host:port/~/path/to/repo\fP \- path relative to user\(aqs home directory
+.sp
+\fBssh://user@host:port/~other/path/to/repo\fP \- path relative to other\(aqs home directory (deprecated)
+.sp
+\fBRemote repositories with relative paths, deprecated SCP style syntax\fP:
.sp
\fBuser@host:path/to/repo\fP \- path relative to current directory
.sp
@@ -248,24 +237,14 @@ Note: you may also prepend a \fBfile://\fP to a filesystem path to get URL style
Note: giving \fBuser@host:/./path/to/repo\fP or \fBuser@host:/~/path/to/repo\fP or
\fBuser@host:/~other/path/to/repo\fP is also supported, but not required here.
.sp
-\fBRemote repositories with relative paths, alternative syntax with port\fP:
-.sp
-\fBssh://user@host:port/./path/to/repo\fP \- path relative to current directory
-.sp
-\fBssh://user@host:port/~/path/to/repo\fP \- path relative to user\(aqs home directory
-.sp
-\fBssh://user@host:port/~other/path/to/repo\fP \- path relative to other\(aqs home directory
-.sp
If you frequently need the same repo URL, it is a good idea to set the
\fBBORG_REPO\fP environment variable to set a default for the repo URL:
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
export BORG_REPO=\(aqssh://user@host:port/path/to/repo\(aq
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
@@ -297,11 +276,9 @@ If you want to capture the log output to a file, just redirect it:
.INDENT 0.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
borg create repo::archive myfiles 2>> logfile
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
@@ -343,9 +320,8 @@ their usage is not recommended as you might miss important information.
.sp
Borg can exit with the following return codes (rc):
.TS
-center;
-|l|l|.
-_
+box center;
+l|l.
T{
Return code
T} T{
@@ -389,11 +365,12 @@ T{
T} T{
killed by signal N (e.g. 137 == kill \-9)
T}
-_
.TE
.sp
If you use \fB\-\-show\-rc\fP, the return code is also logged at the indicated
level as the last log entry.
+.sp
+The modern exit codes (return codes, \(dqrc\(dq) are documented there: \fImsgid\fP
.SS Environment Variables
.sp
Borg uses some environment variables for automation:
@@ -449,10 +426,11 @@ a unique id based on the MAC address of the network interface. Except if that MA
that case it returns a random value, which is not what we want (because it kills automatic stale lock removal).
So, if you have a all\-zero MAC address or other reasons to better externally control the host id, just set this
environment variable to a unique value. If all your FQDNs are unique, you can just use the FQDN. If not,
-use \fI\%fqdn@uniqueid\fP\&.
+use \&.
.TP
.B BORG_LOGGING_CONF
-When set, use the given filename as \fI\%INI\fP\-style logging configuration.
+When set, use the given filename as INI
+\-style logging configuration.
A basic example conf can be found at \fBdocs/misc/logging.conf\fP\&.
.TP
.B BORG_RSH
@@ -474,6 +452,10 @@ When set to a numeric value, this determines the maximum \(dqtime to live\(dq fo
entries (default: 20). The files cache is used to quickly determine whether a file is unchanged.
The FAQ explains this more detailed in: \fIalways_chunking\fP
.TP
+.B BORG_USE_CHUNKS_ARCHIVE
+When set to no (default: yes), the \fBchunks.archive.d\fP folder will not be used. This reduces
+disk space usage but slows down cache resyncs.
+.TP
.B BORG_SHOW_SYSINFO
When set to no (default: yes), system information (like OS, Python version, ...) in
exceptions is not shown.
@@ -534,11 +516,9 @@ from an affected repository (read\-only access):
.INDENT 7.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
BORG_WORKAROUNDS=authenticated_no_key borg extract repo::archive
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
@@ -546,11 +526,9 @@ After you have extracted all data you need, you MUST delete the repository:
.INDENT 7.0
.INDENT 3.5
.sp
-.nf
-.ft C
+.EX
BORG_WORKAROUNDS=authenticated_no_key borg delete repo
-.ft P
-.fi
+.EE
.UNINDENT
.UNINDENT
.sp
@@ -599,14 +577,16 @@ to modify \fBBORG_BASE_DIR\fP: the other paths for cache, config etc. will adapt
.TP
.B BORG_CACHE_DIR
Defaults to \fB$BORG_BASE_DIR/.cache/borg\fP\&. If \fBBORG_BASE_DIR\fP is not explicitly set while
-\fI\%XDG env var\fP \fBXDG_CACHE_HOME\fP is set, then \fB$XDG_CACHE_HOME/borg\fP is being used instead.
+XDG env var
+ \fBXDG_CACHE_HOME\fP is set, then \fB$XDG_CACHE_HOME/borg\fP is being used instead.
This directory contains the local cache and might need a lot
of space for dealing with big repositories. Make sure you\(aqre aware of the associated
security aspects of the cache location: \fIcache_security\fP
.TP
.B BORG_CONFIG_DIR
Defaults to \fB$BORG_BASE_DIR/.config/borg\fP\&. If \fBBORG_BASE_DIR\fP is not explicitly set while
-\fI\%XDG env var\fP \fBXDG_CONFIG_HOME\fP is set, then \fB$XDG_CONFIG_HOME/borg\fP is being used instead.
+XDG env var
+ \fBXDG_CONFIG_HOME\fP is set, then \fB$XDG_CONFIG_HOME/borg\fP is being used instead.
This directory contains all borg configuration directories, see the FAQ
for a security advisory about the data in this directory: \fIhome_config_borg\fP
.TP
@@ -641,7 +621,8 @@ you need to point to the correct key file matching the repository the command wi
.TP
.B TMPDIR
This is where temporary files are stored (might need a lot of temporary space for some
-operations), see \fI\%tempfile\fP for details.
+operations), see tempfile
+ for details.
.UNINDENT
.TP
.B Building:
@@ -707,16 +688,19 @@ config file), but the code tries to work also if hardlinks are not supported.
.SS Units
.sp
To display quantities, Borg takes care of respecting the
-usual conventions of scale. Disk sizes are displayed in \fI\%decimal\fP, using powers of ten (so
-\fBkB\fP means 1000 bytes). For memory usage, \fI\%binary prefixes\fP are used, and are
-indicated using the \fI\%IEC binary prefixes\fP,
+usual conventions of scale. Disk sizes are displayed in decimal
+, using powers of ten (so
+\fBkB\fP means 1000 bytes). For memory usage, binary prefixes
+ are used, and are
+indicated using the IEC binary prefixes
+,
using powers of two (so \fBKiB\fP means 1024 bytes).
.SS Date and Time
.sp
We format date and time conforming to ISO\-8601, that is: YYYY\-MM\-DD and
HH:MM:SS (24h clock).
.sp
-For more information about that, see: \fI\%https://xkcd.com/1179/\fP
+For more information about that, see:
.sp
Unless otherwise noted, we display local date and time.
Internally, we store and process date and time as UTC.
@@ -763,7 +747,7 @@ borg check: the repository check computes the checksums of all chunks
borg delete repo: low CPU usage
.TP
.B CPU (only for client/server operation):
-When using borg in a client/server way with a \fI\%ssh:\-type\fP repo, the ssh
+When using borg in a client/server way with a repo, the ssh
processes used for the transport layer will need some CPU on the client and
on the server due to the crypto they are doing \- esp. if you are pumping
big amounts of data.
@@ -863,9 +847,8 @@ On some platforms additional features are supported:
.\" Yes/No's are grouped by reason/mechanism/reference.
.
.TS
-center;
-|l|l|l|l|.
-_
+box center;
+l|l|l|l.
T{
Platform
T} T{
@@ -948,7 +931,6 @@ No
T} T{
No
T}
-_
.TE
.sp
Other Unix\-like operating systems may work as well, but have not been tested at all.
@@ -986,15 +968,15 @@ The BSDs define additional flags.
\fIborg\-compression(1)\fP, \fIborg\-patterns(1)\fP, \fIborg\-placeholders(1)\fP
.INDENT 0.0
.IP \(bu 2
-Main web site \fI\%https://www.borgbackup.org/\fP
+Main web site
.IP \(bu 2
-Releases \fI\%https://github.com/borgbackup/borg/releases\fP
+Releases
.IP \(bu 2
-Changelog \fI\%https://github.com/borgbackup/borg/blob/master/docs/changes.rst\fP
+Changelog
.IP \(bu 2
-GitHub \fI\%https://github.com/borgbackup/borg\fP
+GitHub
.IP \(bu 2
-Security contact \fI\%https://borgbackup.readthedocs.io/en/latest/support.html#security\-contact\fP
+Security contact
.UNINDENT
.SH AUTHOR
The Borg Collective
diff --git a/docs/man/borgfs.1 b/docs/man/borgfs.1
index 40906746d..5a5e3cac0 100644
--- a/docs/man/borgfs.1
+++ b/docs/man/borgfs.1
@@ -27,7 +27,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 "2024-07-02" "" "borg backup tool"
+.TH "BORGFS" "1" "2025-04-18" "" "borg backup tool"
.SH NAME
borgfs \- Mount archive or an entire repository as a FUSE filesystem
.SH SYNOPSIS
@@ -35,10 +35,29 @@ borgfs \- Mount archive or an entire repository as a FUSE filesystem
borgfs [options] REPOSITORY_OR_ARCHIVE MOUNTPOINT [PATH...]
.SH DESCRIPTION
.sp
-This command mounts an archive as a FUSE filesystem. This can be useful for
-browsing an archive or restoring individual files. Unless the \fB\-\-foreground\fP
-option is given the command will run in the background until the filesystem
-is \fBumounted\fP\&.
+This command mounts a repository or an archive as a FUSE filesystem.
+This can be useful for browsing or restoring individual files.
+.sp
+When restoring, take into account that the current FUSE implementation does
+not support special fs flags and ACLs.
+.sp
+When mounting a repository, the top directories will be named like the
+archives and the directory structure below these will be loaded on\-demand from
+the repository when entering these directories, so expect some delay.
+.sp
+Unless the \fB\-\-foreground\fP option is given the command will run in the
+background until the filesystem is \fBumounted\fP\&.
+.sp
+Performance tips:
+.INDENT 0.0
+.IP \(bu 2
+when doing a \(dqwhole repository\(dq mount:
+do not enter archive dirs if not needed, this avoids on\-demand loading.
+.IP \(bu 2
+only mount a specific archive, not the whole repository.
+.IP \(bu 2
+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:
@@ -90,8 +109,8 @@ When the daemonized process receives a signal or crashes, it does not unmount.
Unmounting in these cases could cause an active rsync or similar process
to unintentionally delete data.
.sp
-When running in the foreground ^C/SIGINT unmounts cleanly, but other
-signals or crashes do not.
+When running in the foreground, ^C/SIGINT cleanly unmounts the filesystem,
+but other signals or crashes do not.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
@@ -107,7 +126,7 @@ where to mount filesystem
.B PATH
paths to extract; patterns are supported
.UNINDENT
-.SS optional arguments
+.SS options
.INDENT 0.0
.TP
.B \-V\fP,\fB \-\-version
diff --git a/docs/usage/check.rst.inc b/docs/usage/check.rst.inc
index 47bf1f7ce..cfa72d057 100644
--- a/docs/usage/check.rst.inc
+++ b/docs/usage/check.rst.inc
@@ -17,7 +17,7 @@ borg check
+-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| | ``REPOSITORY_OR_ARCHIVE`` | repository or archive to check consistency of |
+-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
- | **optional arguments** |
+ | **options** |
+-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| | ``--repository-only`` | only perform repository checks |
+-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
@@ -62,7 +62,7 @@ borg check
repository or archive to check consistency of
- optional arguments
+ options
--repository-only only perform repository checks
--archives-only only perform archives checks
--verify-data perform cryptographic archive data integrity verification (conflicts with ``--repository-only``)
diff --git a/docs/usage/compact.rst.inc b/docs/usage/compact.rst.inc
index 8187bbf7f..80343e5e7 100644
--- a/docs/usage/compact.rst.inc
+++ b/docs/usage/compact.rst.inc
@@ -17,7 +17,9 @@ borg compact
+-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
| | ``REPOSITORY`` | repository to compact |
+-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
- | **optional arguments** |
+ | **options** |
+ +-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
+ | | ``-n``, ``--dry-run`` | do nothing |
+-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
| | ``--cleanup-commits`` | cleanup commit-only 17-byte segment files |
+-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
@@ -42,9 +44,10 @@ borg compact
repository to compact
- optional arguments
- --cleanup-commits cleanup commit-only 17-byte segment files
- --threshold PERCENT set minimum threshold for saved space in PERCENT (Default: 10)
+ options
+ -n, --dry-run do nothing
+ --cleanup-commits cleanup commit-only 17-byte segment files
+ --threshold PERCENT set minimum threshold for saved space in PERCENT (Default: 10)
:ref:`common_options`
diff --git a/docs/usage/config.rst.inc b/docs/usage/config.rst.inc
index d90c327ee..9c5142b9f 100644
--- a/docs/usage/config.rst.inc
+++ b/docs/usage/config.rst.inc
@@ -21,7 +21,7 @@ borg config
+-------------------------------------------------------+----------------------+----------------------------------------+
| | ``VALUE`` | new value for key |
+-------------------------------------------------------+----------------------+----------------------------------------+
- | **optional arguments** |
+ | **options** |
+-------------------------------------------------------+----------------------+----------------------------------------+
| | ``-c``, ``--cache`` | get and set values from the repo cache |
+-------------------------------------------------------+----------------------+----------------------------------------+
@@ -52,7 +52,7 @@ borg config
new value for key
- optional arguments
+ options
-c, --cache get and set values from the repo cache
-d, --delete delete the key from the config file
-l, --list list the configuration of the repo
@@ -68,7 +68,7 @@ This command gets and sets options in a local repository or cache config file.
For security reasons, this command only works on local repositories.
To delete a config value entirely, use ``--delete``. To list the values
-of the configuration file or the default values, use ``--list``. To get and existing
+of the configuration file or the default values, use ``--list``. To get an existing
key, pass only the key name. To set a key, pass both the key name and
the new value. Keys can be specified in the format "section.name" or
simply "name"; the section will default to "repository" and "cache" for
diff --git a/docs/usage/create.rst.inc b/docs/usage/create.rst.inc
index b02b6003b..b38faaf4e 100644
--- a/docs/usage/create.rst.inc
+++ b/docs/usage/create.rst.inc
@@ -19,7 +19,7 @@ borg create
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``PATH`` | paths to archive |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | **optional arguments** |
+ | **options** |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-n``, ``--dry-run`` | do not create a backup archive |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -130,7 +130,7 @@ borg create
paths to archive
- optional arguments
+ options
-n, --dry-run do not create a backup archive
-s, --stats print statistics for the created archive
--list output verbose list of items (files, dirs, ...)
@@ -334,8 +334,8 @@ borg usually just stores their metadata:
Other flags used include:
- 'i' = backup data was read from standard input (stdin)
-- '-' = item would be included in archive(s) (if not in dry-run mode)
-- 'x' = item was excluded - or would be excluded from archive(s) (if not in dry-run mode)
+- '-' = dry run, item was *not* backed up
+- 'x' = excluded, item was *not* backed up
- '?' = missing status code (if you see this, please file a bug report!)
Reading backup data from stdin
@@ -384,4 +384,4 @@ to borg (maybe implementing your own recursion or your own rules), you can use
fail to create an archive should the command fail).
Borg supports paths with the slashdot hack to strip path prefixes here also.
-So, be careful not to unintentionally trigger that.
+So, be careful not to unintentionally trigger that.
\ No newline at end of file
diff --git a/docs/usage/delete.rst.inc b/docs/usage/delete.rst.inc
index 77246644f..46a21fa6a 100644
--- a/docs/usage/delete.rst.inc
+++ b/docs/usage/delete.rst.inc
@@ -19,7 +19,7 @@ borg delete
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| | ``ARCHIVE`` | archives to delete |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
- | **optional arguments** |
+ | **options** |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| | ``-n``, ``--dry-run`` | do not change repository |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
@@ -70,7 +70,7 @@ borg delete
archives to delete
- optional arguments
+ options
-n, --dry-run do not change repository
--list output verbose list of archives
-s, --stats print statistics for the deleted archive
diff --git a/docs/usage/diff.rst.inc b/docs/usage/diff.rst.inc
index 914d46a06..4bad260bb 100644
--- a/docs/usage/diff.rst.inc
+++ b/docs/usage/diff.rst.inc
@@ -21,7 +21,7 @@ borg diff
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| | ``PATH`` | paths of items inside the archives to compare; patterns are supported |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
- | **optional arguments** |
+ | **options** |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
| | ``--numeric-owner`` | deprecated, use ``--numeric-ids`` instead |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
@@ -68,7 +68,7 @@ borg diff
paths of items inside the archives to compare; patterns are supported
- optional arguments
+ options
--numeric-owner deprecated, use ``--numeric-ids`` instead
--numeric-ids only consider numeric user and group identifiers
--same-chunker-params Override check of chunker parameters.
diff --git a/docs/usage/export-tar.rst.inc b/docs/usage/export-tar.rst.inc
index 46334880a..cabfec740 100644
--- a/docs/usage/export-tar.rst.inc
+++ b/docs/usage/export-tar.rst.inc
@@ -21,7 +21,7 @@ borg export-tar
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``PATH`` | paths to extract; patterns are supported |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
- | **optional arguments** |
+ | **options** |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--tar-filter`` | filter program to pipe data through |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
@@ -62,7 +62,7 @@ borg export-tar
paths to extract; patterns are supported
- optional arguments
+ options
--tar-filter filter program to pipe data through
--list output verbose list of items (files, dirs, ...)
diff --git a/docs/usage/extract.rst.inc b/docs/usage/extract.rst.inc
index b233a846b..c928209f9 100644
--- a/docs/usage/extract.rst.inc
+++ b/docs/usage/extract.rst.inc
@@ -19,7 +19,7 @@ borg extract
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``PATH`` | paths to extract; patterns are supported |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
- | **optional arguments** |
+ | **options** |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--list`` | output verbose list of items (files, dirs, ...) |
+-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
@@ -74,7 +74,7 @@ borg extract
paths to extract; patterns are supported
- optional arguments
+ options
--list output verbose list of items (files, dirs, ...)
-n, --dry-run do not actually change any files
--numeric-owner deprecated, use ``--numeric-ids`` instead
diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc
index c10ca755b..c3d99a59d 100644
--- a/docs/usage/help.rst.inc
+++ b/docs/usage/help.rst.inc
@@ -91,6 +91,15 @@ Exclusions can be passed via the command line option ``--exclude``. When used
from within a shell, the patterns should be quoted to protect them from
expansion.
+Patterns matching special characters, e.g. white space, within a shell may
+require adjustments, such as putting quotation marks around the arguments.
+Example:
+Using bash, the following command line option would match and exclude "item name":
+``--pattern='-path/item name'``
+Note that when patterns are used within a pattern file directly read by borg,
+e.g. when using ``--exclude-from`` or ``--patterns-from``, there is no shell
+involved and thus no quotation marks are required.
+
The ``--exclude-from`` option permits loading exclusion patterns from a text
file with one pattern per line. Lines empty or starting with the number sign
('#') after removing whitespace on both ends are ignored. The optional style
@@ -369,7 +378,8 @@ auto,C[,L]
The heuristic tries with lz4 whether the data is compressible.
For incompressible data, it will not use compression (uses "none").
For compressible data, it uses the given C[,L] compression - with C[,L]
- being any valid compression specifier.
+ being any valid compression specifier. This can be helpful for media files
+ which often cannot be compressed much more.
obfuscate,SPEC,C[,L]
Use compressed-size obfuscation to make fingerprinting attacks based on
@@ -412,6 +422,15 @@ obfuscate,SPEC,C[,L]
...
123: 8MiB (max.)
+ *Padmé padding* (deterministic)
+
+ ::
+
+ 250: pads to sums of powers of 2, max 12% overhead
+
+ Uses the Padmé algorithm to deterministically pad the compressed size to a sum of
+ powers of 2, limiting overhead to 12%. See https://lbarman.ch/blog/padme/ for details.
+
Examples::
borg create --compression lz4 REPO::ARCHIVE data
@@ -424,4 +443,5 @@ Examples::
borg create --compression obfuscate,110,none ...
borg create --compression obfuscate,3,auto,zstd,10 ...
borg create --compression obfuscate,2,zstd,6 ...
+ borg create --compression obfuscate,250,zstd,3 ...
diff --git a/docs/usage/import-tar.rst.inc b/docs/usage/import-tar.rst.inc
index 033ea1614..0749627cd 100644
--- a/docs/usage/import-tar.rst.inc
+++ b/docs/usage/import-tar.rst.inc
@@ -19,7 +19,7 @@ borg import-tar
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
| | ``TARFILE`` | input tar file. "-" to read from stdin instead. |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
- | **optional arguments** |
+ | **options** |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
| | ``--tar-filter`` | filter program to pipe data through |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
@@ -66,7 +66,7 @@ borg import-tar
input tar file. "-" to read from stdin instead.
- optional arguments
+ 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, ...)
diff --git a/docs/usage/info.rst.inc b/docs/usage/info.rst.inc
index d77e485a0..d53ecf3cc 100644
--- a/docs/usage/info.rst.inc
+++ b/docs/usage/info.rst.inc
@@ -17,7 +17,7 @@ borg info
+-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| | ``REPOSITORY_OR_ARCHIVE`` | repository or archive to display information about |
+-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
- | **optional arguments** |
+ | **options** |
+-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| | ``--json`` | format output as JSON |
+-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
@@ -52,7 +52,7 @@ borg info
repository or archive to display information about
- optional arguments
+ options
--json format output as JSON
diff --git a/docs/usage/init.rst.inc b/docs/usage/init.rst.inc
index 52102fa0a..265a491a2 100644
--- a/docs/usage/init.rst.inc
+++ b/docs/usage/init.rst.inc
@@ -17,7 +17,7 @@ borg init
+-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``REPOSITORY`` | repository to create |
+-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | **optional arguments** |
+ | **options** |
+-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-e MODE``, ``--encryption MODE`` | select encryption key mode **(required)** |
+-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -46,7 +46,7 @@ borg init
repository to create
- optional arguments
+ options
-e MODE, --encryption MODE select encryption key mode **(required)**
--append-only create an append-only mode repository. Note that this only affects the low level structure of the repository, and running `delete` or `prune` will still be allowed. See :ref:`append_only_mode` in Additional Notes for more details.
--storage-quota QUOTA Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota.
diff --git a/docs/usage/key_export.rst.inc b/docs/usage/key_export.rst.inc
index 0a57bf091..319d8b8d8 100644
--- a/docs/usage/key_export.rst.inc
+++ b/docs/usage/key_export.rst.inc
@@ -19,7 +19,7 @@ borg key export
+-------------------------------------------------------+----------------+------------------------------------------------------------------------+
| | ``PATH`` | where to store the backup |
+-------------------------------------------------------+----------------+------------------------------------------------------------------------+
- | **optional arguments** |
+ | **options** |
+-------------------------------------------------------+----------------+------------------------------------------------------------------------+
| | ``--paper`` | Create an export suitable for printing and later type-in |
+-------------------------------------------------------+----------------+------------------------------------------------------------------------+
@@ -46,7 +46,7 @@ borg key export
where to store the backup
- optional arguments
+ options
--paper Create an export suitable for printing and later type-in
--qr-html Create an html file suitable for printing and later type-in or qr scan
diff --git a/docs/usage/key_import.rst.inc b/docs/usage/key_import.rst.inc
index a0890ff38..19afbe537 100644
--- a/docs/usage/key_import.rst.inc
+++ b/docs/usage/key_import.rst.inc
@@ -19,7 +19,7 @@ borg key import
+-------------------------------------------------------+----------------+----------------------------------------------------------+
| | ``PATH`` | path to the backup ('-' to read from stdin) |
+-------------------------------------------------------+----------------+----------------------------------------------------------+
- | **optional arguments** |
+ | **options** |
+-------------------------------------------------------+----------------+----------------------------------------------------------+
| | ``--paper`` | interactively import from a backup done with ``--paper`` |
+-------------------------------------------------------+----------------+----------------------------------------------------------+
@@ -44,7 +44,7 @@ borg key import
path to the backup ('-' to read from stdin)
- optional arguments
+ options
--paper interactively import from a backup done with ``--paper``
diff --git a/docs/usage/list.rst.inc b/docs/usage/list.rst.inc
index f48a7f515..d44d9d550 100644
--- a/docs/usage/list.rst.inc
+++ b/docs/usage/list.rst.inc
@@ -19,7 +19,7 @@ borg list
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``PATH`` | paths to list; patterns are supported |
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | **optional arguments** |
+ | **options** |
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--consider-checkpoints`` | Show checkpoint archives in the repository contents list (default: hidden). |
+-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -74,7 +74,7 @@ borg list
paths to list; patterns are supported
- optional arguments
+ options
--consider-checkpoints Show checkpoint archives in the repository contents list (default: hidden).
--short only print file/directory names, nothing else
--format FORMAT specify format for file or archive listing (default for files: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}"; for archives: "{archive:<36} {time} [{id}]{NL}")
diff --git a/docs/usage/mount.rst.inc b/docs/usage/mount.rst.inc
index 251f56cfe..1b5585938 100644
--- a/docs/usage/mount.rst.inc
+++ b/docs/usage/mount.rst.inc
@@ -21,7 +21,7 @@ borg mount
+-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| | ``PATH`` | paths to extract; patterns are supported |
+-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
- | **optional arguments** |
+ | **options** |
+-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| | ``--consider-checkpoints`` | Show checkpoint archives in the repository contents list (default: hidden). |
+-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
@@ -80,7 +80,7 @@ borg mount
paths to extract; patterns are supported
- optional arguments
+ options
--consider-checkpoints Show checkpoint archives in the repository contents list (default: hidden).
-f, --foreground stay in foreground, do not daemonize
-o Extra mount options
@@ -110,10 +110,25 @@ borg mount
Description
~~~~~~~~~~~
-This command mounts an archive as a FUSE filesystem. This can be useful for
-browsing an archive or restoring individual files. Unless the ``--foreground``
-option is given the command will run in the background until the filesystem
-is ``umounted``.
+This command mounts a repository or an archive as a FUSE filesystem.
+This can be useful for browsing or restoring individual files.
+
+When restoring, take into account that the current FUSE implementation does
+not support special fs flags and ACLs.
+
+When mounting a repository, the top directories will be named like the
+archives and the directory structure below these will be loaded on-demand from
+the repository when entering these directories, so expect some delay.
+
+Unless the ``--foreground`` option is given the command will run in the
+background until the filesystem is ``umounted``.
+
+Performance tips:
+
+- when doing a "whole repository" mount:
+ do not enter archive dirs if not needed, this avoids on-demand loading.
+- 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:
@@ -161,5 +176,5 @@ When the daemonized process receives a signal or crashes, it does not unmount.
Unmounting in these cases could cause an active rsync or similar process
to unintentionally delete data.
-When running in the foreground ^C/SIGINT unmounts cleanly, but other
-signals or crashes do not.
\ No newline at end of file
+When running in the foreground, ^C/SIGINT cleanly unmounts the filesystem,
+but other signals or crashes do not.
\ No newline at end of file
diff --git a/docs/usage/prune.rst.inc b/docs/usage/prune.rst.inc
index c57677bf7..49b36a6f4 100644
--- a/docs/usage/prune.rst.inc
+++ b/docs/usage/prune.rst.inc
@@ -17,7 +17,7 @@ borg prune
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| | ``REPOSITORY`` | repository to prune |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
- | **optional arguments** |
+ | **options** |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| | ``-n``, ``--dry-run`` | do not change repository |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
@@ -41,6 +41,10 @@ borg prune
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| | ``-m``, ``--keep-monthly`` | number of monthly archives to keep |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
+ | | ``--keep-13weekly`` | number of quarterly archives to keep (13 week strategy) |
+ +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
+ | | ``--keep-3monthly`` | number of quarterly archives to keep (3 month strategy) |
+ +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| | ``-y``, ``--keep-yearly`` | number of yearly archives to keep |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| | ``--save-space`` | work slower, but using less space |
@@ -72,7 +76,7 @@ borg prune
repository to prune
- optional arguments
+ options
-n, --dry-run do not change repository
--force force pruning of corrupted archives, use ``--force --force`` in case ``--force`` does not work.
-s, --stats print statistics for the deleted archive
@@ -84,6 +88,8 @@ borg prune
-d, --keep-daily number of daily archives to keep
-w, --keep-weekly number of weekly archives to keep
-m, --keep-monthly number of monthly archives to keep
+ --keep-13weekly number of quarterly archives to keep (13 week strategy)
+ --keep-3monthly number of quarterly archives to keep (3 month strategy)
-y, --keep-yearly number of yearly archives to keep
--save-space work slower, but using less space
-c SECONDS, --checkpoint-interval SECONDS write checkpoint every SECONDS seconds (Default: 1800)
@@ -141,9 +147,13 @@ starts is used for pruning purposes. Dates and times are interpreted in
the local timezone, and weeks go from Monday to Sunday. Specifying a
negative number of archives to keep means that there is no limit. As of borg
1.2.0, borg will retain the oldest archive if any of the secondly, minutely,
-hourly, daily, weekly, monthly, or yearly rules was not otherwise able to meet
-its retention target. This enables the first chronological archive to continue
-aging until it is replaced by a newer archive that meets the retention criteria.
+hourly, daily, weekly, monthly, quarterly, or yearly rules was not otherwise
+able to meet its retention target. This enables the first chronological archive
+to continue aging until it is replaced by a newer archive that meets the
+retention criteria.
+
+The ``--keep-13weekly`` and ``--keep-3monthly`` rules are two different
+strategies for keeping archives every quarter year.
The ``--keep-last N`` option is doing the same as ``--keep-secondly N`` (and it will
keep the last N archives under the assumption that you do not create more than one
diff --git a/docs/usage/recreate.rst.inc b/docs/usage/recreate.rst.inc
index d9c1302ee..22a6dc908 100644
--- a/docs/usage/recreate.rst.inc
+++ b/docs/usage/recreate.rst.inc
@@ -19,7 +19,7 @@ borg recreate
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``PATH`` | paths to recreate; patterns are supported |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | **optional arguments** |
+ | **options** |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--list`` | output verbose list of items (files, dirs, ...) |
+-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -82,7 +82,7 @@ borg recreate
paths to recreate; patterns are supported
- optional arguments
+ 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
diff --git a/docs/usage/serve.rst.inc b/docs/usage/serve.rst.inc
index 1c93098c1..e40692b5a 100644
--- a/docs/usage/serve.rst.inc
+++ b/docs/usage/serve.rst.inc
@@ -13,7 +13,7 @@ borg serve
.. class:: borg-options-table
+-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | **optional arguments** |
+ | **options** |
+-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--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 sub-directories is granted implicitly; PATH doesn't need to directly point to a repository. |
+-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -40,7 +40,7 @@ borg serve
- optional arguments
+ options
--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 sub-directories is granted implicitly; PATH doesn't need to directly point to a repository.
--restrict-to-repository PATH restrict repository access. Only the repository located at PATH (no sub-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path`` sub-directories are not accessible; PATH needs to directly point at 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.
--append-only only allow appending to repository segment files. Note that this only affects the low level structure of the repository, and running `delete` or `prune` will still be allowed. See :ref:`append_only_mode` in Additional Notes for more details.
diff --git a/docs/usage/upgrade.rst.inc b/docs/usage/upgrade.rst.inc
index 68499d895..fd02d0088 100644
--- a/docs/usage/upgrade.rst.inc
+++ b/docs/usage/upgrade.rst.inc
@@ -17,7 +17,7 @@ borg upgrade
+-------------------------------------------------------+--------------------------+------------------------------------------------------------------------------------------------+
| | ``REPOSITORY`` | path to the repository to be upgraded |
+-------------------------------------------------------+--------------------------+------------------------------------------------------------------------------------------------+
- | **optional arguments** |
+ | **options** |
+-------------------------------------------------------+--------------------------+------------------------------------------------------------------------------------------------+
| | ``-n``, ``--dry-run`` | do not change repository |
+-------------------------------------------------------+--------------------------+------------------------------------------------------------------------------------------------+
@@ -54,7 +54,7 @@ borg upgrade
path to the repository to be upgraded
- optional arguments
+ options
-n, --dry-run do not change repository
--inplace rewrite repository in place, with no chance of going back to older versions of the repository.
--force Force upgrade