build_usage build_man

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-09-09" "" "borg backup tool"
+.TH "BORG-BENCHMARK-CPU" 1 "2024-09-26" "" "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-09-09" "" "borg backup tool"
+.TH "BORG-BENCHMARK-CRUD" 1 "2024-09-26" "" "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-09-09" "" "borg backup tool"
+.TH "BORG-BENCHMARK" 1 "2024-09-26" "" "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-09-09" "" "borg backup tool"
+.TH "BORG-BREAK-LOCK" 1 "2024-09-26" "" "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-09-09" "" "borg backup tool"
+.TH "BORG-CHECK" 1 "2024-09-26" "" "borg backup tool"
 .SH NAME
 borg-check \- Check repository consistency
 .SH SYNOPSIS

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-09-09" "" "borg backup tool"
+.TH "BORG-COMMON" 1 "2024-09-26" "" "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-09-09" "" "borg backup tool"
+.TH "BORG-COMPACT" 1 "2024-09-26" "" "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-09-09" "" "borg backup tool"
+.TH "BORG-COMPRESSION" 1 "2024-09-26" "" "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-09-09" "" "borg backup tool"
+.TH "BORG-CREATE" 1 "2024-09-26" "" "borg backup tool"
 .SH NAME
 borg-create \- Create new archive
 .SH SYNOPSIS
@@ -53,7 +53,9 @@ stdin\fP below for details.
 The archive will consume almost no disk space for files or parts of files that
 have already been stored in other archives.
 .sp
-The archive name needs to be unique.
+The archive name does NOT need to be unique, you can and should use the same
+name for a series of archives. The unique archive identifier is its ID (hash)
+and you can abbreviate the ID as long as it is unique.
 .sp
 In the archive name, you may use the following placeholders:
 {now}, {utcnow}, {fqdn}, {hostname}, {user} and some others.
@@ -153,9 +155,6 @@ only display items with the given status characters (see description)
 .B  \-\-json
 output stats as JSON. Implies \fB\-\-stats\fP\&.
 .TP
