build_usage

docs/usage/check.rst.inc

@@ -12,41 +12,41 @@ borg check
 
     .. class:: borg-options-table
 
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                                                                                     |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``REPOSITORY_OR_ARCHIVE``             | repository or archive to check consistency of                                                                                                          |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                       |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--repository-only``                 | only perform repository checks                                                                                                                         |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--archives-only``                   | only perform archives checks                                                                                                                           |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--verify-data``                     | perform cryptographic archive data integrity verification (conflicts with ``--repository-only``)                                                       |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--repair``                          | attempt to repair any inconsistencies found                                                                                                            |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--save-space``                      | work slower, but using less space                                                                                                                      |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--max-duration SECONDS``            | do only a partial repo check for max. SECONDS seconds (Default: unlimited)                                                                             |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                               |
-    |                                                                                                                                                                                                                                                                              |
-    | :ref:`common_options`                                                                                                                                                                                                                                                        |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                                                                                  |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-P PREFIX``, ``--prefix PREFIX``    | only consider archive names starting with this prefix.                                                                                                 |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive. |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--sort-by KEYS``                    | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp                                                       |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--first N``                         | consider first N archives after other filters were applied                                                                                             |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--last N``                          | consider last N archives after other filters were applied                                                                                              |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    | **positional arguments**                                                                                                                                                                                               |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``REPOSITORY_OR_ARCHIVE``             | repository or archive to check consistency of                                                    |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    | **options**                                                                                                                                                                                                            |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--repository-only``                 | only perform repository checks                                                                   |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--archives-only``                   | only perform archives checks                                                                     |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--verify-data``                     | perform cryptographic archive data integrity verification (conflicts with ``--repository-only``) |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--repair``                          | attempt to repair any inconsistencies found                                                      |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--save-space``                      | work slower, but using less space                                                                |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--max-duration SECONDS``            | do only a partial repo check for max. SECONDS seconds (Default: unlimited)                       |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                                                                                                                         |
+    |                                                                                                                                                                                                                        |
+    | :ref:`common_options`                                                                                                                                                                                                  |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                            |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-P PREFIX``, ``--prefix PREFIX``    | only consider archive names starting with this prefix. (deprecated)                              |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns".        |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--sort-by KEYS``                    | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--first N``                         | consider first N archives after other filters were applied                                       |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--last N``                          | consider last N archives after other filters were applied                                        |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -62,7 +62,7 @@ borg check
         repository or archive to check consistency of
 
 
-    optional arguments
+    options
         --repository-only    only perform repository checks
         --archives-only    only perform archives checks
         --verify-data     perform cryptographic archive data integrity verification (conflicts with ``--repository-only``)
@@ -75,8 +75,8 @@ borg check
         |
 
     Archive filters
-        -P PREFIX, --prefix PREFIX        only consider archive names starting with this prefix.
-        -a GLOB, --glob-archives GLOB     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
+        -P PREFIX, --prefix PREFIX        only consider archive names starting with this prefix. (deprecated)
+        -a GLOB, --glob-archives GLOB     only consider archive names matching the glob. sh: rules apply, see "borg help patterns".
         --sort-by KEYS                    Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
         --first N                         consider first N archives after other filters were applied
         --last N                          consider last N archives after other filters were applied

docs/usage/compact.rst.inc

@@ -17,7 +17,7 @@ borg compact
     +-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
     |                                                       | ``REPOSITORY``          | repository to compact                                          |
     +-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
-    | **optional arguments**                                                                                                                           |
+    | **options**                                                                                                                                      |
     +-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
     |                                                       | ``--cleanup-commits``   | cleanup commit-only 17-byte segment files                      |
     +-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
@@ -42,7 +42,7 @@ borg compact
         repository to compact
 
 
-    optional arguments
+    options
         --cleanup-commits       cleanup commit-only 17-byte segment files
         --threshold PERCENT     set minimum threshold for saved space in PERCENT (Default: 10)
 

