Merge pull request #2867 from ThomasWaldmann/rel110rc1

WIP: release 1.1.0rc1

docs/changes.rst

@@ -131,7 +131,7 @@ The best check that everything is ok is to run a dry-run extraction::
 Changelog
 =========
 
-Version 1.1.0rc1 (unreleased)
+Version 1.1.0rc1 (2017-07-24)
 -----------------------------
 
 Compatibility notes:

docs/usage/break-lock.rst.inc

@@ -6,7 +6,7 @@ borg break-lock
 ---------------
 .. code-block:: none
 
-    borg [common options] break-lock [options] REPOSITORY
+    borg [common options] break-lock [options] [REPOSITORY]
 
 .. only:: html
 

docs/usage/change-passphrase.rst.inc

@@ -6,7 +6,7 @@ borg change-passphrase
 ----------------------
 .. code-block:: none
 
-    borg [common options] change-passphrase [options] REPOSITORY
+    borg [common options] change-passphrase [options] [REPOSITORY]
 
 .. only:: html
 

docs/usage/check.rst.inc

@@ -6,45 +6,45 @@ borg check
 ----------
 .. code-block:: none
 
-    borg [common options] check [options] REPOSITORY_OR_ARCHIVE
+    borg [common options] check [options] [REPOSITORY_OR_ARCHIVE]
 
 .. only:: html
 
     .. 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                                                                                                                      |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                                                                                               |
-    |                                                                                                                                                                                                                                              |
-    | :ref:`common_options`                                                                                                                                                                                                                        |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **filters**                                                                                                                                                                                                                                  |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-P``, ``--prefix``        | only consider archive names starting with this prefix.                                                                                                 |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-a``, ``--glob-archives`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive. |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--sort-by``               | 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                                                                                                          |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **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                                                                                                                      |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | .. 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                                                                                              |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -71,12 +71,12 @@ borg check
     :ref:`common_options`
         |
 
-    filters
-        -P, --prefix            only consider archive names starting with this prefix.
-        -a, --glob-archives     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
-        --sort-by               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
+    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.
+        --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
 
 
 Description

docs/usage/common-options.rst.inc

@@ -7,12 +7,12 @@
 --debug-topic TOPIC    enable TOPIC debugging (can be specified multiple times). The logger path is borg.debug.<TOPIC> if TOPIC is not fully qualified.
 -p, --progress     show progress information
 --log-json         Output one JSON object per log line instead of formatted text.
---lock-wait N      wait for the lock, but max. N seconds (default: 1).
+--lock-wait SECONDS    wait at most SECONDS for acquiring a repository/cache lock (default: 1).
 --show-version     show/log the borg version
 --show-rc          show/log the return code (rc)
 --no-files-cache    do not load/update the file metadata cache used to detect unchanged files
 --umask M          set umask to M (local and remote, default: 0077)
 --remote-path PATH    use PATH as borg executable on the remote (default: "borg")
---remote-ratelimit rate    set remote network upload rate limit in kiByte/s (default: 0=unlimited)
+--remote-ratelimit RATE    set remote network upload rate limit in kiByte/s (default: 0=unlimited)
 --consider-part-files    treat part files like normal files (e.g. to list/extract them)
 --debug-profile FILE    Write execution profile in Borg format into FILE. For local use a Python-compatible file can be generated by suffixing FILE with ".pyprof".

docs/usage/create.rst.inc

@@ -6,7 +6,7 @@ borg create
 -----------
 .. code-block:: none
 
-    borg [common options] create [options] ARCHIVE PATH
+    borg [common options] create [options] ARCHIVE [PATH...]
 
 .. only:: html
 
@@ -27,7 +27,7 @@ borg create
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--list``                                        | output verbose list of items (files, dirs, ...)                                                                                                   |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--filter STATUSCHARS``                          | only display items with the given status characters                                                                                               |
+    |                                                       | ``--filter STATUSCHARS``                          | only display items with the given status characters (see description)                                                                             |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--json``                                        | output stats as JSON. Implies ``--stats``.                                                                                                        |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -43,16 +43,16 @@ borg create
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--exclude-from EXCLUDEFILE``                    | read exclude patterns from EXCLUDEFILE, one per line                                                                                              |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--pattern PATTERN``                             | experimental: include/exclude paths matching PATTERN                                                                                              |
+    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--patterns-from PATTERNFILE``                   | experimental: read include/exclude patterns from PATTERNFILE, one per line                                                                        |
+    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--exclude-caches``                              | exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)                                              |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--exclude-if-present NAME``                     | exclude directories that are tagged by containing a filesystem object with the given NAME                                                         |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--keep-exclude-tags``, ``--keep-tag-files``     | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive                         |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--pattern PATTERN``                             | experimental: include/exclude paths matching PATTERN                                                                                              |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--patterns-from PATTERNFILE``                   | experimental: read include/exclude patterns from PATTERNFILE, one per line                                                                        |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     | **Filesystem options**                                                                                                                                                                                                                                        |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``-x``, ``--one-file-system``                     | stay in the same file system and do not store mount points of other file systems                                                                  |
@@ -71,7 +71,7 @@ borg create
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--comment COMMENT``                             | add a comment text to the archive                                                                                                                 |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--timestamp TIMESTAMP``                         | manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). alternatively, give a reference file/directory.                |
+    |                                                       | ``--timestamp TIMESTAMP``                         | manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). Alternatively, give a reference file/directory.                |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800)                                                                                            |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -100,7 +100,7 @@ borg create
         -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, ...)
-        --filter STATUSCHARS    only display items with the given status characters
+        --filter STATUSCHARS    only display items with the given status characters (see description)
         --json          output stats as JSON. Implies ``--stats``.
         --no-cache-sync    experimental: do not synchronize the cache. Implies ``--no-files-cache``.
 
@@ -111,11 +111,11 @@ borg create
     Exclusion options
         -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
+        --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
+        --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
         --exclude-caches                  exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)
         --exclude-if-present NAME         exclude directories that are tagged by containing a filesystem object with the given NAME
         --keep-exclude-tags, --keep-tag-files    if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive
-        --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
-        --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
 
 
     Filesystem options
@@ -129,7 +129,7 @@ borg create
 
     Archive options
         --comment COMMENT                             add a comment text to the archive
-        --timestamp TIMESTAMP                         manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). alternatively, give a reference file/directory.
+        --timestamp TIMESTAMP                         manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). Alternatively, give a reference file/directory.
         -c SECONDS, --checkpoint-interval SECONDS     write checkpoint every SECONDS seconds (Default: 1800)
         --chunker-params PARAMS                       specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: 19,23,21,4095
         -C COMPRESSION, --compression COMPRESSION     select compression algorithm, see the output of the "borg help compression" command for details.
@@ -156,10 +156,14 @@ checkpoints and treated in special ways.
 In the archive name, you may use the following placeholders:
 {now}, {utcnow}, {fqdn}, {hostname}, {user} and some others.
 
-To speed up pulling backups over sshfs and similar network file systems which do
-not provide correct inode information the ``--ignore-inode`` flag can be used. This
-potentially decreases reliability of change detection, while avoiding always reading
-all files on these file systems.
+Backup speed is increased by not reprocessing files that are already part of
+existing archives and weren't modified. Normally, detecting file modifications
+will take inode information into consideration. This is problematic for files
+located on sshfs and similar network file systems which do not provide stable
+inode numbers, such files will always be considered modified. The
+``--ignore-inode`` flag can be used to prevent this and improve performance.
+This flag will reduce reliability of change detection however, with files
+considered unmodified as long as their size and modification time are unchanged.
 
 The mount points of filesystems or filesystem snapshots should be the same for every
 creation of a new archive to ensure fast operation. This is because the file cache that

docs/usage/delete.rst.inc

@@ -6,43 +6,43 @@ borg delete
 -----------
 .. code-block:: none
 
-    borg [common options] delete [options] TARGET
+    borg [common options] delete [options] [TARGET]
 
 .. only:: html
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                                                     |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``TARGET``                  | archive or repository to delete                                                                                                                        |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                       |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-s``, ``--stats``         | print statistics for the deleted archive                                                                                                               |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-c``, ``--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.                                                       |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--save-space``            | work slower, but using less space                                                                                                                      |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                                                                                               |
-    |                                                                                                                                                                                                                                              |
-    | :ref:`common_options`                                                                                                                                                                                                                        |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **filters**                                                                                                                                                                                                                                  |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-P``, ``--prefix``        | only consider archive names starting with this prefix.                                                                                                 |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-a``, ``--glob-archives`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive. |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--sort-by``               | 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**                                                                                                                                                                                                                                                     |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``TARGET``                            | archive or repository to delete                                                                                                                        |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **optional arguments**                                                                                                                                                                                                                                                       |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-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.                                                       |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--save-space``                      | work slower, but using less space                                                                                                                      |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | .. 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                                                                                              |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -60,7 +60,7 @@ borg delete
 
     optional arguments
         -s, --stats     print statistics for the deleted archive
