build_usage, build_man

docs/man/borg-analyze.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-ANALYZE" 1 "2024-10-03" "" "borg backup tool"
+.TH "BORG-ANALYZE" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-analyze \- Analyze archives
 .SH SYNOPSIS

docs/man/borg-benchmark-cpu.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-CPU" 1 "2024-10-03" "" "borg backup tool"
+.TH "BORG-BENCHMARK-CPU" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-benchmark-cpu \- Benchmark CPU bound operations.
 .SH SYNOPSIS

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-10-03" "" "borg backup tool"
+.TH "BORG-BENCHMARK-CRUD" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
 .SH SYNOPSIS

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-10-03" "" "borg backup tool"
+.TH "BORG-BENCHMARK" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-benchmark \- benchmark command
 .SH SYNOPSIS

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-10-03" "" "borg backup tool"
+.TH "BORG-BREAK-LOCK" 1 "2024-10-31" "" "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

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-10-03" "" "borg backup tool"
+.TH "BORG-CHECK" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-check \- Check repository consistency
 .SH SYNOPSIS
@@ -44,8 +44,8 @@ the file magic headers, and both the metadata and data of all objects in
 the repository. The read data is checked by size and hash. Bit rot and other
 types of accidental damage can be detected this way. Running the repository
 check can be split into multiple partial checks using \fB\-\-max\-duration\fP\&.
-When checking a remote repository, please note that the checks run on the
-server and do not cause significant network traffic.
+When checking a \fI\%ssh://\fP remote repository, please note that the checks run on
+the server and do not cause significant network traffic.
 .IP 2. 3
 Checking consistency and correctness of the archive metadata and optionally
 archive data (requires \fB\-\-verify\-data\fP). This includes ensuring that the

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-10-03" "" "borg backup tool"
+.TH "BORG-COMMON" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-common \- Common options of Borg commands
 .SH SYNOPSIS

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-10-03" "" "borg backup tool"
+.TH "BORG-COMPACT" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-compact \- Collect garbage in repository
 .SH SYNOPSIS

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-10-03" "" "borg backup tool"
+.TH "BORG-COMPRESSION" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-compression \- Details regarding compression
 .SH DESCRIPTION

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-10-03" "" "borg backup tool"
+.TH "BORG-CREATE" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-create \- Create new archive
 .SH SYNOPSIS

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-10-03" "" "borg backup tool"
+.TH "BORG-DELETE" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-delete \- Delete archives
 .SH SYNOPSIS

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-10-03" "" "borg backup tool"
+.TH "BORG-DIFF" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-diff \- Diff contents of two archives
 .SH SYNOPSIS

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-10-03" "" "borg backup tool"
+.TH "BORG-EXPORT-TAR" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-export-tar \- Export archive contents as a tarball
 .SH SYNOPSIS