-.B  \-\-prefer\-adhoc\-cache
-experimental: prefer AdHocCache (w/o files cache) over AdHocWithFilesCache (with files cache).
-.TP
 .BI \-\-stdin\-name \ NAME
 use NAME in archive for stdin data (default: \(aqstdin\(aq)
 .TP
@@ -283,18 +282,18 @@ $ borg create my\-files                \e
 # /home/<one directory>/.thumbnails is excluded, not /home/*/*/.thumbnails etc.)
 $ borg create my\-files /home \-\-exclude \(aqsh:home/*/.thumbnails\(aq
 
-# Backup the root filesystem into an archive named \(dqroot\-YYYY\-MM\-DD\(dq
+# Backup the root filesystem into an archive named \(dqroot\-archive\(dq
 # use zlib compression (good, but slow) \- default is lz4 (fast, low compression ratio)
-$ borg create \-C zlib,6 \-\-one\-file\-system root\-{now:%Y\-%m\-%d} /
+$ borg create \-C zlib,6 \-\-one\-file\-system root\-archive /
 
-# Backup into an archive name like FQDN\-root\-TIMESTAMP
-$ borg create \(aq{fqdn}\-root\-{now}\(aq /
+# Backup into an archive name like FQDN\-root
+$ borg create \(aq{fqdn}\-root\(aq /
 
 # Backup a remote host locally (\(dqpull\(dq style) using sshfs
 $ mkdir sshfs\-mount
 $ sshfs root@example.com:/ sshfs\-mount
 $ cd sshfs\-mount
-$ borg create example.com\-root\-{now:%Y\-%m\-%d} .
+$ borg create example.com\-root .
 $ cd ..
 $ fusermount \-u sshfs\-mount
 
@@ -323,17 +322,13 @@ $ borg create \-\-compression lzma,N arch ~
 # Only compress compressible data with lzma,N (N = 0..9)
 $ borg create \-\-compression auto,lzma,N arch ~
 
-# Use short hostname, user name and current time in archive name
-$ borg create \(aq{hostname}\-{user}\-{now}\(aq ~
-# Similar, use the same datetime format that is default as of borg 1.1
-$ borg create \(aq{hostname}\-{user}\-{now:%Y\-%m\-%dT%H:%M:%S}\(aq ~
-# As above, but add nanoseconds
-$ borg create \(aq{hostname}\-{user}\-{now:%Y\-%m\-%dT%H:%M:%S.%f}\(aq ~
+# Use short hostname and user name as archive name
+$ borg create \(aq{hostname}\-{user}\(aq ~
 
 # Backing up relative paths by moving into the correct directory first
 $ cd /home/user/Documents
 # The root directory of the archive will be \(dqprojectA\(dq
-$ borg create \(aqdaily\-projectA\-{now:%Y\-%m\-%d}\(aq projectA
+$ borg create \(aqdaily\-projectA\(aq projectA
 
 # Use external command to determine files to archive
 # Use \-\-paths\-from\-stdin with find to back up only files less than 1MB in size

docs/man/borg-delete.1

@@ -27,12 +27,12 @@ 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-09-09" "" "borg backup tool"
+.TH "BORG-DELETE" 1 "2024-09-26" "" "borg backup tool"
 .SH NAME
 borg-delete \- Delete archives
 .SH SYNOPSIS
 .sp
-borg [common options] delete [options]
+borg [common options] delete [options] [NAME]
 .SH DESCRIPTION
 .sp
 This command deletes archives from the repository.
@@ -48,6 +48,12 @@ see \fIborg_patterns\fP).
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS arguments
+.INDENT 0.0
+.TP
+.B NAME
+specify the archive name
+.UNINDENT
 .SS optional arguments
 .INDENT 0.0
 .TP
@@ -90,11 +96,14 @@ consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m.
 .sp
 .nf
 .ft C
-# delete a single backup archive:
-$ borg delete \-a Monday
+# delete all backup archives named \(dqkenny\-files\(dq:
+$ borg delete \-a kenny\-files
 # actually free disk space:
 $ borg compact
 
+# delete a specific backup archive using its unique archive ID prefix
+$ borg delete aid:d34db33f
+
 # delete all archives whose names begin with the machine\(aqs hostname followed by \(dq\-\(dq
 $ borg delete \-a \(aqsh:{hostname}\-*\(aq
 

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-09-09" "" "borg backup tool"
+.TH "BORG-DIFF" 1 "2024-09-26" "" "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-09-09" "" "borg backup tool"
+.TH "BORG-EXPORT-TAR" 1 "2024-09-26" "" "borg backup tool"
 .SH NAME
 borg-export-tar \- Export archive contents as a tarball
 .SH SYNOPSIS

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-09-09" "" "borg backup tool"
+.TH "BORG-EXTRACT" 1 "2024-09-26" "" "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-09-09" "" "borg backup tool"
+.TH "BORG-IMPORT-TAR" 1 "2024-09-26" "" "borg backup tool"
 .SH NAME
 borg-import-tar \- Create a backup archive from a tarball
 .SH SYNOPSIS
@@ -170,9 +170,9 @@ Outputs a script that copies all archives from repo1 to repo2:
 .sp
 .nf
 .ft C
-for A T in \(gaborg list \-\-format=\(aq{archive} {time:%Y\-%m\-%dT%H:%M:%S}{NL}\(aq\(ga
+for N I T in \(gaborg list \-\-format=\(aq{archive} {id} {time:%Y\-%m\-%dT%H:%M:%S}{NL}\(aq\(ga
 do
-  echo \(dqborg \-r repo1 export\-tar \-\-tar\-format=BORG $A \- | borg \-r repo2 import\-tar \-\-timestamp=$T $A \-\(dq
+  echo \(dqborg \-r repo1 export\-tar \-\-tar\-format=BORG aid:$I \- | borg \-r repo2 import\-tar \-\-timestamp=$T $N \-\(dq
 done
 .ft P
 .fi

docs/man/borg-info.1

@@ -27,12 +27,12 @@ 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-09-09" "" "borg backup tool"
+.TH "BORG-INFO" 1 "2024-09-26" "" "borg backup tool"
 .SH NAME
 borg-info \- Show archive details such as disk space used
 .SH SYNOPSIS
 .sp
-borg [common options] info [options]
+borg [common options] info [options] [NAME]
 .SH DESCRIPTION
 .sp
 This command displays detailed information about the specified archive.
@@ -48,6 +48,12 @@ All archives / deduplicated size = amount of data stored in the repo
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS arguments
+.INDENT 0.0
+.TP
+.B NAME
+specify the archive name
+.UNINDENT
 .SS optional arguments
 .INDENT 0.0
 .TP
@@ -87,8 +93,8 @@ consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m.
 .sp
 .nf
 .ft C
-$ borg info Tuesday2022\-06\-25T20:51:39
-Archive name: Tuesday2022\-06\-25T20:51:39
+$ borg info aid:f7dea078
+Archive name: source\-backup
 Archive fingerprint: f7dea0788dfc026cc2be1c0f5b94beb4e4084eb3402fc40c38d8719b1bf2d943
 Comment:
 Hostname: mba2020
@@ -96,7 +102,7 @@ Username: tw
 Time (start): Sat, 2022\-06\-25 20:51:40
 Time (end): Sat, 2022\-06\-25 20:51:40
 Duration: 0.03 seconds
-Command line: /Users/tw/w/borg\-env/bin/borg \-r path/to/repo create \-\-stats \(aqTuesday{now}\(aq src \-\-progress
+Command line: /usr/bin/borg \-r path/to/repo create source\-backup src
 Utilization of maximum supported archive size: 0%
 Number of files: 244
 Original size: 13.80 MB

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-09-09" "" "borg backup tool"
+.TH "BORG-KEY-CHANGE-LOCATION" 1 "2024-09-26" "" "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-09-09" "" "borg backup tool"
+.TH "BORG-KEY-CHANGE-PASSPHRASE" 1 "2024-09-26" "" "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-09-09" "" "borg backup tool"
+.TH "BORG-KEY-EXPORT" 1 "2024-09-26" "" "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-09-09" "" "borg backup tool"
+.TH "BORG-KEY-IMPORT" 1 "2024-09-26" "" "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-09-09" "" "borg backup tool"
+.TH "BORG-KEY" 1 "2024-09-26" "" "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-09-09" "" "borg backup tool"
+.TH "BORG-LIST" 1 "2024-09-26" "" "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-09-09" "" "borg backup tool"
+.TH "BORG-MATCH-ARCHIVES" 1 "2024-09-26" "" "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-09-09" "" "borg backup tool"
+.TH "BORG-MOUNT" 1 "2024-09-26" "" "borg backup tool"
 .SH NAME
 borg-mount \- Mount archive or an entire repository as a FUSE filesystem
 .SH SYNOPSIS

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

docs/man/borg-prune.1

@@ -27,12 +27,12 @@ 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-09-09" "" "borg backup tool"
+.TH "BORG-PRUNE" 1 "2024-09-26" "" "borg backup tool"
 .SH NAME
 borg-prune \- Prune repository archives according to specified rules
 .SH SYNOPSIS
 .sp
-borg [common options] prune [options]
+borg [common options] prune [options] [NAME]
 .SH DESCRIPTION
 .sp
 The prune command prunes a repository by deleting all archives not matching
@@ -45,17 +45,18 @@ certain number of historic backups. This retention policy is commonly referred t
 \fI\%GFS\fP
 (Grandfather\-father\-son) backup rotation scheme.
 .sp
-If you use \-\-match\-archives (\-a), then only archives that match the pattern are
-considered for deletion and only those archives count towards the totals
-specified by the rules.
+The recommended way to use prune is to give the archive series name to it via the
+NAME argument (assuming you have the same name for all archives in a series).
+Alternatively, you can also use \-\-match\-archives (\-a), then only archives that
+match the pattern are considered for deletion and only those archives count
+towards the totals specified by the rules.
 Otherwise, \fIall\fP archives in the repository are candidates for deletion!
 There is no automatic distinction between archives representing different
 contents. These need to be distinguished by specifying matching globs.
 .sp
-If you have multiple sequences of archives with different data sets (e.g.
+If you have multiple series of archives with different data sets (e.g.
 from different machines) in one shared repository, use one prune call per
-data set that matches only the respective archives using the \-\-match\-archives
-(\-a) option.
+series.
 .sp
 The \fB\-\-keep\-within\fP option takes an argument of the form \(dq<int><char>\(dq,
 where char is \(dqH\(dq, \(dqd\(dq, \(dqw\(dq, \(dqm\(dq, \(dqy\(dq. For example, \fB\-\-keep\-within 2d\fP means
@@ -86,6 +87,12 @@ the \fBborg repo\-list\fP description for more details about the format string).
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS arguments
+.INDENT 0.0
+.TP
+.B NAME
+specify the archive name
+.UNINDENT
 .SS optional arguments
 .INDENT 0.0
 .TP
@@ -155,12 +162,21 @@ Be careful, prune is a potentially dangerous command, it will remove backup
 archives.
 .sp
 The default of prune is to apply to \fBall archives in the repository\fP unless
-you restrict its operation to a subset of the archives using \fB\-a\fP / \fB\-\-match\-archives\fP\&.
+you restrict its operation to a subset of the archives.
+.sp
+The recommended way to name archives (with \fBborg create\fP) is to use the
+identical archive name within a series of archives. Then you can simply give
+that name to prune also, so it operates just on that series of archives.
+.sp
+Alternatively, you can use \fB\-a\fP / \fB\-\-match\-archives\fP to do a match on the
+archive names to select some of them.
 When using \fB\-a\fP, be careful to choose a good pattern \- e.g. do not use a
 prefix \(dqfoo\(dq if you do not also want to match \(dqfoobar\(dq.
 .sp
 It is strongly recommended to always run \fBprune \-v \-\-list \-\-dry\-run ...\fP
 first so you will see what it would do without it actually doing anything.
+.sp
+Don\(aqt forget to run \fBborg compact \-v\fP after prune to actually free disk space.
 .INDENT 0.0
 .INDENT 3.5
 .sp
@@ -170,11 +186,12 @@ first so you will see what it would do without it actually doing anything.
 # Do a dry\-run without actually deleting anything.
 $ borg prune \-v \-\-list \-\-dry\-run \-\-keep\-daily=7 \-\-keep\-weekly=4
 
-# Same as above but only apply to archive names starting with the hostname
+# Similar as above but only apply to the archive series named \(aq{hostname}\(aq:
+$ borg prune \-v \-\-list \-\-keep\-daily=7 \-\-keep\-weekly=4 \(aq{hostname}\(aq
+
+# Similar as above but apply to archive names starting with the hostname
 # of the machine followed by a \(dq\-\(dq character:
 $ borg prune \-v \-\-list \-\-keep\-daily=7 \-\-keep\-weekly=4 \-a \(aqsh:{hostname}\-*\(aq
-# actually free disk space:
-$ borg compact
 
 # Keep 7 end of day, 4 additional end of week archives,
 # and an end of month archive for every month:

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-09-09" "" "borg backup tool"
+.TH "BORG-RECREATE" 1 "2024-09-26" "" "borg backup tool"
 .SH NAME
 borg-recreate \- Re-create archives
 .SH SYNOPSIS
@@ -155,7 +155,7 @@ consider archives older than (now \- TIMESPAN), e.g. 7d or 12m.
 consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m.
 .TP
 .BI \-\-target \ TARGET
-create a new archive with the name ARCHIVE, do not replace existing archive (only applies for a single archive)
+create a new archive with the name ARCHIVE, do not replace existing archive
 .TP
 .BI \-\-comment \ COMMENT
 add a comment text to the archive

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-09-09" "" "borg backup tool"
+.TH "BORG-RENAME" 1 "2024-09-26" "" "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-09-09" "" "borg backup tool"
+.TH "BORG-REPO-COMPRESS" 1 "2024-09-26" "" "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-09-09" "" "borg backup tool"
+.TH "BORG-REPO-CREATE" 1 "2024-09-26" "" "borg backup tool"
 .SH NAME
 borg-repo-create \- Create a new, empty repository
 .SH SYNOPSIS

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-09-09" "" "borg backup tool"
+.TH "BORG-REPO-DELETE" 1 "2024-09-26" "" "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-09-09" "" "borg backup tool"
+.TH "BORG-REPO-INFO" 1 "2024-09-26" "" "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-09-09" "" "borg backup tool"
+.TH "BORG-REPO-LIST" 1 "2024-09-26" "" "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-09-09" "" "borg backup tool"
+.TH "BORG-REPO-SPACE" 1 "2024-09-26" "" "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-09-09" "" "borg backup tool"
+.TH "BORG-SERVE" 1 "2024-09-26" "" "borg backup tool"
 .SH NAME
 borg-serve \- Start in server mode. This command is usually not used manually.
 .SH SYNOPSIS

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-09-09" "" "borg backup tool"
+.TH "BORG-TRANSFER" 1 "2024-09-26" "" "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-09-09" "" "borg backup tool"
+.TH "BORG-UMOUNT" 1 "2024-09-26" "" "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-09-09" "" "borg backup tool"
+.TH "BORG-VERSION" 1 "2024-09-26" "" "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-09-09" "" "borg backup tool"
+.TH "BORG-WITH-LOCK" 1 "2024-09-26" "" "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-09-09" "" "borg backup tool"
+.TH "BORG" 1 "2024-09-26" "" "borg backup tool"
 .SH NAME
 borg \- deduplicating and encrypting backup tool
 .SH SYNOPSIS
@@ -67,25 +67,25 @@ $ borg \-r /path/to/repo repo\-create \-\-encryption=repokey\-aes\-ocb
 .UNINDENT
 .IP 2. 3
 Back up the \fB~/src\fP and \fB~/Documents\fP directories into an archive called
-\fIMonday\fP:
+\fIdocs\fP:
 .INDENT 3.0
 .INDENT 3.5
 .sp
 .nf
 .ft C
-$ borg \-r /path/to/repo create Monday ~/src ~/Documents
+$ borg \-r /path/to/repo create docs ~/src ~/Documents
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
 .IP 3. 3
-The next day create a new archive called \fITuesday\fP:
+The next day create a new archive using the same archive name:
 .INDENT 3.0
 .INDENT 3.5
 .sp
 .nf
 .ft C
-$ borg \-r /path/to/repo create \-\-stats Tuesday ~/src ~/Documents
+$ borg \-r /path/to/repo create \-\-stats docs ~/src ~/Documents
 .ft P
 .fi
 .UNINDENT
@@ -101,7 +101,7 @@ size (the amount of unique data not shared with other archives):
 .nf
 .ft C
 Repository: /path/to/repo
-Archive name: Tuesday
+Archive name: docs
 Archive fingerprint: bcd1b53f9b4991b7afc2b339f851b7ffe3c6d030688936fe4552eccc1877718d
 Time (start): Sat, 2022\-06\-25 20:21:43
 Time (end):   Sat, 2022\-06\-25 20:21:43
@@ -122,20 +122,20 @@ List all archives in the repository:
 .nf
 .ft C
 $ borg \-r /path/to/repo repo\-list
-Monday                               Sat, 2022\-06\-25 20:21:14 [b80e24d2...b179f298]
-Tuesday                              Sat, 2022\-06\-25 20:21:43 [bcd1b53f...1877718d]
+docs                                 Sat, 2022\-06\-25 20:21:14 [b80e24d2...b179f298]
+docs                                 Sat, 2022\-06\-25 20:21:43 [bcd1b53f...1877718d]
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
 .IP 5. 3
-List the contents of the \fIMonday\fP archive:
+List the contents of the first archive:
 .INDENT 3.0
 .INDENT 3.5
 .sp
 .nf
 .ft C
-$ borg \-r /path/to/repo list Monday
+$ borg \-r /path/to/repo list aid:b80e24d2
 drwxr\-xr\-x user   group          0 Mon, 2016\-02\-15 18:22:30 home/user/Documents
 \-rw\-r\-\-r\-\- user   group       7961 Mon, 2016\-02\-15 18:22:30 home/user/Documents/Important.doc
 \&...
@@ -144,34 +144,32 @@ drwxr\-xr\-x user   group          0 Mon, 2016\-02\-15 18:22:30 home/user/Docume
 .UNINDENT
 .UNINDENT
 .IP 6. 3
-Restore the \fIMonday\fP archive by extracting the files relative to the current directory:
+Restore the first archive by extracting the files relative to the current directory:
 .INDENT 3.0
 .INDENT 3.5
 .sp
 .nf
 .ft C
-$ borg \-r /path/to/repo extract Monday
+$ borg \-r /path/to/repo extract aid:b80e24d2
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
 .IP 7. 3
-Delete the \fIMonday\fP archive (please note that this does \fBnot\fP free repo disk space):
+Delete the first archive (please note that this does \fBnot\fP free repo disk space):
 .INDENT 3.0
 .INDENT 3.5
 .sp
 .nf
 .ft C
-$ borg \-r /path/to/repo delete \-a Monday
+$ borg \-r /path/to/repo delete aid:b80e24d2
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
 .sp
-Please note the \fB\-a\fP option here (short for \fB\-\-match\-archives\fP) which enables you
-to give a pattern to delete multiple archives, like \fB\-a \(aqsh:oldcrap\-*\(aq\fP\&.
-You can also combine this with \fB\-\-first\fP, \fB\-\-last\fP and \fB\-\-sort\-by\fP\&.
-Be careful, always first use with \fB\-\-dry\-run\fP and \fB\-\-list\fP!
+Be careful if you use an archive NAME (and not an archive ID), that might match multiple archives!
+Always first use with \fB\-\-dry\-run\fP and \fB\-\-list\fP!
 .IP 8. 3
 Recover disk space by compacting the segment files in the repo:
 .INDENT 3.0
@@ -179,7 +177,7 @@ Recover disk space by compacting the segment files in the repo:
 .sp
 .nf
 .ft C
-$ borg \-r /path/to/repo compact
+$ borg \-r /path/to/repo compact \-v
 .ft P
 .fi
 .UNINDENT
@@ -232,7 +230,7 @@ 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\(ga
+\fBssh://user@host:port/path/to/repo\fP \- absolute path
 .sp
 \fBssh://user@host:port/./path/to/repo\fP \- path relative to current directory
 .sp
@@ -240,7 +238,13 @@ Note: you may also prepend a \fBfile://\fP to a filesystem path to get URL style
 .sp
 \fBRemote repositories\fP accessed via sftp:
 .sp
-\fBsftp://user@host:port/path/to/repo\fP \- absolute path\(ga
+\fBsftp://user@host:port/path/to/repo\fP \- absolute path
+.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
 .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:
@@ -462,8 +466,7 @@ cache entries for backup sources other than the current sources.
 .TP
 .B BORG_FILES_CACHE_TTL
 When set to a numeric value, this determines the maximum \(dqtime to live\(dq for the files cache
-entries (default: 20). The files cache is used to determine quickly whether a file is unchanged.
-The FAQ explains this more detailed in: \fIalways_chunking\fP
+entries (default: 2). The files cache is used to determine quickly whether a file is unchanged.
 .TP
 .B BORG_USE_CHUNKS_ARCHIVE
 When set to no (default: yes), the \fBchunks.archive.d\fP folder will not be used. This reduces
@@ -491,20 +494,6 @@ given order, e.g.:
 \fBnone\fP: do not try to load an implementation
 .UNINDENT
 .TP
-.B BORG_CACHE_IMPL
-Choose the implementation for the clientside cache, choose one of:
-.INDENT 7.0
-.IP \(bu 2
-\fBadhoc\fP: builds a non\-persistent chunks cache by querying the repo. Chunks cache contents
-are somewhat sloppy for already existing chunks, concerning their refcount (\(dqinfinite\(dq) and
-size (0). No files cache (slow, will chunk all input files). DEPRECATED.
-.IP \(bu 2
-\fBadhocwithfiles\fP: Like \fBadhoc\fP, but with a persistent files cache. Default implementation.
-.IP \(bu 2
-\fBcli\fP: Determine the cache implementation from cli options. Without special options, will
-usually end up with the \fBlocal\fP implementation.
-.UNINDENT
-.TP
 .B BORG_SELFTEST
 This can be used to influence borg\(aqs builtin self\-tests. The default is to execute the tests
 at the beginning of each borg command invocation.
@@ -724,7 +713,7 @@ and re\-write segment files to free space.
 .IP \(bu 2
 In future, easier to adapt to other kinds of storage:
 borgstore\(aqs backends are quite simple to implement.
-A \fBsftp:\fP backend already exists, cloud storage might be easy to add.
+\fBsftp:\fP and \fBrclone:\fP backends already exists, others might be easy to add.
 .IP \(bu 2
 Parallel repository access with less locking is easier to implement.
 .UNINDENT

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

docs/usage/create.rst.inc

@@ -31,8 +31,6 @@ borg create
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--json``                                        | output stats as JSON. Implies ``--stats``.                                                                                                                                                        |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--prefer-adhoc-cache``                          | experimental: prefer AdHocCache (w/o files cache) over AdHocWithFilesCache (with files cache).                                                                                                    |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--stdin-name NAME``                             | use NAME in archive for stdin data (default: 'stdin')                                                                                                                                             |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--stdin-user USER``                             | set user USER in archive for stdin data (default: do not store user/uid)                                                                                                                          |
@@ -128,7 +126,6 @@ borg create
         --list          output verbose list of items (files, dirs, ...)
         --filter STATUSCHARS    only display items with the given status characters (see description)
         --json          output stats as JSON. Implies ``--stats``.
-        --prefer-adhoc-cache    experimental: prefer AdHocCache (w/o files cache) over AdHocWithFilesCache (with files cache).
         --stdin-name NAME    use NAME in archive for stdin data (default: 'stdin')
         --stdin-user USER    set user USER in archive for stdin data (default: do not store user/uid)
         --stdin-group GROUP    set group GROUP in archive for stdin data (default: do not store group/gid)
@@ -195,7 +192,9 @@ stdin* below for details.
 The archive will consume almost no disk space for files or parts of files that
 have already been stored in other archives.
 
-The archive name needs to be unique.
+The archive name does NOT need to be unique, you can and should use the same
+name for a series of archives. The unique archive identifier is its ID (hash)
+and you can abbreviate the ID as long as it is unique.
 
 In the archive name, you may use the following placeholders:
 {now}, {utcnow}, {fqdn}, {hostname}, {user} and some others.

docs/usage/delete.rst.inc

@@ -6,12 +6,16 @@ borg delete
 -----------
 .. code-block:: none
 
-    borg [common options] delete [options]
+    borg [common options] delete [options] [NAME]
 
 .. only:: html
 
     .. class:: borg-options-table
 
+    +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    | **positional arguments**                                                                                                                                                                                                               |
+    +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``NAME``                                     | specify the archive name                                                                                  |
     +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
     | **optional arguments**                                                                                                                                                                                                                 |
     +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
@@ -52,6 +56,8 @@ borg delete
 
 .. only:: latex
 
+    NAME
+        specify the archive name
 
 
     optional arguments

docs/usage/help.rst.inc

@@ -342,8 +342,9 @@ If literal curly braces need to be used, double them for escaping::
 
 Examples::
 
-    borg create '{hostname}-{user}' ...
-    borg prune '{hostname}-{user}' ...
+    borg create /path/to/repo::{hostname}-{user}-{utcnow} ...
+    borg create /path/to/repo::{hostname}-{now:%Y-%m-%d_%H:%M:%S%z} ...
+    borg prune -a 'sh:{hostname}-*' ...
 
 .. note::
     systemd uses a difficult, non-standard syntax for command lines in unit files (refer to

docs/usage/info.rst.inc

@@ -6,12 +6,16 @@ borg info
 ---------
 .. code-block:: none
 
-    borg [common options] info [options]
+    borg [common options] info [options] [NAME]
 
 .. only:: html
 
     .. class:: borg-options-table
 
+    +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    | **positional arguments**                                                                                                                                                                                                               |
+    +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``NAME``                                     | specify the archive name                                                                                  |
     +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
     | **optional arguments**                                                                                                                                                                                                                 |
     +-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
@@ -50,6 +54,8 @@ borg info
 
 .. only:: latex
 
+    NAME
+        specify the archive name
 
 
     optional arguments

docs/usage/prune.rst.inc

@@ -6,12 +6,16 @@ borg prune
 ----------
 .. code-block:: none
 
-    borg [common options] prune [options]
+    borg [common options] prune [options] [NAME]
 
 .. only:: html
 
     .. class:: borg-options-table
 
+    +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
+    | **positional arguments**                                                                                                                                                                                                       |
+    +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
+    |                                                                             | ``NAME``                                     | specify the archive name                                                                          |
     +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
     | **optional arguments**                                                                                                                                                                                                         |
     +-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
@@ -70,6 +74,8 @@ borg prune
 
 .. only:: latex
 
+    NAME
+        specify the archive name
 
 
     optional arguments
@@ -113,17 +119,18 @@ certain number of historic backups. This retention policy is commonly referred t
 `GFS <https://en.wikipedia.org/wiki/Backup_rotation_scheme#Grandfather-father-son>`_
 (Grandfather-father-son) backup rotation scheme.
 
-If you use --match-archives (-a), then only archives that match the pattern are
-considered for deletion and only those archives count towards the totals
-specified by the rules.
+The recommended way to use prune is to give the archive series name to it via the
+NAME argument (assuming you have the same name for all archives in a series).
+Alternatively, you can also use --match-archives (-a), then only archives that
+match the pattern are considered for deletion and only those archives count
+towards the totals specified by the rules.
 Otherwise, *all* archives in the repository are candidates for deletion!
 There is no automatic distinction between archives representing different
 contents. These need to be distinguished by specifying matching globs.
 
-If you have multiple sequences of archives with different data sets (e.g.
+If you have multiple series of archives with different data sets (e.g.
 from different machines) in one shared repository, use one prune call per
-data set that matches only the respective archives using the --match-archives
-(-a) option.
+series.
 
 The ``--keep-within`` option takes an argument of the form "<int><char>",
 where char is "H", "d", "w", "m", "y". For example, ``--keep-within 2d`` means

docs/usage/recreate.rst.inc

@@ -65,7 +65,7 @@ borg recreate
     +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``--newer TIMESPAN``                              | consider archives newer than (now - TIMESPAN), e.g. 7d or 12m.                                                                                                                                    |
     +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--target TARGET``                               | create a new archive with the name ARCHIVE, do not replace existing archive (only applies for a single archive)                                                                                   |
+    |                                                                             | ``--target TARGET``                               | create a new archive with the name ARCHIVE, do not replace existing archive                                                                                                                       |
     +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``--comment COMMENT``                             | add a comment text to the archive                                                                                                                                                                 |
     +-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -119,7 +119,7 @@ borg recreate
         --newest TIMESPAN                        consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m.
         --older TIMESPAN                         consider archives older than (now - TIMESPAN), e.g. 7d or 12m.
         --newer TIMESPAN                         consider archives newer than (now - TIMESPAN), e.g. 7d or 12m.
-        --target TARGET                          create a new archive with the name ARCHIVE, do not replace existing archive (only applies for a single archive)
+        --target TARGET                          create a new archive with the name ARCHIVE, do not replace existing archive
         --comment COMMENT                        add a comment text to the archive
         --timestamp TIMESTAMP                    manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory.
         -C COMPRESSION, --compression COMPRESSION    select compression algorithm, see the output of the "borg help compression" command for details.