-        -c, --cache-only    delete only the local cache for the given repository
+        --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.
         --save-space    work slower, but using less space
 
@@ -68,12 +68,12 @@ borg delete
     :ref:`common_options`
         |
 
-    filters
-        -P, --prefix            only consider archive names starting with this prefix.
-        -a, --glob-archives     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
-        --sort-by               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
+    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.
+        --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
 
 
 Description

docs/usage/diff.rst.inc

@@ -6,7 +6,7 @@ borg diff
 ---------
 .. code-block:: none
 
-    borg [common options] diff [options] REPO_ARCHIVE1 ARCHIVE2 PATH
+    borg [common options] diff [options] REPO_ARCHIVE1 ARCHIVE2 [PATH...]
 
 .. only:: html
 
@@ -39,16 +39,16 @@ borg diff
     +-------------------------------------------------------+-----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--exclude-from EXCLUDEFILE``                | read exclude patterns from EXCLUDEFILE, one per line                                                                      |
     +-------------------------------------------------------+-----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--pattern PATTERN``                         | experimental: include/exclude paths matching PATTERN                                                                      |
+    +-------------------------------------------------------+-----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--patterns-from PATTERNFILE``               | experimental: read include/exclude patterns from PATTERNFILE, one per line                                                |
+    +-------------------------------------------------------+-----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--exclude-caches``                          | exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)                      |
     +-------------------------------------------------------+-----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--exclude-if-present NAME``                 | exclude directories that are tagged by containing a filesystem object with the given NAME                                 |
     +-------------------------------------------------------+-----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--keep-exclude-tags``, ``--keep-tag-files`` | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive |
     +-------------------------------------------------------+-----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--pattern PATTERN``                         | experimental: include/exclude paths matching PATTERN                                                                      |