docs/usage/config.rst.inc

@@ -21,7 +21,7 @@ borg config
     +-------------------------------------------------------+----------------------+----------------------------------------+
     |                                                       | ``VALUE``            | new value for key                      |
     +-------------------------------------------------------+----------------------+----------------------------------------+
-    | **optional arguments**                                                                                                |
+    | **options**                                                                                                           |
     +-------------------------------------------------------+----------------------+----------------------------------------+
     |                                                       | ``-c``, ``--cache``  | get and set values from the repo cache |
     +-------------------------------------------------------+----------------------+----------------------------------------+
@@ -52,7 +52,7 @@ borg config
         new value for key
 
 
-    optional arguments
+    options
         -c, --cache    get and set values from the repo cache
         -d, --delete    delete the key from the config file
         -l, --list     list the configuration of the repo

docs/usage/create.rst.inc

@@ -19,7 +19,7 @@ borg create
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``PATH``                                          | paths to archive                                                                                                                                     |
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                           |
+    | **options**                                                                                                                                                                                                                                                      |
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``-n``, ``--dry-run``                             | do not create a backup archive                                                                                                                       |
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -37,7 +37,7 @@ borg create
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--stdin-user USER``                             | set user USER in archive for stdin data (default: 'root')                                                                                            |
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--stdin-group GROUP``                           | set group GROUP in archive for stdin data (default: 'root')                                                                                          |
+    |                                                       | ``--stdin-group GROUP``                           | set group GROUP in archive for stdin data (default: 'wheel')                                                                                         |
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--stdin-mode M``                                | set mode to M in archive for stdin data (default: 0660)                                                                                              |
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -130,7 +130,7 @@ borg create
         paths to archive
 
 
-    optional arguments
+    options
         -n, --dry-run    do not create a backup archive
         -s, --stats     print statistics for the created archive
         --list          output verbose list of items (files, dirs, ...)
@@ -139,7 +139,7 @@ borg create
         --no-cache-sync    experimental: do not synchronize the cache. Implies not using the 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: 'root')
-        --stdin-group GROUP    set group GROUP in archive for stdin data (default: 'root')
+        --stdin-group GROUP    set group GROUP in archive for stdin data (default: 'wheel')
         --stdin-mode M    set mode to M in archive for stdin data (default: 0660)
         --content-from-command    interpret PATH as command and store its stdout. See also section Reading from stdin below.
         --paths-from-stdin    read DELIM-separated list of paths to backup from stdin. Will not recurse into directories.

docs/usage/delete.rst.inc

@@ -12,47 +12,47 @@ borg delete
 
     .. class:: borg-options-table
 
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                                                                                                 |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``REPOSITORY_OR_ARCHIVE``                         | repository or archive to delete                                                                                                                        |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``ARCHIVE``                                       | archives to delete                                                                                                                                     |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                                   |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-n``, ``--dry-run``                             | do not change repository                                                                                                                               |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--list``                                        | output verbose list of archives                                                                                                                        |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-s``, ``--stats``                               | print statistics for the deleted archive                                                                                                               |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--cache-only``                                  | delete only the local cache for the given repository                                                                                                   |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--force``                                       | force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work.                                                       |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--keep-security-info``                          | keep the local security info when deleting a repository                                                                                                |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--save-space``                                  | work slower, but using less space                                                                                                                      |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800)                                                                                                 |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                                           |
-    |                                                                                                                                                                                                                                                                                          |
-    | :ref:`common_options`                                                                                                                                                                                                                                                                    |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                                                                                              |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-P PREFIX``, ``--prefix PREFIX``                | only consider archive names starting with this prefix.                                                                                                 |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB``             | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive. |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--sort-by KEYS``                                | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp                                                       |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--first N``                                     | consider first N archives after other filters were applied                                                                                             |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--last N``                                      | consider last N archives after other filters were applied                                                                                              |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    | **positional arguments**                                                                                                                                                                                                           |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``REPOSITORY_OR_ARCHIVE``                         | repository or archive to delete                                                                  |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``ARCHIVE``                                       | archives to delete                                                                               |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    | **options**                                                                                                                                                                                                                        |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-n``, ``--dry-run``                             | do not change repository                                                                         |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--list``                                        | output verbose list of archives                                                                  |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-s``, ``--stats``                               | print statistics for the deleted archive                                                         |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--cache-only``                                  | delete only the local cache for the given repository                                             |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--force``                                       | force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work. |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--keep-security-info``                          | keep the local security info when deleting a repository                                          |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--save-space``                                  | work slower, but using less space                                                                |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800)                                           |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                                                                                                                                     |
+    |                                                                                                                                                                                                                                    |
+    | :ref:`common_options`                                                                                                                                                                                                              |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                                        |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-P PREFIX``, ``--prefix PREFIX``                | only consider archive names starting with this prefix. (deprecated)                              |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB``             | only consider archive names matching the glob. sh: rules apply, see "borg help patterns".        |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--sort-by KEYS``                                | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--first N``                                     | consider first N archives after other filters were applied                                       |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--last N``                                      | consider last N archives after other filters were applied                                        |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -70,7 +70,7 @@ borg delete
         archives to delete
 
 
