Merge pull request #6249 from borgbackup/rel120rc1

release 1.2.0 rc1

.appveyor.yml

@@ -1,8 +1,8 @@
 version: '{build}'
 
-environment:  
+environment:
   matrix:
-    - PYTHON: C:\Python37-x64
+    - PYTHON: C:\Python38-x64
 
 # Disable automatic builds
 build: off

docs/changes.rst

@@ -217,8 +217,8 @@ The best check that everything is ok is to run a dry-run extraction::
 Change Log
 ==========
 
-Version 1.2.0b4 (2022-01-23)
-----------------------------
+Version 1.2.0rc1 (2022-02-05)
+-----------------------------
 
 Please note:
 
@@ -270,6 +270,41 @@ Compatibility notes:
   if you have scripts expecting rc == 2 for a signal exit, you need to update
   them to check for >= 128.
 
+Fixes:
+
+- repo::archive location placeholder expansion fixes, #5826, #5998
+- repository: fix intermediate commits, shall be at end of current segment
+- delete: don't commit if nothing was deleted, avoid cache sync, #6060
+- argument parsing: accept some options only once, #6026
+- disallow overwriting of existing keyfiles on init, #6036
+- if ensure_dir() fails, give more informative error message, #5952
+
+New features:
+
+- delete --force: do not ask when deleting a repo, #5941
+
+Other changes:
+
+- requirements: exclude broken or incompatible-with-pyinstaller setuptools
+- add a requirements.d/development.lock.txt and use it for vagrant
+- tests:
+
+  - added nonce-related tests
+  - refactor: remove assert_true
+  - vagrant: macos box tuning, netbsd box fixes, #5370, #5922
+- docs:
+
+  - update install docs / requirements docs, #6180
+  - borg mount / FUSE "versions" view is not experimental any more
+  - --pattern* is not experimental any more, #6134
+  - impact of deleting path/to/repo/nonce, #5858
+  - key export: add examples, #6204
+  - ~/.config/borg/keys is not used for repokey keys, #6107
+  - excluded parent dir's metadata can't restore
+
+
+Version 1.2.0b4 (2022-01-23)
+----------------------------
 
 Fixes:
 

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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-BENCHMARK-CRUD" 1 "2022-02-05" "" "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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-BENCHMARK" 1 "2022-02-05" "" "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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-BREAK-LOCK" 1 "2022-02-05" "" "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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-CHECK" 1 "2022-02-05" "" "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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-COMMON" 1 "2022-02-05" "" "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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-COMPACT" 1 "2022-02-05" "" "borg backup tool"
 .SH NAME
 borg-compact \- compact segment files in the 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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-COMPRESSION" 1 "2022-02-05" "" "borg backup tool"
 .SH NAME
 borg-compression \- Details regarding compression
 .SH DESCRIPTION

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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-CONFIG" 1 "2022-02-05" "" "borg backup tool"
 .SH NAME
 borg-config \- get, set, and delete values in a repository or cache config file
 .SH SYNOPSIS

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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-CREATE" 1 "2022-02-05" "" "borg backup tool"
 .SH NAME
 borg-create \- Create new archive
 .SH SYNOPSIS
@@ -187,10 +187,10 @@ exclude paths matching PATTERN
 read exclude patterns from EXCLUDEFILE, one per line
 .TP
 .BI \-\-pattern \ PATTERN
-experimental: include/exclude paths matching PATTERN
+include/exclude paths matching PATTERN
 .TP
 .BI \-\-patterns\-from \ PATTERNFILE
-experimental: read include/exclude patterns from PATTERNFILE, one per line
+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)

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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-DELETE" 1 "2022-02-05" "" "borg backup tool"
 .SH NAME
 borg-delete \- Delete an existing repository or 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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-DIFF" 1 "2022-02-05" "" "borg backup tool"
 .SH NAME
 borg-diff \- Diff contents of two archives
 .SH SYNOPSIS
@@ -94,10 +94,10 @@ exclude paths matching PATTERN
 read exclude patterns from EXCLUDEFILE, one per line
 .TP
 .BI \-\-pattern \ PATTERN