-    +-------------------------------------------------------+-----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--patterns-from PATTERNFILE``               | experimental: read include/exclude patterns from PATTERNFILE, one per line                                                |
-    +-------------------------------------------------------+-----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -80,11 +80,11 @@ borg diff
     Exclusion options
         -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
+        --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
+        --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
         --exclude-caches                  exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)
         --exclude-if-present NAME         exclude directories that are tagged by containing a filesystem object with the given NAME
         --keep-exclude-tags, --keep-tag-files    if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive
-        --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
-        --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
 
 
 Description

docs/usage/export-tar.rst.inc

@@ -6,41 +6,43 @@ borg export-tar
 ---------------
 .. code-block:: none
 
-    borg [common options] export-tar [options] ARCHIVE FILE PATH
+    borg [common options] export-tar [options] ARCHIVE FILE [PATH...]
 
 .. only:: html
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                      |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``ARCHIVE``                           | archive to export                                                                                             |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``FILE``                              | output tar file. "-" to write to stdout instead.                                                              |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``PATH``                              | paths to extract; patterns are supported                                                                      |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                        |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--tar-filter``                      | filter program to pipe data through                                                                           |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--list``                            | output verbose list of items (files, dirs, ...)                                                               |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN                                                                                |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--exclude-from EXCLUDEFILE``        | read exclude patterns from EXCLUDEFILE, one per line                                                          |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--pattern PATTERN``                 | experimental: include/exclude paths matching PATTERN                                                          |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--patterns-from PATTERNFILE``       | experimental: read include/exclude patterns from PATTERNFILE, one per line                                    |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--strip-components NUMBER``         | Remove the specified number of leading path elements. Pathnames with fewer elements will be silently skipped. |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                                                                |
-    |                                                                                                                                                                                                               |
-    | :ref:`common_options`                                                                                                                                                                                         |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    | **positional arguments**                                                                                                                                                                                  |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                       | ``ARCHIVE``                           | archive to export                                                                                         |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                       | ``FILE``                              | output tar file. "-" to write to stdout instead.                                                          |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                       | ``PATH``                              | paths to extract; patterns are supported                                                                  |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    | **optional arguments**                                                                                                                                                                                    |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--tar-filter``                      | filter program to pipe data through                                                                       |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--list``                            | output verbose list of items (files, dirs, ...)                                                           |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                                                                                                            |
+    |                                                                                                                                                                                                           |
+    | :ref:`common_options`                                                                                                                                                                                     |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    | **Exclusion options**                                                                                                                                                                                     |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                       | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN                                                                            |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--exclude-from EXCLUDEFILE``        | read exclude patterns from EXCLUDEFILE, one per line                                                      |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--pattern PATTERN``                 | experimental: include/exclude paths matching PATTERN                                                      |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--patterns-from PATTERNFILE``       | experimental: read include/exclude patterns from PATTERNFILE, one per line                                |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--strip-components NUMBER``         | Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -61,17 +63,20 @@ borg export-tar
 
 
     optional arguments
-        --tar-filter                      filter program to pipe data through
-        --list                            output verbose list of items (files, dirs, ...)
+        --tar-filter     filter program to pipe data through
+        --list           output verbose list of items (files, dirs, ...)
+
+
+    :ref:`common_options`
+        |
+
+    Exclusion options
         -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
         --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
         --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
-        --strip-components NUMBER         Remove the specified number of leading path elements. Pathnames with fewer elements will be silently skipped.
-
+        --strip-components NUMBER         Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped.
 
-    :ref:`common_options`
-        |
 
 Description
 ~~~~~~~~~~~

docs/usage/extract.rst.inc

@@ -6,45 +6,47 @@ borg extract
 ------------
 .. code-block:: none
 