-    optional arguments
+    options
         -n, --dry-run    do not change repository
         --list          output verbose list of archives
         -s, --stats     print statistics for the deleted archive
@@ -85,8 +85,8 @@ borg delete
         |
 
     Archive filters
-        -P PREFIX, --prefix PREFIX        only consider archive names starting with this prefix.
-        -a GLOB, --glob-archives GLOB     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
+        -P PREFIX, --prefix PREFIX        only consider archive names starting with this prefix. (deprecated)
+        -a GLOB, --glob-archives GLOB     only consider archive names matching the glob. sh: rules apply, see "borg help patterns".
         --sort-by KEYS                    Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
         --first N                         consider first N archives after other filters were applied
         --last N                          consider last N archives after other filters were applied
@@ -112,11 +112,9 @@ deleted - the "Deleted data" deduplicated size there is most interesting as
 that is how much your repository will shrink.
 Please note that the "All archives" stats refer to the state after deletion.
 
-You can delete multiple archives by specifying their common prefix, if they
-have one, using the ``--prefix PREFIX`` option. You can also specify a shell
-pattern to match multiple archives using the ``--glob-archives GLOB`` option
-(for more info on these patterns, see :ref:`borg_patterns`). Note that these
-two options are mutually exclusive.
+You can delete multiple archives by specifying a shell pattern to match
+multiple archives using the ``--glob-archives GLOB`` option (for more info on
+these patterns, see :ref:`borg_patterns`).
 
 To avoid accidentally deleting archives, especially when using glob patterns,
 it might be helpful to use the ``--dry-run`` to test out the command without

docs/usage/diff.rst.inc

@@ -21,7 +21,7 @@ borg diff
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
     |                                                       | ``PATH``                              | paths of items inside the archives to compare; patterns are supported |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                |
+    | **options**                                                                                                                                                           |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
     |                                                       | ``--numeric-owner``                   | deprecated, use ``--numeric-ids`` instead                             |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
@@ -66,7 +66,7 @@ borg diff
         paths of items inside the archives to compare; patterns are supported
 
 
-    optional arguments
+    options
         --numeric-owner    deprecated, use ``--numeric-ids`` instead
         --numeric-ids    only consider numeric user and group identifiers
         --same-chunker-params    Override check of chunker parameters.

docs/usage/export-tar.rst.inc

@@ -21,7 +21,7 @@ borg export-tar
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     |                                                       | ``PATH``                              | paths to extract; patterns are supported                                                                  |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                    |
+    | **options**                                                                                                                                                                                               |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     |                                                       | ``--tar-filter``                      | filter program to pipe data through                                                                       |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
@@ -62,7 +62,7 @@ borg export-tar
         paths to extract; patterns are supported
 
 