-experimental: include/exclude paths matching PATTERN
+include/exclude paths matching PATTERN
 .TP
 .BI \-\-patterns\-from \ PATTERNFILE
-experimental: read include/exclude patterns from PATTERNFILE, one per line
+read include/exclude patterns from PATTERNFILE, one per line
 .UNINDENT
 .SH EXAMPLES
 .INDENT 0.0

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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-EXPORT-TAR" 1 "2022-02-05" "" "borg backup tool"
 .SH NAME
 borg-export-tar \- Export archive contents as a tarball
 .SH SYNOPSIS
@@ -110,10 +110,10 @@ exclude paths matching PATTERN
 read exclude patterns from EXCLUDEFILE, one per line
 .TP
 .BI \-\-pattern \ PATTERN
-experimental: include/exclude paths matching PATTERN
+include/exclude paths matching PATTERN
 .TP
 .BI \-\-patterns\-from \ PATTERNFILE
-experimental: read include/exclude patterns from PATTERNFILE, one per line
+read include/exclude patterns from PATTERNFILE, one per line
 .TP
 .BI \-\-strip\-components \ NUMBER
 Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped.

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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-EXTRACT" 1 "2022-02-05" "" "borg backup tool"
 .SH NAME
 borg-extract \- Extract archive contents
 .SH SYNOPSIS
@@ -54,6 +54,10 @@ pass over the archive metadata.
 .INDENT 3.5
 Currently, extract always writes into the current working directory ("."),
 so make sure you \fBcd\fP to the right place before calling \fBborg extract\fP\&.