-    borg [common options] extract [options] ARCHIVE PATH
+    borg [common options] extract [options] ARCHIVE [PATH...]
 
 .. only:: html
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                      |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``ARCHIVE``                           | archive to extract                                                                                            |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``PATH``                              | paths to extract; patterns are supported                                                                      |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                        |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--list``                            | output verbose list of items (files, dirs, ...)                                                               |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-n``, ``--dry-run``                 | do not actually change any files                                                                              |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN                                                                                |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--exclude-from EXCLUDEFILE``        | read exclude patterns from EXCLUDEFILE, one per line                                                          |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--pattern PATTERN``                 | experimental: include/exclude paths matching PATTERN                                                          |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--patterns-from PATTERNFILE``       | experimental: read include/exclude patterns from PATTERNFILE, one per line                                    |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--numeric-owner``                   | only obey numeric user and group identifiers                                                                  |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--strip-components NUMBER``         | Remove the specified number of leading path elements. Pathnames with fewer elements will be silently skipped. |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--stdout``                          | write all extracted data to stdout                                                                            |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--sparse``                          | create holes in output sparse file from all-zero chunks                                                       |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                                                                |
-    |                                                                                                                                                                                                               |
-    | :ref:`common_options`                                                                                                                                                                                         |
-    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    | **positional arguments**                                                                                                                                                                                  |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                       | ``ARCHIVE``                           | archive to extract                                                                                        |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                       | ``PATH``                              | paths to extract; patterns are supported                                                                  |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    | **optional arguments**                                                                                                                                                                                    |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--list``                            | output verbose list of items (files, dirs, ...)                                                           |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                       | ``-n``, ``--dry-run``                 | do not actually change any files                                                                          |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--numeric-owner``                   | only obey numeric user and group identifiers                                                              |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--stdout``                          | write all extracted data to stdout                                                                        |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--sparse``                          | create holes in output sparse file from all-zero chunks                                                   |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                                                                                                            |
+    |                                                                                                                                                                                                           |
+    | :ref:`common_options`                                                                                                                                                                                     |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    | **Exclusion options**                                                                                                                                                                                     |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                       | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN                                                                            |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--exclude-from EXCLUDEFILE``        | read exclude patterns from EXCLUDEFILE, one per line                                                      |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--pattern PATTERN``                 | experimental: include/exclude paths matching PATTERN                                                      |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--patterns-from PATTERNFILE``       | experimental: read include/exclude patterns from PATTERNFILE, one per line                                |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--strip-components NUMBER``         | Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. |
+    +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -65,12 +67,7 @@ borg extract
     optional arguments
         --list            output verbose list of items (files, dirs, ...)
         -n, --dry-run     do not actually change any files
-        -e PATTERN, --exclude PATTERN    exclude paths matching PATTERN
-        --exclude-from EXCLUDEFILE    read exclude patterns from EXCLUDEFILE, one per line
-        --pattern PATTERN    experimental: include/exclude paths matching PATTERN
-        --patterns-from PATTERNFILE    experimental: read include/exclude patterns from PATTERNFILE, one per line
         --numeric-owner    only obey numeric user and group identifiers
-        --strip-components NUMBER    Remove the specified number of leading path elements. Pathnames with fewer elements will be silently skipped.
         --stdout          write all extracted data to stdout
         --sparse          create holes in output sparse file from all-zero chunks
 
@@ -78,6 +75,14 @@ borg extract
     :ref:`common_options`
         |
 
+    Exclusion options
+        -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
+        --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
+        --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
+        --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
+        --strip-components NUMBER         Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped.
+
+
 Description
 ~~~~~~~~~~~
 
@@ -93,4 +98,9 @@ output data: reading metadata and data chunks from the repo, checking the hash/h
 decrypting, decompressing.
 
 ``--progress`` can be slower than no progress display, since it makes one additional
-pass over the archive metadata.
+pass over the archive metadata.
+
+.. note::
+
+    Currently, extract always writes into the current working directory ("."),
+    so make sure you ``cd`` to the right place before calling ``borg extract``.

docs/usage/info.rst.inc

@@ -6,37 +6,37 @@ borg info
 ---------
 .. code-block:: none
 