-    optional arguments
+    options
         --tar-filter     filter program to pipe data through
         --list           output verbose list of items (files, dirs, ...)
 
@@ -92,7 +92,7 @@ before writing it to FILE:
 - .tar.gz or .tgz: gzip
 - .tar.bz2 or .tbz: bzip2
 - .tar.xz or .txz: xz
-- .tar.zstd: zstd
+- .tar.zstd or .tar.zst: zstd
 - .tar.lz4: lz4
 
 Alternatively, a ``--tar-filter`` program may be explicitly specified. It should

docs/usage/extract.rst.inc

@@ -19,7 +19,7 @@ borg extract
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     |                                                       | ``PATH``                              | paths to extract; patterns are supported                                                                  |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                    |
+    | **options**                                                                                                                                                                                               |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     |                                                       | ``--list``                            | output verbose list of items (files, dirs, ...)                                                           |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
@@ -74,7 +74,7 @@ borg extract
         paths to extract; patterns are supported
 
 
-    optional arguments
+    options
         --list            output verbose list of items (files, dirs, ...)
         -n, --dry-run     do not actually change any files
         --numeric-owner    deprecated, use ``--numeric-ids`` instead

docs/usage/help.rst.inc

@@ -279,7 +279,7 @@ Examples::
 
     borg create /path/to/repo::{hostname}-{user}-{utcnow} ...
     borg create /path/to/repo::{hostname}-{now:%Y-%m-%d_%H:%M:%S} ...