+.sp
+When parent directories are not extracted (because of using file/directory selection
+or any other reason), borg can not restore parent directories\(aq metadata, e.g. owner,
+group, permission, etc.
 .UNINDENT
 .UNINDENT
 .SH OPTIONS
@@ -111,10 +115,10 @@ exclude paths matching PATTERN
 read exclude patterns from EXCLUDEFILE, one per line
 .TP
 .BI \-\-pattern \ PATTERN
-experimental: include/exclude paths matching PATTERN
+include/exclude paths matching PATTERN
 .TP
 .BI \-\-patterns\-from \ PATTERNFILE
-experimental: read include/exclude patterns from PATTERNFILE, one per line
+read include/exclude patterns from PATTERNFILE, one per line
 .TP
 .BI \-\-strip\-components \ NUMBER
 Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped.

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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-IMPORT-TAR" 1 "2022-02-05" "" "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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-INFO" 1 "2022-02-05" "" "borg backup tool"
 .SH NAME
 borg-info \- Show archive details such as disk space used
 .SH SYNOPSIS

docs/man/borg-init.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-INIT" 1 "2022-01-23" "" "borg backup tool"
+.TH "BORG-INIT" 1 "2022-02-05" "" "borg backup tool"
 .SH NAME
 borg-init \- Initialize an empty repository
 .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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-KEY-CHANGE-PASSPHRASE" 1 "2022-02-05" "" "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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-KEY-EXPORT" 1 "2022-02-05" "" "borg backup tool"
 .SH NAME
 borg-key-export \- Export the repository key for backup
 .SH SYNOPSIS
@@ -56,6 +56,24 @@ For repositories using the repokey encryption the key is saved in the
 repository in the config file. A backup is thus not strictly needed,
 but guards against the repository becoming inaccessible if the file
 is damaged for some reason.
+.sp
+Examples:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+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
+# Or pass the output file as an argument instead of redirecting stdout:
+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
+.UNINDENT
+.UNINDENT
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.

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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-KEY-IMPORT" 1 "2022-02-05" "" "borg backup tool"
 .SH NAME
 borg-key-import \- Import the repository key from backup
 .SH SYNOPSIS

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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-KEY-MIGRATE-TO-REPOKEY" 1 "2022-02-05" "" "borg backup tool"
 .SH NAME
 borg-key-migrate-to-repokey \- Migrate passphrase -> repokey
 .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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-KEY" 1 "2022-02-05" "" "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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-LIST" 1 "2022-02-05" "" "borg backup tool"
 .SH NAME
 borg-list \- List archive or repository contents
 .SH SYNOPSIS
@@ -96,10 +96,10 @@ exclude paths matching PATTERN
 read exclude patterns from EXCLUDEFILE, one per line
 .TP
 .BI \-\-pattern \ PATTERN
-experimental: include/exclude paths matching PATTERN
+include/exclude paths matching PATTERN
 .TP
 .BI \-\-patterns\-from \ PATTERNFILE
-experimental: read include/exclude patterns from PATTERNFILE, one per line
+read include/exclude patterns from PATTERNFILE, one per line
 .UNINDENT
 .SH EXAMPLES
 .INDENT 0.0

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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-MOUNT" 1 "2022-02-05" "" "borg backup tool"
 .SH NAME
 borg-mount \- Mount archive or an entire repository as a FUSE filesystem
 .SH SYNOPSIS
@@ -153,10 +153,10 @@ exclude paths matching PATTERN
 read exclude patterns from EXCLUDEFILE, one per line
 .TP
 .BI \-\-pattern \ PATTERN
-experimental: include/exclude paths matching PATTERN
+include/exclude paths matching PATTERN
 .TP
 .BI \-\-patterns\-from \ PATTERNFILE
-experimental: read include/exclude patterns from PATTERNFILE, one per line
+read include/exclude patterns from PATTERNFILE, one per line
 .TP
 .BI \-\-strip\-components \ NUMBER
 Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped.

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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-PATTERNS" 1 "2022-02-05" "" "borg backup tool"
 .SH NAME
 borg-patterns \- Details regarding patterns
 .SH DESCRIPTION
@@ -48,10 +48,18 @@ store all files as \fIsome/path/.../file.ext\fP and \fBborg create
 .sp
 File patterns support these styles: fnmatch, shell, regular expressions,
 path prefixes and path full\-matches. By default, fnmatch is used for
-\fB\-\-exclude\fP patterns and shell\-style is used for the experimental
-\fB\-\-pattern\fP option. For commands that support patterns in their
-\fBPATH\fP argument like (\fBborg list\fP), the default pattern is path
-prefix.
+\fB\-\-exclude\fP patterns and shell\-style is used for the \fB\-\-pattern\fP
+.IP "System Message: ERROR/3 (docs/borg-patterns.rst:, line 43)"
+Unexpected indentation.
+.INDENT 0.0
+.INDENT 3.5
+option. For commands that support patterns in their \fBPATH\fP argument
+.UNINDENT
+.UNINDENT
+.IP "System Message: WARNING/2 (docs/borg-patterns.rst:, line 44)"
+Block quote ends without a blank line; unexpected unindent.
+.sp
+like (\fBborg list\fP), the default pattern is path prefix.
 .sp
 Starting with Borg 1.2, for all but regular expression pattern matching
 styles, all paths are treated as relative, meaning that a leading path
@@ -179,77 +187,65 @@ sh:/home/*/.thumbnails
 some file with spaces.txt
 EOF
 $ borg create \-\-exclude\-from exclude.txt backup /
-.ft P
-.fi
-.UNINDENT
-.UNINDENT
+
 A more general and easier to use way to define filename matching patterns exists
-with the experimental \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP options. Using these, you
-may specify the backup roots (starting points) and patterns for inclusion/exclusion.
-A root path starts with the prefix \fIR\fP, followed by a path (a plain path, not a
+with the \(ga\(ga\-\-pattern\(ga\(ga and \(ga\(ga\-\-patterns\-from\(ga\(ga options. Using these, you may
+specify the backup roots (starting points) and patterns for inclusion/exclusion.
+A root path starts with the prefix \(gaR\(ga, followed by a path (a plain path, not a
 file pattern). An include rule starts with the prefix +, an exclude rule starts
 with the prefix \-, an exclude\-norecurse rule starts with !, all followed by a pattern.
-.sp
-\fBNOTE:\fP
-.INDENT 0.0
-.INDENT 3.5
-Via \fB\-\-pattern\fP or \fB\-\-patterns\-from\fP you can define BOTH inclusion and exclusion
-of files using pattern prefixes \fB+\fP and \fB\-\fP\&. With \fB\-\-exclude\fP and
-\fB\-\-exclude\-from\fP ONLY excludes are defined.
-.UNINDENT
-.UNINDENT
-.sp
+
+\&.. note::
+
+    Via \(ga\(ga\-\-pattern\(ga\(ga or \(ga\(ga\-\-patterns\-from\(ga\(ga you can define BOTH inclusion and exclusion
+    of files using pattern prefixes \(ga\(ga+\(ga\(ga and \(ga\(ga\-\(ga\(ga. With \(ga\(ga\-\-exclude\(ga\(ga and
+    \(ga\(ga\-\-exclude\-from\(ga\(ga ONLY excludes are defined.
+
 Inclusion patterns are useful to include paths that are contained in an excluded
 path. The first matching pattern is used so if an include pattern matches before
 an exclude pattern, the file is backed up. If an exclude\-norecurse pattern matches
 a directory, it won\(aqt recurse into it and won\(aqt discover any potential matches for
 include rules below that directory.
-.sp
-Note that the default pattern style for \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP is
-shell style (\fIsh:\fP), so those patterns behave similar to rsync include/exclude
-patterns. The pattern style can be set via the \fIP\fP prefix.
-.sp
-Patterns (\fB\-\-pattern\fP) and excludes (\fB\-\-exclude\fP) from the command line are
-considered first (in the order of appearance). Then patterns from \fB\-\-patterns\-from\fP
-are added. Exclusion patterns from \fB\-\-exclude\-from\fP files are appended last.
-.sp
-Examples:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-# 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
-.UNINDENT
-.UNINDENT
-.sp
-The patterns.lst file could look like that:
-.INDENT 0.0
-.INDENT 3.5
-.sp
-.nf
-.ft C
-# "sh:" pattern style is the default, so the following line is not needed:
-P sh
-R /
-# can be rebuild
-\- /home/*/.cache
-# they\(aqre downloads for a reason
-\- /home/*/Downloads
-# susan is a nice person
-# include susans home
-+ /home/susan
-# don\(aqt backup the other home directories
-\- /home/*
-# don\(aqt even look in /proc
-! /proc
+\&.. note::
+
+    It\(aqs possible that a sub\-directory/file is matched while parent directories are not.
+    In that case, parent directories are not backed up thus their user, group, permission,
+    etc. can not be restored.
+
+Note that the default pattern style for \(ga\(ga\-\-pattern\(ga\(ga and \(ga\(ga\-\-patterns\-from\(ga\(ga is
+shell style (\(gash:\(ga), so those patterns behave similar to rsync include/exclude
+patterns. The pattern style can be set via the \(gaP\(ga prefix.
+
+Patterns (\(ga\(ga\-\-pattern\(ga\(ga) and excludes (\(ga\(ga\-\-exclude\(ga\(ga) from the command line are
+considered first (in the order of appearance). Then patterns from \(ga\(ga\-\-patterns\-from\(ga\(ga
+are added. Exclusion patterns from \(ga\(ga\-\-exclude\-from\(ga\(ga files are appended last.
+
+Examples::
+
+    # 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
+
+The patterns.lst file could look like that::
+
+    # "sh:" pattern style is the default, so the following line is not needed:
+    P sh
+    R /
+    # can be rebuild
+    \- /home/*/.cache
+    # they\(aqre downloads for a reason
+    \- /home/*/Downloads
+    # susan is a nice person
+    # include susans home
+    + /home/susan
+    # don\(aqt backup the other home directories
+    \- /home/*
+    # don\(aqt even look in /proc
+    ! /proc
 .ft P
 .fi
 .UNINDENT

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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-PLACEHOLDERS" 1 "2022-02-05" "" "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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-PRUNE" 1 "2022-02-05" "" "borg backup tool"
 .SH NAME
 borg-prune \- Prune repository archives according to specified rules
 .SH SYNOPSIS

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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-RECREATE" 1 "2022-02-05" "" "borg backup tool"
 .SH NAME
 borg-recreate \- Re-create archives
 .SH SYNOPSIS
@@ -122,10 +122,10 @@ exclude paths matching PATTERN
 read exclude patterns from EXCLUDEFILE, one per line
 .TP
 .BI \-\-pattern \ PATTERN
-experimental: include/exclude paths matching PATTERN
+include/exclude paths matching PATTERN
 .TP
 .BI \-\-patterns\-from \ PATTERNFILE
-experimental: read include/exclude patterns from PATTERNFILE, one per line
+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)

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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-RENAME" 1 "2022-02-05" "" "borg backup tool"
 .SH NAME
 borg-rename \- Rename an existing archive
 .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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-SERVE" 1 "2022-02-05" "" "borg backup tool"
 .SH NAME
 borg-serve \- Start in server mode. This command is usually not used manually.
 .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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-UMOUNT" 1 "2022-02-05" "" "borg backup tool"
 .SH NAME
 borg-umount \- un-mount the FUSE filesystem
 .SH SYNOPSIS
@@ -69,7 +69,7 @@ bin  boot  etc      home  lib  lib64  lost+found  media  mnt  opt
 root  sbin  srv  tmp  usr  var
 $ borg umount /tmp/mymountpoint
 
-# The experimental "versions view" merges all archives in the repository
+# The "versions view" merges all archives in the repository
 # and provides a versioned view on files.
 $ borg mount \-o versions /path/to/repo /tmp/mymountpoint
 $ ls \-l /tmp/mymountpoint/home/user/doc.txt/

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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-UPGRADE" 1 "2022-02-05" "" "borg backup tool"
 .SH NAME
 borg-upgrade \- upgrade a repository from a previous 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 "2022-01-23" "" "borg backup tool"
+.TH "BORG-WITH-LOCK" 1 "2022-02-05" "" "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 "2022-01-23" "" "borg backup tool"
+.TH "BORG" 1 "2022-02-05" "" "borg backup tool"
 .SH NAME
 borg \- deduplicating and encrypting backup tool
 .SH SYNOPSIS

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 "2022-01-23" "" "borg backup tool"
+.TH "BORGFS" 1 "2022-02-05" "" "borg backup tool"
 .SH NAME
 borgfs \- Mount archive or an entire repository as a FUSE filesystem
 .SH SYNOPSIS
@@ -156,10 +156,10 @@ exclude paths matching PATTERN
 read exclude patterns from EXCLUDEFILE, one per line
 .TP
 .BI \-\-pattern \ PATTERN
-experimental: include/exclude paths matching PATTERN
+include/exclude paths matching PATTERN
 .TP
 .BI \-\-patterns\-from \ PATTERNFILE
-experimental: read include/exclude patterns from PATTERNFILE, one per line
+read include/exclude patterns from PATTERNFILE, one per line
 .TP
 .BI \-\-strip\-components \ NUMBER
 Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped.

docs/usage/create.rst.inc

@@ -59,9 +59,9 @@ borg create
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--exclude-from EXCLUDEFILE``                    | read exclude patterns from EXCLUDEFILE, one per line                                                                                                 |
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--pattern PATTERN``                             | experimental: include/exclude paths matching PATTERN                                                                                                 |
+    |                                                       | ``--pattern PATTERN``                             | include/exclude paths matching PATTERN                                                                                                               |
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--patterns-from PATTERNFILE``                   | experimental: read include/exclude patterns from PATTERNFILE, one per line                                                                           |
+    |                                                       | ``--patterns-from PATTERNFILE``                   | read include/exclude patterns from PATTERNFILE, one per line                                                                                         |
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--exclude-caches``                              | exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html)                                                      |
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -153,8 +153,8 @@ borg create
     Exclusion options
         -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
-        --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
-        --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
+        --pattern PATTERN                 include/exclude paths matching PATTERN
+        --patterns-from PATTERNFILE       read include/exclude patterns from PATTERNFILE, one per line
         --exclude-caches                  exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html)
         --exclude-if-present NAME         exclude directories that are tagged by containing a filesystem object with the given NAME
         --keep-exclude-tags               if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive

docs/usage/diff.rst.inc

@@ -12,41 +12,41 @@ borg diff
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                   |
-    +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+
-    |                                                       | ``REPO::ARCHIVE1``                    | repository location and ARCHIVE1 name                                      |
-    +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+
-    |                                                       | ``ARCHIVE2``                          | ARCHIVE2 name (no repository location allowed)                             |
-    +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+
-    |                                                       | ``PATH``                              | paths of items inside the archives to compare; patterns are supported      |
-    +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                     |
-    +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+
-    |                                                       | ``--numeric-owner``                   | deprecated, use ``--numeric-ids`` instead                                  |
-    +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+
-    |                                                       | ``--numeric-ids``                     | only consider numeric user and group identifiers                           |
-    +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+
-    |                                                       | ``--same-chunker-params``             | Override check of chunker parameters.                                      |
-    +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+
-    |                                                       | ``--sort``                            | Sort the output lines by file path.                                        |
-    +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+
-    |                                                       | ``--json-lines``                      | Format output as JSON Lines.                                               |
-    +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                             |
-    |                                                                                                                                                                            |
-    | :ref:`common_options`                                                                                                                                                      |
-    +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+
-    | **Exclusion options**                                                                                                                                                      |
-    +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+
-    |                                                       | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN                                             |
-    +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+
-    |                                                       | ``--exclude-from EXCLUDEFILE``        | read exclude patterns from EXCLUDEFILE, one per line                       |
-    +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+
-    |                                                       | ``--pattern PATTERN``                 | experimental: include/exclude paths matching PATTERN                       |
-    +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+
-    |                                                       | ``--patterns-from PATTERNFILE``       | experimental: read include/exclude patterns from PATTERNFILE, one per line |
-    +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
+    | **positional arguments**                                                                                                                                              |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
+    |                                                       | ``REPO::ARCHIVE1``                    | repository location and ARCHIVE1 name                                 |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
+    |                                                       | ``ARCHIVE2``                          | ARCHIVE2 name (no repository location allowed)                        |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
+    |                                                       | ``PATH``                              | paths of items inside the archives to compare; patterns are supported |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
+    | **optional arguments**                                                                                                                                                |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
+    |                                                       | ``--numeric-owner``                   | deprecated, use ``--numeric-ids`` instead                             |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
+    |                                                       | ``--numeric-ids``                     | only consider numeric user and group identifiers                      |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
+    |                                                       | ``--same-chunker-params``             | Override check of chunker parameters.                                 |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
+    |                                                       | ``--sort``                            | Sort the output lines by file path.                                   |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
+    |                                                       | ``--json-lines``                      | Format output as JSON Lines.                                          |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                                                                        |
+    |                                                                                                                                                                       |
+    | :ref:`common_options`                                                                                                                                                 |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
+    | **Exclusion options**                                                                                                                                                 |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
+    |                                                       | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN                                        |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
+    |                                                       | ``--exclude-from EXCLUDEFILE``        | read exclude patterns from EXCLUDEFILE, one per line                  |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
+    |                                                       | ``--pattern PATTERN``                 | include/exclude paths matching PATTERN                                |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
+    |                                                       | ``--patterns-from PATTERNFILE``       | read include/exclude patterns from PATTERNFILE, one per line          |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -80,8 +80,8 @@ borg diff
     Exclusion options
         -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
-        --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
-        --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
+        --pattern PATTERN                 include/exclude paths matching PATTERN
+        --patterns-from PATTERNFILE       read include/exclude patterns from PATTERNFILE, one per line
 
 
 Description

docs/usage/export-tar.rst.inc

@@ -37,9 +37,9 @@ borg export-tar
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     |                                                       | ``--exclude-from EXCLUDEFILE``        | read exclude patterns from EXCLUDEFILE, one per line                                                      |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--pattern PATTERN``                 | experimental: include/exclude paths matching PATTERN                                                      |
+    |                                                       | ``--pattern PATTERN``                 | include/exclude paths matching PATTERN                                                                    |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--patterns-from PATTERNFILE``       | experimental: read include/exclude patterns from PATTERNFILE, one per line                                |
+    |                                                       | ``--patterns-from PATTERNFILE``       | read include/exclude patterns from PATTERNFILE, one per line                                              |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     |                                                       | ``--strip-components NUMBER``         | Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
@@ -73,8 +73,8 @@ borg export-tar
     Exclusion options
         -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
-        --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
-        --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
+        --pattern PATTERN                 include/exclude paths matching PATTERN
+        --patterns-from PATTERNFILE       read include/exclude patterns from PATTERNFILE, one per line
         --strip-components NUMBER         Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped.
 
 

docs/usage/extract.rst.inc

@@ -51,9 +51,9 @@ borg extract
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     |                                                       | ``--exclude-from EXCLUDEFILE``        | read exclude patterns from EXCLUDEFILE, one per line                                                      |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--pattern PATTERN``                 | experimental: include/exclude paths matching PATTERN                                                      |
+    |                                                       | ``--pattern PATTERN``                 | include/exclude paths matching PATTERN                                                                    |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--patterns-from PATTERNFILE``       | experimental: read include/exclude patterns from PATTERNFILE, one per line                                |
+    |                                                       | ``--patterns-from PATTERNFILE``       | read include/exclude patterns from PATTERNFILE, one per line                                              |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     |                                                       | ``--strip-components NUMBER``         | Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
@@ -93,8 +93,8 @@ borg extract
     Exclusion options
         -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
-        --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
-        --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
+        --pattern PATTERN                 include/exclude paths matching PATTERN
+        --patterns-from PATTERNFILE       read include/exclude patterns from PATTERNFILE, one per line
         --strip-components NUMBER         Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped.
 
 
@@ -118,4 +118,8 @@ pass over the archive metadata.
 .. note::
 
     Currently, extract always writes into the current working directory ("."),
-    so make sure you ``cd`` to the right place before calling ``borg extract``.
+    so make sure you ``cd`` to the right place before calling ``borg extract``.
+
+    When parent directories are not extracted (because of using file/directory selection
+    or any other reason), borg can not restore parent directories' metadata, e.g. owner,
+    group, permission, etc.

docs/usage/help.rst.inc

@@ -22,10 +22,9 @@ store all files as `some/path/.../file.ext` and ``borg create
 
 File patterns support these styles: fnmatch, shell, regular expressions,
 path prefixes and path full-matches. By default, fnmatch is used for
-``--exclude`` patterns and shell-style is used for the experimental
-``--pattern`` option. For commands that support patterns in their
-``PATH`` argument like (``borg list``), the default pattern is path
-prefix.
+``--exclude`` patterns and shell-style is used for the ``--pattern``
+ option. For commands that support patterns in their ``PATH`` argument
+like (``borg list``), the default pattern is path prefix.
 
 Starting with Borg 1.2, for all but regular expression pattern matching
 styles, all paths are treated as relative, meaning that a leading path
@@ -145,11 +144,9 @@ Examples::
     EOF
     $ borg create --exclude-from exclude.txt backup /
 
-.. container:: experimental
-
     A more general and easier to use way to define filename matching patterns exists
-    with the experimental ``--pattern`` and ``--patterns-from`` options. Using these, you
-    may specify the backup roots (starting points) and patterns for inclusion/exclusion.
+    with the ``--pattern`` and ``--patterns-from`` options. Using these, you may
+    specify the backup roots (starting points) and patterns for inclusion/exclusion.
     A root path starts with the prefix `R`, followed by a path (a plain path, not a
     file pattern). An include rule starts with the prefix +, an exclude rule starts
     with the prefix -, an exclude-norecurse rule starts with !, all followed by a pattern.
@@ -166,6 +163,12 @@ Examples::
     a directory, it won't recurse into it and won't discover any potential matches for
     include rules below that directory.
 
+    .. note::
+
+        It's possible that a sub-directory/file is matched while parent directories are not.
+        In that case, parent directories are not backed up thus their user, group, permission,
+        etc. can not be restored.
+
     Note that the default pattern style for ``--pattern`` and ``--patterns-from`` is
     shell style (`sh:`), so those patterns behave similar to rsync include/exclude
     patterns. The pattern style can be set via the `P` prefix.

docs/usage/key_export.rst.inc

@@ -77,4 +77,15 @@ data backup.
 For repositories using the repokey encryption the key is saved in the
 repository in the config file. A backup is thus not strictly needed,
 but guards against the repository becoming inaccessible if the file
-is damaged for some reason.
+is damaged for some reason.
+
+Examples::
+
+    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
+    # Or pass the output file as an argument instead of redirecting stdout:
+    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
+

docs/usage/list.rst.inc

@@ -53,9 +53,9 @@ borg list
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``--exclude-from EXCLUDEFILE``        | read exclude patterns from EXCLUDEFILE, one per line                                                                                                                                                                                                                     |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--pattern PATTERN``                 | experimental: include/exclude paths matching PATTERN                                                                                                                                                                                                                     |
+    |                                                                             | ``--pattern PATTERN``                 | include/exclude paths matching PATTERN                                                                                                                                                                                                                                   |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--patterns-from PATTERNFILE``       | experimental: read include/exclude patterns from PATTERNFILE, one per line                                                                                                                                                                                               |
+    |                                                                             | ``--patterns-from PATTERNFILE``       | read include/exclude patterns from PATTERNFILE, one per line                                                                                                                                                                                                             |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
@@ -96,8 +96,8 @@ borg list
     Exclusion options
         -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
-        --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
-        --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
+        --pattern PATTERN                 include/exclude paths matching PATTERN
+        --patterns-from PATTERNFILE       read include/exclude patterns from PATTERNFILE, one per line
 
 
 Description

docs/usage/mount.rst.inc

@@ -55,9 +55,9 @@ borg mount
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``--exclude-from EXCLUDEFILE``        | read exclude patterns from EXCLUDEFILE, one per line                                                                                                   |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--pattern PATTERN``                 | experimental: include/exclude paths matching PATTERN                                                                                                   |
+    |                                                                             | ``--pattern PATTERN``                 | include/exclude paths matching PATTERN                                                                                                                 |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--patterns-from PATTERNFILE``       | experimental: read include/exclude patterns from PATTERNFILE, one per line                                                                             |
+    |                                                                             | ``--patterns-from PATTERNFILE``       | read include/exclude patterns from PATTERNFILE, one per line                                                                                           |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``--strip-components NUMBER``         | Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped.                                              |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -102,8 +102,8 @@ borg mount
     Exclusion options
         -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
-        --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
-        --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
+        --pattern PATTERN                 include/exclude paths matching PATTERN
+        --patterns-from PATTERNFILE       read include/exclude patterns from PATTERNFILE, one per line
         --strip-components NUMBER         Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped.
 
 

docs/usage/recreate.rst.inc

@@ -39,9 +39,9 @@ borg recreate
     +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--exclude-from EXCLUDEFILE``                    | read exclude patterns from EXCLUDEFILE, one per line                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
     +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--pattern PATTERN``                             | experimental: include/exclude paths matching PATTERN                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+    |                                                       | ``--pattern PATTERN``                             | include/exclude paths matching PATTERN                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
     +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--patterns-from PATTERNFILE``                   | experimental: read include/exclude patterns from PATTERNFILE, one per line                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+    |                                                       | ``--patterns-from PATTERNFILE``                   | read include/exclude patterns from PATTERNFILE, one per line                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
     +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--exclude-caches``                              | exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html)                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
     +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -95,8 +95,8 @@ borg recreate
     Exclusion options
         -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
-        --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
-        --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
+        --pattern PATTERN                 include/exclude paths matching PATTERN
+        --patterns-from PATTERNFILE       read include/exclude patterns from PATTERNFILE, one per line
         --exclude-caches                  exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html)
         --exclude-if-present NAME         exclude directories that are tagged by containing a filesystem object with the given NAME
         --keep-exclude-tags               if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive

setup_docs.py

@@ -307,6 +307,7 @@ class build_man(Command):
         'key_migrate-to-repokey': 'key',
 
         'export-tar': 'tar',
+        'import-tar': 'tar',
 
         'benchmark_crud': 'benchmark',