-    borg [common options] info [options] REPOSITORY_OR_ARCHIVE
+    borg [common options] info [options] [REPOSITORY_OR_ARCHIVE]
 
 .. only:: html
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                                                     |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``REPOSITORY_OR_ARCHIVE``   | archive or repository to display information about                                                                                                     |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                       |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--json``                  | format output as JSON                                                                                                                                  |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                                                                                               |
-    |                                                                                                                                                                                                                                              |
-    | :ref:`common_options`                                                                                                                                                                                                                        |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **filters**                                                                                                                                                                                                                                  |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-P``, ``--prefix``        | only consider archive names starting with this prefix.                                                                                                 |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-a``, ``--glob-archives`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive. |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--sort-by``               | 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``             | archive or repository 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                                                                                              |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -59,12 +59,12 @@ borg info
     :ref:`common_options`
         |
 
-    filters
-        -P, --prefix            only consider archive names starting with this prefix.
-        -a, --glob-archives     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
-        --sort-by               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
+    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.
+        --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
 
 
 Description

docs/usage/init.rst.inc

@@ -6,29 +6,29 @@ borg init
 ---------
 .. code-block:: none
 
-    borg [common options] init [options] REPOSITORY
+    borg [common options] init [options] [REPOSITORY]
 
 .. only:: html
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+--------------------------+-----------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                       |
-    +-------------------------------------------------------+--------------------------+-----------------------------------------------------------------------------+
-    |                                                       | ``REPOSITORY``           | repository to create                                                        |
-    +-------------------------------------------------------+--------------------------+-----------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                         |
-    +-------------------------------------------------------+--------------------------+-----------------------------------------------------------------------------+
-    |                                                       | ``-e``, ``--encryption`` | select encryption key mode **(required)**                                   |
-    +-------------------------------------------------------+--------------------------+-----------------------------------------------------------------------------+
-    |                                                       | ``--append-only``        | create an append-only mode repository                                       |
-    +-------------------------------------------------------+--------------------------+-----------------------------------------------------------------------------+
-    |                                                       | ``--storage-quota``      | Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota. |
-    +-------------------------------------------------------+--------------------------+-----------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                 |
-    |                                                                                                                                                                |
-    | :ref:`common_options`                                                                                                                                          |
-    +-------------------------------------------------------+--------------------------+-----------------------------------------------------------------------------+
+    +-------------------------------------------------------+------------------------------------+-----------------------------------------------------------------------------+
+    | **positional arguments**                                                                                                                                                 |
+    +-------------------------------------------------------+------------------------------------+-----------------------------------------------------------------------------+
+    |                                                       | ``REPOSITORY``                     | repository to create                                                        |
+    +-------------------------------------------------------+------------------------------------+-----------------------------------------------------------------------------+
+    | **optional arguments**                                                                                                                                                   |
+    +-------------------------------------------------------+------------------------------------+-----------------------------------------------------------------------------+
+    |                                                       | ``-e MODE``, ``--encryption MODE`` | select encryption key mode **(required)**                                   |
+    +-------------------------------------------------------+------------------------------------+-----------------------------------------------------------------------------+
+    |                                                       | ``--append-only``                  | create an append-only mode repository                                       |
+    +-------------------------------------------------------+------------------------------------+-----------------------------------------------------------------------------+
+    |                                                       | ``--storage-quota QUOTA``          | Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota. |
+    +-------------------------------------------------------+------------------------------------+-----------------------------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                                                                           |
+    |                                                                                                                                                                          |
+    | :ref:`common_options`                                                                                                                                                    |
+    +-------------------------------------------------------+------------------------------------+-----------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -45,9 +45,9 @@ borg init
 
 
     optional arguments
-        -e, --encryption     select encryption key mode **(required)**
-        --append-only        create an append-only mode repository
-        --storage-quota      Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota.
+        -e MODE, --encryption MODE     select encryption key mode **(required)**
+        --append-only                  create an append-only mode repository
+        --storage-quota QUOTA          Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota.
 
 
     :ref:`common_options`

docs/usage/key_change-passphrase.rst.inc

@@ -6,7 +6,7 @@ borg key change-passphrase
 --------------------------
 .. code-block:: none
 
-    borg [common options] key change-passphrase [options] REPOSITORY
+    borg [common options] key change-passphrase [options] [REPOSITORY]
 
 .. only:: html
 

docs/usage/key_export.rst.inc

@@ -6,7 +6,7 @@ borg key export
 ---------------
 .. code-block:: none
 
-    borg [common options] key export [options] REPOSITORY PATH
+    borg [common options] key export [options] [REPOSITORY] [PATH]
 
 .. only:: html
 

docs/usage/key_import.rst.inc

@@ -6,7 +6,7 @@ borg key import
 ---------------
 .. code-block:: none
 
-    borg [common options] key import [options] REPOSITORY PATH
+    borg [common options] key import [options] [REPOSITORY] [PATH]
 
 .. only:: html
 
@@ -17,7 +17,7 @@ borg key import
     +-------------------------------------------------------+----------------+----------------------------------------------------------+
     |                                                       | ``REPOSITORY`` |                                                          |
     +-------------------------------------------------------+----------------+----------------------------------------------------------+
-    |                                                       | ``PATH``       | path to the backup                                       |
+    |                                                       | ``PATH``       | path to the backup ('-' to read from stdin)              |
     +-------------------------------------------------------+----------------+----------------------------------------------------------+
     | **optional arguments**                                                                                                            |
     +-------------------------------------------------------+----------------+----------------------------------------------------------+
@@ -41,7 +41,7 @@ borg key import
     REPOSITORY
 
     PATH
-        path to the backup
+        path to the backup ('-' to read from stdin)
 
 
     optional arguments

docs/usage/key_migrate-to-repokey.rst.inc

@@ -6,7 +6,7 @@ borg key migrate-to-repokey
 ---------------------------
 .. code-block:: none
 
-    borg [common options] key migrate-to-repokey [options] REPOSITORY
+    borg [common options] key migrate-to-repokey [options] [REPOSITORY]
 
 .. only:: html
 

docs/usage/list.rst.inc

@@ -6,61 +6,61 @@ borg list
 ---------
 .. code-block:: none
 
-    borg [common options] list [options] REPOSITORY_OR_ARCHIVE PATH
+    borg [common options] list [options] [REPOSITORY_OR_ARCHIVE] [PATH...]
 
 .. only:: html
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                                                                                                                                                                                         |
-    +-------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``REPOSITORY_OR_ARCHIVE``                     | repository/archive to list contents of                                                                                                                                                                                                                                   |
-    +-------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``PATH``                                      | paths to list; patterns are supported                                                                                                                                                                                                                                    |
-    +-------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                                                                                                                           |
-    +-------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--short``                                   | only print file/directory names, nothing else                                                                                                                                                                                                                            |
-    +-------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--format``, ``--list-format``               | specify format for file listing (default: "{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NL}")                                                                                                                                                            |
-    +-------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--json``                                    | Only valid for listing repository contents. Format output as JSON. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available. |
-    +-------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--json-lines``                              | Only valid for listing archive contents. Format output as JSON Lines. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available. |
-    +-------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                                                                                                                                   |
-    |                                                                                                                                                                                                                                                                                                                                                                                  |
-    | :ref:`common_options`                                                                                                                                                                                                                                                                                                                                                            |
-    +-------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **filters**                                                                                                                                                                                                                                                                                                                                                                      |
-    +-------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-P``, ``--prefix``                          | only consider archive names starting with this prefix.                                                                                                                                                                                                                   |
-    +-------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-a``, ``--glob-archives``                   | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.                                                                                                                   |
-    +-------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--sort-by``                                 | 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                                                                                                                                                                                                                     |
-    +-------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--exclude-caches``                          | exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)                                                                                                                                                                     |
-    +-------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--exclude-if-present NAME``                 | exclude directories that are tagged by containing a filesystem object with the given NAME                                                                                                                                                                                |
-    +-------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--keep-exclude-tags``, ``--keep-tag-files`` | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive                                                                                                                                                |
-    +-------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--pattern PATTERN``                         | experimental: include/exclude paths matching PATTERN                                                                                                                                                                                                                     |
-    +-------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--patterns-from PATTERNFILE``               | experimental: read include/exclude patterns from PATTERNFILE, one per line                                                                                                                                                                                               |
-    +-------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **positional arguments**                                                                                                                                                                                                                                                                                                                                                                               |
+    +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``REPOSITORY_OR_ARCHIVE``                     | repository/archive to list contents of                                                                                                                                                                                                                                   |
+    +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``PATH``                                      | paths to list; patterns are supported                                                                                                                                                                                                                                    |
+    +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **optional arguments**                                                                                                                                                                                                                                                                                                                                                                                 |
+    +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--short``                                   | only print file/directory names, nothing else                                                                                                                                                                                                                            |
+    +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--format FORMAT``, ``--list-format FORMAT`` | specify format for file listing (default: "{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NL}")                                                                                                                                                            |
+    +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--json``                                    | Only valid for listing repository contents. Format output as JSON. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available. |
+    +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--json-lines``                              | Only valid for listing archive contents. Format output as JSON Lines. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available. |
+    +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | .. 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``                         | experimental: include/exclude paths matching PATTERN                                                                                                                                                                                                                     |
+    +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--patterns-from PATTERNFILE``               | experimental: read include/exclude patterns from PATTERNFILE, one per line                                                                                                                                                                                               |
+    +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--exclude-caches``                          | exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)                                                                                                                                                                     |
+    +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--exclude-if-present NAME``                 | exclude directories that are tagged by containing a filesystem object with the given NAME                                                                                                                                                                                |
+    +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--keep-exclude-tags``, ``--keep-tag-files`` | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive                                                                                                                                                |
+    +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -80,7 +80,7 @@ borg list
 
     optional arguments
         --short     only print file/directory names, nothing else
-        --format, --list-format    specify format for file listing (default: "{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NL}")
+        --format FORMAT, --list-format FORMAT    specify format for file listing (default: "{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NL}")
         --json      Only valid for listing repository contents. Format output as JSON. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available.
         --json-lines    Only valid for listing archive contents. Format output as JSON Lines. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available.
 
@@ -88,22 +88,22 @@ borg list
     :ref:`common_options`
         |
 
-    filters
-        -P, --prefix            only consider archive names starting with this prefix.
-        -a, --glob-archives     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
-        --sort-by               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
+    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.
+        --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                 experimental: include/exclude paths matching PATTERN
+        --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
         --exclude-caches                  exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)
         --exclude-if-present NAME         exclude directories that are tagged by containing a filesystem object with the given NAME
         --keep-exclude-tags, --keep-tag-files    if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive
-        --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
-        --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
 
 
 Description
@@ -127,11 +127,18 @@ The following keys are available for ``--format``:
 
 Keys for listing repository archives:
 
-- archive, name: archive name interpreted as text (might be missing non-text characters, see barchive)
+- name: archive name interpreted as text (might be missing non-text characters, see barchive)
+- archive: archive name interpreted as text (might be missing non-text characters, see barchive)
 - barchive: verbatim archive name, can contain any character except NUL
-- time: time of creation of the archive
+- comment: archive comment interpreted as text (might be missing non-text characters, see bcomment)
+- bcomment: verbatim archive comment, can contain any character except NUL
 - id: internal ID of the archive
 
+- time: time (start) of creation of the archive
+- start: time (start) of creation of the archive
+- end: time (end) of creation of the archive
+
+
 Keys for listing archive files:
 
 - type

docs/usage/mount.rst.inc

@@ -12,35 +12,35 @@ borg mount
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                                                     |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``REPOSITORY_OR_ARCHIVE``   | repository/archive to mount                                                                                                                            |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``MOUNTPOINT``              | where to mount filesystem                                                                                                                              |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                       |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-f``, ``--foreground``    | stay in foreground, do not daemonize                                                                                                                   |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-o``                      | Extra mount options                                                                                                                                    |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                                                                                               |
-    |                                                                                                                                                                                                                                              |
-    | :ref:`common_options`                                                                                                                                                                                                                        |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **filters**                                                                                                                                                                                                                                  |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-P``, ``--prefix``        | only consider archive names starting with this prefix.                                                                                                 |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-a``, ``--glob-archives`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive. |
-    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--sort-by``               | 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/archive to mount                                                                                                                            |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``MOUNTPOINT``                        | where to mount filesystem                                                                                                                              |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **optional arguments**                                                                                                                                                                                                                                                       |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-f``, ``--foreground``              | stay in foreground, do not daemonize                                                                                                                   |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-o``                                | Extra mount options                                                                                                                                    |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | .. 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                                                                                              |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -66,12 +66,12 @@ borg mount
     :ref:`common_options`
         |
 