-    borg prune --prefix '{hostname}-' ...
+    borg prune --glob-archives '{hostname}-*' ...
 
 .. note::
     systemd uses a difficult, non-standard syntax for command lines in unit files (refer to

docs/usage/import-tar.rst.inc

@@ -19,7 +19,7 @@ borg import-tar
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``TARFILE``                                       | input tar file. "-" to read from stdin instead.                                                                                       |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                            |
+    | **options**                                                                                                                                                                                                                                       |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--tar-filter``                                  | filter program to pipe data through                                                                                                   |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
@@ -64,7 +64,7 @@ borg import-tar
         input tar file. "-" to read from stdin instead.
 
 
-    optional arguments
+    options
         --tar-filter    filter program to pipe data through
         -s, --stats     print statistics for the created archive
         --list          output verbose list of items (files, dirs, ...)
@@ -96,7 +96,7 @@ based on its file extension and pipe the file through an appropriate filter:
 - .tar.gz or .tgz: gzip -d
 - .tar.bz2 or .tbz: bzip2 -d
 - .tar.xz or .txz: xz -d
-- .tar.zstd: zstd -d
+- .tar.zstd or .tar.zst: zstd -d
 - .tar.lz4: lz4 -d
 
 Alternatively, a --tar-filter program may be explicitly specified. It should

docs/usage/info.rst.inc

@@ -12,31 +12,31 @@ borg info
 
     .. class:: borg-options-table
 
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                                                                                     |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``REPOSITORY_OR_ARCHIVE``             | repository or archive to display information about                                                                                                     |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                       |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--json``                            | format output as JSON                                                                                                                                  |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                               |
-    |                                                                                                                                                                                                                                                                              |
-    | :ref:`common_options`                                                                                                                                                                                                                                                        |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                                                                                  |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-P PREFIX``, ``--prefix PREFIX``    | only consider archive names starting with this prefix.                                                                                                 |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive. |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--sort-by KEYS``                    | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp                                                       |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--first N``                         | consider first N archives after other filters were applied                                                                                             |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--last N``                          | consider last N archives after other filters were applied                                                                                              |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    | **positional arguments**                                                                                                                                                                                               |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``REPOSITORY_OR_ARCHIVE``             | repository or archive to display information about                                               |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    | **options**                                                                                                                                                                                                            |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--json``                            | format output as JSON                                                                            |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                                                                                                                         |
+    |                                                                                                                                                                                                                        |
+    | :ref:`common_options`                                                                                                                                                                                                  |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                            |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-P PREFIX``, ``--prefix PREFIX``    | only consider archive names starting with this prefix. (deprecated)                              |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns".        |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--sort-by KEYS``                    | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--first N``                         | consider first N archives after other filters were applied                                       |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--last N``                          | consider last N archives after other filters were applied                                        |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -52,7 +52,7 @@ borg info
         repository or archive to display information about
 
 
-    optional arguments
+    options
         --json     format output as JSON
 
 
@@ -60,8 +60,8 @@ borg info
         |
 
     Archive filters
-        -P PREFIX, --prefix PREFIX        only consider archive names starting with this prefix.
-        -a GLOB, --glob-archives GLOB     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
+        -P PREFIX, --prefix PREFIX        only consider archive names starting with this prefix. (deprecated)
+        -a GLOB, --glob-archives GLOB     only consider archive names matching the glob. sh: rules apply, see "borg help patterns".
         --sort-by KEYS                    Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
         --first N                         consider first N archives after other filters were applied
         --last N                          consider last N archives after other filters were applied

docs/usage/init.rst.inc

@@ -17,7 +17,7 @@ borg init
     +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``REPOSITORY``                     | repository to create                                                                                                                                                                                                                   |
     +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                                                                              |
+    | **options**                                                                                                                                                                                                                                                                                                                         |
     +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``-e MODE``, ``--encryption MODE`` | select encryption key mode **(required)**                                                                                                                                                                                              |
     +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -46,7 +46,7 @@ borg init
         repository to create
 
 
-    optional arguments
+    options
         -e MODE, --encryption MODE     select encryption key mode **(required)**
         --append-only                  create an append-only mode repository. Note that this only affects the low level structure of the repository, and running `delete` or `prune` will still be allowed. See :ref:`append_only_mode` in Additional Notes for more details.
         --storage-quota QUOTA          Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota.

docs/usage/key_export.rst.inc

@@ -19,7 +19,7 @@ borg key export
     +-------------------------------------------------------+----------------+------------------------------------------------------------------------+
     |                                                       | ``PATH``       | where to store the backup                                              |
     +-------------------------------------------------------+----------------+------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                          |
+    | **options**                                                                                                                                     |
     +-------------------------------------------------------+----------------+------------------------------------------------------------------------+
     |                                                       | ``--paper``    | Create an export suitable for printing and later type-in               |
     +-------------------------------------------------------+----------------+------------------------------------------------------------------------+
@@ -46,7 +46,7 @@ borg key export
         where to store the backup
 
 
-    optional arguments
+    options
         --paper       Create an export suitable for printing and later type-in
         --qr-html     Create an html file suitable for printing and later type-in or qr scan
 

docs/usage/key_import.rst.inc

@@ -19,7 +19,7 @@ borg key import
     +-------------------------------------------------------+----------------+----------------------------------------------------------+
     |                                                       | ``PATH``       | path to the backup ('-' to read from stdin)              |
     +-------------------------------------------------------+----------------+----------------------------------------------------------+
-    | **optional arguments**                                                                                                            |
+    | **options**                                                                                                                       |
     +-------------------------------------------------------+----------------+----------------------------------------------------------+
     |                                                       | ``--paper``    | interactively import from a backup done with ``--paper`` |
     +-------------------------------------------------------+----------------+----------------------------------------------------------+
@@ -44,7 +44,7 @@ borg key import
         path to the backup ('-' to read from stdin)
 
 
-    optional arguments
+    options
         --paper     interactively import from a backup done with ``--paper``
 
 

docs/usage/list.rst.inc

@@ -19,7 +19,7 @@ borg list
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``PATH``                              | paths to list; patterns are supported                                                                                                                                                                                                                                    |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                                                                                                                                         |
+    | **options**                                                                                                                                                                                                                                                                                                                                                                                    |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``--consider-checkpoints``            | Show checkpoint archives in the repository contents list (default: hidden).                                                                                                                                                                                              |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -37,9 +37,9 @@ borg list
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                                                                                                                                                                                                    |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-P PREFIX``, ``--prefix PREFIX``    | only consider archive names starting with this prefix.                                                                                                                                                                                                                   |
+    |                                                                             | ``-P PREFIX``, ``--prefix PREFIX``    | only consider archive names starting with this prefix. (deprecated)                                                                                                                                                                                                      |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.                                                                                                                   |
+    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns".                                                                                                                                                                                |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``--sort-by KEYS``                    | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp                                                                                                                                                                         |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -74,7 +74,7 @@ borg list
         paths to list; patterns are supported
 
 
-    optional arguments
+    options
         --consider-checkpoints    Show checkpoint archives in the repository contents list (default: hidden).
         --short     only print file/directory names, nothing else
         --format FORMAT    specify format for file or archive listing (default for files: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}"; for archives: "{archive:<36} {time} [{id}]{NL}")
@@ -86,8 +86,8 @@ borg list
         |
 
     Archive filters
-        -P PREFIX, --prefix PREFIX        only consider archive names starting with this prefix.
-        -a GLOB, --glob-archives GLOB     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
+        -P PREFIX, --prefix PREFIX        only consider archive names starting with this prefix. (deprecated)
+        -a GLOB, --glob-archives GLOB     only consider archive names matching the glob. sh: rules apply, see "borg help patterns".
         --sort-by KEYS                    Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
         --first N                         consider first N archives after other filters were applied
         --last N                          consider last N archives after other filters were applied

docs/usage/mount.rst.inc

@@ -12,55 +12,55 @@ borg mount
 
     .. class:: borg-options-table
 
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                                                                                     |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``REPOSITORY_OR_ARCHIVE``             | repository or archive to mount                                                                                                                         |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``MOUNTPOINT``                        | where to mount filesystem                                                                                                                              |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``PATH``                              | paths to extract; patterns are supported                                                                                                               |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                       |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--consider-checkpoints``            | Show checkpoint archives in the repository contents list (default: hidden).                                                                            |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-f``, ``--foreground``              | stay in foreground, do not daemonize                                                                                                                   |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-o``                                | Extra mount options                                                                                                                                    |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--numeric-owner``                   | deprecated, use ``--numeric-ids`` instead                                                                                                              |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--numeric-ids``                     | use numeric user and group identifiers from archive(s)                                                                                                 |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                               |
-    |                                                                                                                                                                                                                                                                              |
-    | :ref:`common_options`                                                                                                                                                                                                                                                        |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                                                                                  |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-P PREFIX``, ``--prefix PREFIX``    | only consider archive names starting with this prefix.                                                                                                 |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive. |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--sort-by KEYS``                    | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp                                                       |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--first N``                         | consider first N archives after other filters were applied                                                                                             |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--last N``                          | consider last N archives after other filters were applied                                                                                              |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **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                                                                                           |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--strip-components NUMBER``         | Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped.                                              |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    | **positional arguments**                                                                                                                                                                                                        |
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``REPOSITORY_OR_ARCHIVE``             | repository or archive to mount                                                                            |
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``MOUNTPOINT``                        | where to mount filesystem                                                                                 |
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``PATH``                              | paths to extract; patterns are supported                                                                  |
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    | **options**                                                                                                                                                                                                                     |
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--consider-checkpoints``            | Show checkpoint archives in the repository contents list (default: hidden).                               |
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-f``, ``--foreground``              | stay in foreground, do not daemonize                                                                      |
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-o``                                | Extra mount options                                                                                       |
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--numeric-owner``                   | deprecated, use ``--numeric-ids`` instead                                                                 |
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--numeric-ids``                     | use numeric user and group identifiers from archive(s)                                                    |
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                                                                                                                                  |
+    |                                                                                                                                                                                                                                 |
+    | :ref:`common_options`                                                                                                                                                                                                           |
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                                     |
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-P PREFIX``, ``--prefix PREFIX``    | only consider archive names starting with this prefix. (deprecated)                                       |
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns".                 |
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--sort-by KEYS``                    | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp          |
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--first N``                         | consider first N archives after other filters were applied                                                |
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--last N``                          | consider last N archives after other filters were applied                                                 |
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    | **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                                              |
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--strip-components NUMBER``         | Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. |
+    +-----------------------------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -80,7 +80,7 @@ borg mount
         paths to extract; patterns are supported
 
 
-    optional arguments
+    options
         --consider-checkpoints    Show checkpoint archives in the repository contents list (default: hidden).
         -f, --foreground    stay in foreground, do not daemonize
         -o     Extra mount options
@@ -92,8 +92,8 @@ borg mount
         |
 
     Archive filters
-        -P PREFIX, --prefix PREFIX        only consider archive names starting with this prefix.
-        -a GLOB, --glob-archives GLOB     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
+        -P PREFIX, --prefix PREFIX        only consider archive names starting with this prefix. (deprecated)
+        -a GLOB, --glob-archives GLOB     only consider archive names matching the glob. sh: rules apply, see "borg help patterns".
         --sort-by KEYS                    Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
         --first N                         consider first N archives after other filters were applied
         --last N                          consider last N archives after other filters were applied

docs/usage/prune.rst.inc

@@ -12,51 +12,51 @@ borg prune
 
     .. class:: borg-options-table
 
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                                                                                                 |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``REPOSITORY``                                    | repository to prune                                                                                                                                    |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                                   |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-n``, ``--dry-run``                             | do not change repository                                                                                                                               |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--force``                                       | force pruning of corrupted archives, use ``--force --force`` in case ``--force`` does not work.                                                        |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-s``, ``--stats``                               | print statistics for the deleted archive                                                                                                               |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--list``                                        | output verbose list of archives it keeps/prunes                                                                                                        |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--keep-within INTERVAL``                        | keep all archives within this time interval                                                                                                            |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--keep-last``, ``--keep-secondly``              | number of secondly archives to keep                                                                                                                    |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--keep-minutely``                               | number of minutely archives to keep                                                                                                                    |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-H``, ``--keep-hourly``                         | number of hourly archives to keep                                                                                                                      |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-d``, ``--keep-daily``                          | number of daily archives to keep                                                                                                                       |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-w``, ``--keep-weekly``                         | number of weekly archives to keep                                                                                                                      |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-m``, ``--keep-monthly``                        | number of monthly archives to keep                                                                                                                     |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-y``, ``--keep-yearly``                         | number of yearly archives to keep                                                                                                                      |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--save-space``                                  | work slower, but using less space                                                                                                                      |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800)                                                                                                 |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                                           |
-    |                                                                                                                                                                                                                                                                                          |
-    | :ref:`common_options`                                                                                                                                                                                                                                                                    |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                                                                                              |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-P PREFIX``, ``--prefix PREFIX``                | only consider archive names starting with this prefix.                                                                                                 |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB``             | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive. |
-    +-----------------------------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    | **positional arguments**                                                                                                                                                                                                          |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``REPOSITORY``                                    | repository to prune                                                                             |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    | **options**                                                                                                                                                                                                                       |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-n``, ``--dry-run``                             | do not change repository                                                                        |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--force``                                       | force pruning of corrupted archives, use ``--force --force`` in case ``--force`` does not work. |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-s``, ``--stats``                               | print statistics for the deleted archive                                                        |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--list``                                        | output verbose list of archives it keeps/prunes                                                 |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--keep-within INTERVAL``                        | keep all archives within this time interval                                                     |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--keep-last``, ``--keep-secondly``              | number of secondly archives to keep                                                             |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--keep-minutely``                               | number of minutely archives to keep                                                             |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-H``, ``--keep-hourly``                         | number of hourly archives to keep                                                               |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-d``, ``--keep-daily``                          | number of daily archives to keep                                                                |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-w``, ``--keep-weekly``                         | number of weekly archives to keep                                                               |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-m``, ``--keep-monthly``                        | number of monthly archives to keep                                                              |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-y``, ``--keep-yearly``                         | number of yearly archives to keep                                                               |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--save-space``                                  | work slower, but using less space                                                               |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800)                                          |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                                                                                                                                    |
+    |                                                                                                                                                                                                                                   |
+    | :ref:`common_options`                                                                                                                                                                                                             |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                                       |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-P PREFIX``, ``--prefix PREFIX``                | only consider archive names starting with this prefix. (deprecated)                             |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB``             | only consider archive names matching the glob. sh: rules apply, see "borg help patterns".       |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -72,7 +72,7 @@ borg prune
         repository to prune
 
 