@@ -86,6 +86,7 @@ T}	T{
 POSIX.1\-2001 (pax) format
 T}	T{
 GNU + atime/ctime/mtime ns
++ xattrs
 T}
 _
 T{

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-10-03" "" "borg backup tool"
+.TH "BORG-EXTRACT" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-extract \- Extract archive contents
 .SH SYNOPSIS

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-10-03" "" "borg backup tool"
+.TH "BORG-IMPORT-TAR" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-import-tar \- Create a backup archive from a tarball
 .SH SYNOPSIS

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-10-03" "" "borg backup tool"
+.TH "BORG-INFO" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-info \- Show archive details such as disk space used
 .SH SYNOPSIS

docs/man/borg-key-change-location.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-LOCATION" 1 "2024-10-03" "" "borg backup tool"
+.TH "BORG-KEY-CHANGE-LOCATION" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-key-change-location \- Change repository key location
 .SH SYNOPSIS

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-10-03" "" "borg backup tool"
+.TH "BORG-KEY-CHANGE-PASSPHRASE" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-key-change-passphrase \- Change repository key file passphrase
 .SH SYNOPSIS

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-10-03" "" "borg backup tool"
+.TH "BORG-KEY-EXPORT" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-key-export \- Export the repository key for backup
 .SH SYNOPSIS

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-10-03" "" "borg backup tool"
+.TH "BORG-KEY-IMPORT" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-key-import \- Import the repository key from backup
 .SH SYNOPSIS

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-10-03" "" "borg backup tool"
+.TH "BORG-KEY" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-key \- Manage a keyfile or repokey of a repository
 .SH SYNOPSIS

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-10-03" "" "borg backup tool"
+.TH "BORG-LIST" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-list \- List archive contents
 .SH SYNOPSIS

docs/man/borg-match-archives.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-MATCH-ARCHIVES" 1 "2024-10-03" "" "borg backup tool"
+.TH "BORG-MATCH-ARCHIVES" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-match-archives \- Details regarding match-archives
 .SH DESCRIPTION

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-10-03" "" "borg backup tool"
+.TH "BORG-MOUNT" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-mount \- Mount archive or an entire repository as a FUSE filesystem
 .SH SYNOPSIS
@@ -35,14 +35,30 @@ borg-mount \- Mount archive or an entire repository as a FUSE filesystem
 borg [common options] mount [options] 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. When restoring,
-take into account that the current FUSE implementation does not support
-special fs flags and ACLs.
+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:
 \fB/path/to/repo /mnt/point fuse.borgfs defaults,noauto 0 0\fP

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-10-03" "" "borg backup tool"
+.TH "BORG-PATTERNS" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-patterns \- Details regarding patterns
 .SH DESCRIPTION

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-10-03" "" "borg backup tool"
+.TH "BORG-PLACEHOLDERS" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-placeholders \- Details regarding placeholders
 .SH DESCRIPTION

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-10-03" "" "borg backup tool"
+.TH "BORG-PRUNE" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-prune \- Prune repository archives according to specified rules
 .SH SYNOPSIS
@@ -72,10 +72,15 @@ rules do not count towards those of later rules. The time that each backup
 starts is used for pruning purposes. Dates and times are interpreted in the local
 timezone of the system where borg prune runs, and weeks go from Monday to Sunday.
 Specifying a negative number of archives to keep means that there is no limit.
-As of borg 1.2.0, borg will retain the oldest archive if any of the secondly,
-minutely, hourly, daily, weekly, monthly, or yearly rules was not otherwise able to
-meet its retention target. This enables the first chronological archive to continue
-aging until it is replaced by a newer archive that meets the retention criteria.
+.sp
+Borg will retain the oldest archive if any of the secondly, minutely, 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
@@ -135,6 +140,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
 .UNINDENT

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-10-03" "" "borg backup tool"
+.TH "BORG-RECREATE" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-recreate \- Re-create archives
 .SH SYNOPSIS

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-10-03" "" "borg backup tool"
+.TH "BORG-RENAME" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-rename \- Rename an existing archive
 .SH SYNOPSIS

docs/man/borg-repo-compress.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-REPO-COMPRESS" 1 "2024-10-03" "" "borg backup tool"
+.TH "BORG-REPO-COMPRESS" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-repo-compress \- Repository (re-)compression
 .SH SYNOPSIS

docs/man/borg-repo-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-REPO-CREATE" 1 "2024-10-03" "" "borg backup tool"
+.TH "BORG-REPO-CREATE" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-repo-create \- Create a new, empty repository
 .SH SYNOPSIS
@@ -37,6 +37,10 @@ borg [common options] repo\-create [options]
 .sp
 This command creates a new, empty repository. A repository is a \fBborgstore\fP store
 containing the deduplicated data from zero or more archives.
+.sp
+Repository creation can be quite slow for some kinds of stores (e.g. for \fBsftp:\fP) \-
+this is due to borgstore pre\-creating all directories needed, making usage of the
+store faster.
 .SS Encryption mode TLDR
 .sp
 The encryption mode can only be configured when creating a new repository \- you can

docs/man/borg-repo-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-REPO-DELETE" 1 "2024-10-03" "" "borg backup tool"
+.TH "BORG-REPO-DELETE" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-repo-delete \- Delete a repository
 .SH SYNOPSIS

docs/man/borg-repo-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-REPO-INFO" 1 "2024-10-03" "" "borg backup tool"
+.TH "BORG-REPO-INFO" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-repo-info \- Show repository infos
 .SH SYNOPSIS

docs/man/borg-repo-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-REPO-LIST" 1 "2024-10-03" "" "borg backup tool"
+.TH "BORG-REPO-LIST" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-repo-list \- List the archives contained in a repository
 .SH SYNOPSIS

docs/man/borg-repo-space.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-REPO-SPACE" 1 "2024-10-03" "" "borg backup tool"
+.TH "BORG-REPO-SPACE" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-repo-space \- Manage reserved space in repository
 .SH SYNOPSIS

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-10-03" "" "borg backup tool"
+.TH "BORG-SERVE" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-serve \- Start in server mode. This command is usually not used manually.
 .SH SYNOPSIS

docs/man/borg-tag.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-TAG" 1 "2024-10-03" "" "borg backup tool"
+.TH "BORG-TAG" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-tag \- Manage tags
 .SH SYNOPSIS
@@ -41,6 +41,15 @@ Borg archives can have a set of tags which can be used for matching archives.
 .sp
 You can set the tags to a specific set of tags or you can add or remove
 tags from the current set of tags.
+.sp
+User defined tags must not start with \fI@\fP because such tags are considered
+special and users are only allowed to use known special tags:
+.sp
+\fB@PROT\fP: protects archives against archive deletion or pruning.
+.sp
+Pre\-existing special tags can not be removed via \fB\-\-set\fP\&. You can still use
+\fB\-\-set\fP, but you must give pre\-existing special tags also (so they won\(aqt be
+removed).
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.

docs/man/borg-transfer.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-TRANSFER" 1 "2024-10-03" "" "borg backup tool"
+.TH "BORG-TRANSFER" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-transfer \- archives transfer from other repository, optionally upgrade data format
 .SH SYNOPSIS

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-10-03" "" "borg backup tool"
+.TH "BORG-UMOUNT" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-umount \- un-mount the FUSE filesystem
 .SH SYNOPSIS

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-10-03" "" "borg backup tool"
+.TH "BORG-VERSION" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-version \- Display the borg client / borg server version
 .SH SYNOPSIS

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-10-03" "" "borg backup tool"
+.TH "BORG-WITH-LOCK" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg-with-lock \- run a user specified command with the repository lock held
 .SH SYNOPSIS

docs/man/borg.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" 1 "2024-10-03" "" "borg backup tool"
+.TH "BORG" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borg \- deduplicating and encrypting backup tool
 .SH SYNOPSIS
@@ -230,21 +230,21 @@ 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:
 .sp
-\fBssh://user@host:port/path/to/repo\fP \- absolute path
+\fBssh://user@host:port//abs/path/to/repo\fP \- absolute path
 .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
+\fBssh://user@host:port/rel/path/to/repo\fP \- path relative to current directory
 .sp
 \fBRemote repositories\fP accessed via sftp:
 .sp
-\fBsftp://user@host:port/path/to/repo\fP \- absolute path
+\fBsftp://user@host:port//abs/path/to/repo\fP \- absolute path
+.sp
+\fBsftp://user@host:port/rel/path/to/repo\fP \- path relative to current directory
 .sp
 For ssh and sftp URLs, the \fBuser@\fP and \fB:port\fP parts are optional.
 .sp
 \fBRemote repositories\fP accessed via rclone:
 .sp
-\fBrclone://remote:path\fP \- see the rclone docs for more details.
+\fBrclone:remote:path\fP \- see the rclone docs for more details about remote:path.
 .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:
@@ -253,7 +253,7 @@ If you frequently need the same repo URL, it is a good idea to set the
 .sp
 .nf
 .ft C
-export BORG_REPO=\(aqssh://user@host:port/path/to/repo\(aq
+export BORG_REPO=\(aqssh://user@host:port/rel/path/to/repo\(aq
 .ft P
 .fi
 .UNINDENT
@@ -382,6 +382,8 @@ _
 .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:

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-10-03" "" "borg backup tool"
+.TH "BORGFS" 1 "2024-10-31" "" "borg backup tool"
 .SH NAME
 borgfs \- Mount archive or an entire repository as a FUSE filesystem
 .SH SYNOPSIS

docs/usage/check.rst.inc

@@ -96,8 +96,8 @@ It consists of two major steps:
    the repository. The read data is checked by size and hash. Bit rot and other
    types of accidental damage can be detected this way. Running the repository
    check can be split into multiple partial checks using ``--max-duration``.
-   When checking a remote repository, please note that the checks run on the
-   server and do not cause significant network traffic.
+   When checking a ssh:// remote repository, please note that the checks run on
+   the server and do not cause significant network traffic.
 
 2. Checking consistency and correctness of the archive metadata and optionally
    archive data (requires ``--verify-data``). This includes ensuring that the

docs/usage/export-tar.rst.inc

@@ -110,6 +110,7 @@ Depending on the ``-tar-format`` option, these formats are created:
 | BORG         | BORG specific, like PAX   | all as supported by borg   |
 +--------------+---------------------------+----------------------------+
 | PAX          | POSIX.1-2001 (pax) format | GNU + atime/ctime/mtime ns |
+|              |                           | + xattrs                   |
 +--------------+---------------------------+----------------------------+
 | GNU          | GNU tar format            | mtime s, no atime/ctime,   |
 |              |                           | no ACLs/xattrs/bsdflags    |

docs/usage/mount.rst.inc

@@ -109,14 +109,26 @@ borg mount
 Description
 ~~~~~~~~~~~
 
-This command mounts an archive as a FUSE filesystem. This can be useful
-for browsing an archive or restoring individual files. When restoring,
-take into account that the current FUSE implementation does not support
-special fs flags and ACLs.
+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:
 ``/path/to/repo /mnt/point fuse.borgfs defaults,noauto 0 0``

docs/usage/prune.rst.inc

@@ -45,6 +45,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                                                                 |
     +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
     | .. class:: borg-common-opt-ref                                                                                                                                                                                                 |
@@ -92,6 +96,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
 
 
@@ -146,10 +152,15 @@ rules do not count towards those of later rules. The time that each backup
 starts is used for pruning purposes. Dates and times are interpreted in the local
 timezone of the system where borg prune runs, 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.
+
+Borg will retain the oldest archive if any of the secondly, minutely, 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

docs/usage/repo-create.rst.inc

@@ -65,6 +65,10 @@ Description
 This command creates a new, empty repository. A repository is a ``borgstore`` store
 containing the deduplicated data from zero or more archives.
 
+Repository creation can be quite slow for some kinds of stores (e.g. for ``sftp:``) -
+this is due to borgstore pre-creating all directories needed, making usage of the
+store faster.
+
 Encryption mode TLDR
 ++++++++++++++++++++
 

docs/usage/tag.rst.inc

@@ -90,4 +90,13 @@ Manage archive tags.
 Borg archives can have a set of tags which can be used for matching archives.
 
 You can set the tags to a specific set of tags or you can add or remove
-tags from the current set of tags.
+tags from the current set of tags.
+
+User defined tags must not start with `@` because such tags are considered
+special and users are only allowed to use known special tags:
+
+``@PROT``: protects archives against archive deletion or pruning.
+
+Pre-existing special tags can not be removed via ``--set``. You can still use
+``--set``, but you must give pre-existing special tags also (so they won't be
+removed).