-    filters
-        -P, --prefix            only consider archive names starting with this prefix.
-        -a, --glob-archives     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
-        --sort-by               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
+    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.
+        --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
 
 
 Description

docs/usage/prune.rst.inc

@@ -6,55 +6,55 @@ borg prune
 ----------
 .. code-block:: none
 
-    borg [common options] prune [options] REPOSITORY
+    borg [common options] prune [options] [REPOSITORY]
 
 .. only:: html
 
     .. 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                                                                                                                    |
-    +-------------------------------------------------------+--------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-s``, ``--stats``                  | print statistics for the deleted archive                                                                                                               |
-    +-------------------------------------------------------+--------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--list``                           | output verbose list of archives it keeps/prunes                                                                                                        |
-    +-------------------------------------------------------+--------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--keep-within WITHIN``             | 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                                                                                                                      |
-    +-------------------------------------------------------+--------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                        |
-    |                                                                                                                                                                                                                                                       |
-    | :ref:`common_options`                                                                                                                                                                                                                                 |
-    +-------------------------------------------------------+--------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **filters**                                                                                                                                                                                                                                           |
-    +-------------------------------------------------------+--------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-P``, ``--prefix``                 | only consider archive names starting with this prefix.                                                                                                 |
-    +-------------------------------------------------------+--------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-a``, ``--glob-archives``          | 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                                                                                                                                    |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **optional arguments**                                                                                                                                                                                                                                                       |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-n``, ``--dry-run``                 | do not change repository                                                                                                                               |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--force``                           | force pruning of corrupted archives                                                                                                                    |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-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                                                                                                                      |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | .. 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. |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -75,7 +75,7 @@ borg prune
         --force               force pruning of corrupted archives
         -s, --stats           print statistics for the deleted archive
         --list                output verbose list of archives it keeps/prunes