-    optional arguments
+    options
         -n, --dry-run         do not change repository
         --force               force pruning of corrupted archives, use ``--force --force`` in case ``--force`` does not work.
         -s, --stats           print statistics for the deleted archive
@@ -93,8 +93,8 @@ borg prune
         |
 
     Archive filters
-        -P PREFIX, --prefix PREFIX        only consider archive names starting with this prefix.
-        -a GLOB, --glob-archives GLOB     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
+        -P PREFIX, --prefix PREFIX        only consider archive names starting with this prefix. (deprecated)
+        -a GLOB, --glob-archives GLOB     only consider archive names matching the glob. sh: rules apply, see "borg help patterns".
 
 
 Description

docs/usage/recreate.rst.inc

@@ -19,7 +19,7 @@ borg recreate
     +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``PATH``                                          | paths to recreate; patterns are supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
     +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+    | **options**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
     +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--list``                                        | output verbose list of items (files, dirs, ...)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
     +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -82,7 +82,7 @@ borg recreate
         paths to recreate; patterns are supported
 
 
-    optional arguments
+    options
         --list          output verbose list of items (files, dirs, ...)
         --filter STATUSCHARS    only display items with the given status characters (listed in borg create --help)
         -n, --dry-run    do not change anything

docs/usage/serve.rst.inc