-        --keep-within WITHIN    keep all archives within this time interval
+        --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
@@ -89,9 +89,9 @@ borg prune
     :ref:`common_options`
         |
 
-    filters
-        -P, --prefix            only consider archive names starting with this prefix.
-        -a, --glob-archives     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
+    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.
 
 
 Description

docs/usage/recreate.rst.inc

@@ -6,7 +6,7 @@ borg recreate
 -------------
 .. code-block:: none
 
-    borg [common options] recreate [options] REPOSITORY_OR_ARCHIVE PATH
+    borg [common options] recreate [options] [REPOSITORY_OR_ARCHIVE] [PATH...]
 
 .. only:: html
 
@@ -23,7 +23,7 @@ borg recreate
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--list``                                        | output verbose list of items (files, dirs, ...)                                                                                                                                                                                                                     |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--filter STATUSCHARS``                          | only display items with the given status characters                                                                                                                                                                                                                 |
+    |                                                       | ``--filter STATUSCHARS``                          | only display items with the given status characters (listed in borg create --help)                                                                                                                                                                                  |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``-n``, ``--dry-run``                             | do not change anything                                                                                                                                                                                                                                              |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -39,16 +39,16 @@ borg recreate
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--exclude-from EXCLUDEFILE``                    | read exclude patterns from EXCLUDEFILE, one per line                                                                                                                                                                                                                |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--pattern PATTERN``                             | experimental: include/exclude paths matching PATTERN                                                                                                                                                                                                                |
+    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--patterns-from PATTERNFILE``                   | experimental: read include/exclude patterns from PATTERNFILE, one per line                                                                                                                                                                                          |
+    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--exclude-caches``                              | exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)                                                                                                                                                                |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--exclude-if-present NAME``                     | exclude directories that are tagged by containing a filesystem object with the given NAME                                                                                                                                                                           |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--keep-exclude-tags``, ``--keep-tag-files``     | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive                                                                                                                                           |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--pattern PATTERN``                             | experimental: include/exclude paths matching PATTERN                                                                                                                                                                                                                |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--patterns-from PATTERNFILE``                   | experimental: read include/exclude patterns from PATTERNFILE, one per line                                                                                                                                                                                          |
-    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     | **Archive options**                                                                                                                                                                                                                                                                                                                                                             |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--target TARGET``                               | create a new archive with the name ARCHIVE, do not replace existing archive (only applies for a single archive)                                                                                                                                                     |
@@ -84,7 +84,7 @@ borg recreate
 
     optional arguments
         --list          output verbose list of items (files, dirs, ...)
-        --filter STATUSCHARS    only display items with the given status characters
+        --filter STATUSCHARS    only display items with the given status characters (listed in borg create --help)
         -n, --dry-run    do not change anything
         -s, --stats     print statistics at end
 
@@ -95,11 +95,11 @@ borg recreate
     Exclusion options
         -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
+        --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
+        --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
         --exclude-caches                  exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)
         --exclude-if-present NAME         exclude directories that are tagged by containing a filesystem object with the given NAME
         --keep-exclude-tags, --keep-tag-files    if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive
-        --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
-        --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
 
 
     Archive options

docs/usage/serve.rst.inc

@@ -21,7 +21,7 @@ borg serve
     +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--append-only``                 | only allow appending to repository segment files                                                                                                                                                                                                                                                                                                                                                                                                                      |
     +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--storage-quota``               | Override storage quota of the repository (e.g. 5G, 1.5T). When a new repository is initialized, sets the storage quota on the new repository as well. Default: no quota.                                                                                                                                                                                                                                                                                              |
+    |                                                       | ``--storage-quota QUOTA``         | Override storage quota of the repository (e.g. 5G, 1.5T). When a new repository is initialized, sets the storage quota on the new repository as well. Default: no quota.                                                                                                                                                                                                                                                                                              |
     +-------------------------------------------------------+-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
     |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
@@ -43,8 +43,8 @@ borg serve
     optional arguments
         --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
-        --storage-quota     Override storage quota of the repository (e.g. 5G, 1.5T). When a new repository is initialized, sets the storage quota on the new repository as well. Default: no quota.
+        --append-only             only allow appending to repository segment files
+        --storage-quota QUOTA     Override storage quota of the repository (e.g. 5G, 1.5T). When a new repository is initialized, sets the storage quota on the new repository as well. Default: no quota.
 
 
     :ref:`common_options`

docs/usage/upgrade.rst.inc

@@ -6,34 +6,33 @@ borg upgrade
 ------------
 .. code-block:: none
 
-    borg [common options] upgrade [options] REPOSITORY
+    borg [common options] upgrade [options] [REPOSITORY]
 
 .. only:: html
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                      |
-    +-------------------------------------------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``REPOSITORY``        | path to the repository to be upgraded                                                                                         |
-    +-------------------------------------------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                        |
-    +-------------------------------------------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-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                                                                                                                 |
-    +-------------------------------------------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--tam``             | Enable manifest authentication (in key and cache) (Borg 1.0.9 and later)                                                      |
-    +-------------------------------------------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--disable-tam``     | Disable manifest authentication (in key and cache)                                                                            |
-    +-------------------------------------------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                                                                |
-    |                                                                                                                                                                                                               |
-    | :ref:`common_options`                                                                                                                                                                                         |
-    +-------------------------------------------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+-----------------------+------------------------------------------------------------------------------------------------+
+    | **positional arguments**                                                                                                                                                       |
+    +-------------------------------------------------------+-----------------------+------------------------------------------------------------------------------------------------+
+    |                                                       | ``REPOSITORY``        | path to the repository to be upgraded                                                          |
+    +-------------------------------------------------------+-----------------------+------------------------------------------------------------------------------------------------+
+    | **optional arguments**                                                                                                                                                         |
+    +-------------------------------------------------------+-----------------------+------------------------------------------------------------------------------------------------+
+    |                                                       | ``-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                                                                                  |
+    +-------------------------------------------------------+-----------------------+------------------------------------------------------------------------------------------------+
+    |                                                       | ``--tam``             | Enable manifest authentication (in key and cache) (Borg 1.0.9 and later).                      |
+    +-------------------------------------------------------+-----------------------+------------------------------------------------------------------------------------------------+
+    |                                                       | ``--disable-tam``     | Disable manifest authentication (in key and cache).                                            |
+    +-------------------------------------------------------+-----------------------+------------------------------------------------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                                                                                 |
+    |                                                                                                                                                                                |
+    | :ref:`common_options`                                                                                                                                                          |
+    +-------------------------------------------------------+-----------------------+------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -51,11 +50,10 @@ borg upgrade
 
     optional arguments
         -n, --dry-run     do not change repository
-        --inplace         rewrite repository in place, with no chance of going back to older
-                                       versions of the repository.
+        --inplace         rewrite repository in place, with no chance of going back to older versions of the repository.
         --force           Force upgrade
-        --tam             Enable manifest authentication (in key and cache) (Borg 1.0.9 and later)
-        --disable-tam     Disable manifest authentication (in key and cache)
+        --tam             Enable manifest authentication (in key and cache) (Borg 1.0.9 and later).
+        --disable-tam     Disable manifest authentication (in key and cache).
 
 
     :ref:`common_options`
@@ -144,4 +142,4 @@ WARNING: Running the upgrade in place will make the current
 copy unusable with older version, with no way of going back
 to previous versions. This can PERMANENTLY DAMAGE YOUR
 REPOSITORY!  Attic CAN NOT READ BORG REPOSITORIES, as the
-magic strings have changed. You have been warned.
+magic strings have changed. You have been warned.

docs/usage/with-lock.rst.inc

@@ -6,7 +6,7 @@ borg with-lock
 --------------
 .. code-block:: none
 
-    borg [common options] with-lock [options] REPOSITORY COMMAND ARGS
+    borg [common options] with-lock [options] REPOSITORY COMMAND [ARGS...]
 
 .. only:: html
 
@@ -57,6 +57,8 @@ running in the repo), then execute the given command as a subprocess and wait
 for its termination, release the lock and return the user command's return
 code as borg's return code.
 
-Note: if you copy a repository with the lock held, the lock will be present in
-      the copy, obviously. Thus, before using borg on the copy, you need to
-      use "borg break-lock" on it.
+.. note::
+
+    If you copy a repository with the lock held, the lock will be present in
+    the copy, obviously. Thus, before using borg on the copy, you need to
+    use "borg break-lock" on it.