@@ -13,7 +13,7 @@ borg serve
     .. class:: borg-options-table
 
     +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+    | **options**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
     +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--restrict-to-path PATH``       | restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub-directories is granted implicitly; PATH doesn't need to directly point to a repository.                                                                                                                                                                                                                                      |
     +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -40,7 +40,7 @@ borg serve
 
 
 
-    optional arguments
+    options
         --restrict-to-path PATH    restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub-directories is granted implicitly; PATH doesn't need to directly point to a repository.
         --restrict-to-repository PATH    restrict repository access. Only the repository located at PATH (no sub-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike ``--restrict-to-path`` sub-directories are not accessible; PATH needs to directly point at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there.
         --append-only             only allow appending to repository segment files. Note that this only affects the low level structure of the repository, and running `delete` or `prune` will still be allowed. See :ref:`append_only_mode` in Additional Notes for more details.

docs/usage/upgrade.rst.inc

@@ -17,7 +17,7 @@ borg upgrade
     +-------------------------------------------------------+-----------------------+------------------------------------------------------------------------------------------------+
     |                                                       | ``REPOSITORY``        | path to the repository to be upgraded                                                          |
     +-------------------------------------------------------+-----------------------+------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                         |
+    | **options**                                                                                                                                                                    |
     +-------------------------------------------------------+-----------------------+------------------------------------------------------------------------------------------------+
     |                                                       | ``-n``, ``--dry-run`` | do not change repository                                                                       |
     +-------------------------------------------------------+-----------------------+------------------------------------------------------------------------------------------------+
@@ -48,7 +48,7 @@ borg upgrade
         path to the repository to be upgraded
 
 
-    optional arguments
+    options
         -n, --dry-run     do not change repository
         --inplace         rewrite repository in place, with no chance of going back to older versions of the repository.
         --force           Force upgrade