build_usage

docs/usage/create.rst.inc

@@ -37,7 +37,7 @@ borg create
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--stdin-user USER``                             | set user USER in archive for stdin data (default: 'root')                                                                                            |
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--stdin-group GROUP``                           | set group GROUP in archive for stdin data (default: 'root')                                                                                          |
+    |                                                       | ``--stdin-group GROUP``                           | set group GROUP in archive for stdin data (default: 'wheel')                                                                                         |
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--stdin-mode M``                                | set mode to M in archive for stdin data (default: 0660)                                                                                              |
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -139,7 +139,7 @@ borg create
         --no-cache-sync    experimental: do not synchronize the cache. Implies not using the files cache.
         --stdin-name NAME    use NAME in archive for stdin data (default: 'stdin')
         --stdin-user USER    set user USER in archive for stdin data (default: 'root')
-        --stdin-group GROUP    set group GROUP in archive for stdin data (default: 'root')
+        --stdin-group GROUP    set group GROUP in archive for stdin data (default: 'wheel')
         --stdin-mode M    set mode to M in archive for stdin data (default: 0660)
         --content-from-command    interpret PATH as command and store its stdout. See also section Reading from stdin below.
         --paths-from-stdin    read DELIM-separated list of paths to backup from stdin. Will not recurse into directories.

docs/usage/export-tar.rst.inc

@@ -89,11 +89,13 @@ By default (``--tar-filter=auto``) Borg will detect whether the FILE should be c
 based on its file extension and pipe the tarball through an appropriate filter
 before writing it to FILE:
 
-- .tar.gz: gzip
-- .tar.bz2: bzip2
-- .tar.xz: xz
+- .tar.gz or .tgz: gzip
+- .tar.bz2 or .tbz: bzip2
+- .tar.xz or .txz: xz
+- .tar.zstd: zstd
+- .tar.lz4: lz4
 
-Alternatively a ``--tar-filter`` program may be explicitly specified. It should
+Alternatively, a ``--tar-filter`` program may be explicitly specified. It should
 read the uncompressed tar stream from stdin and write a compressed/filtered
 tar stream to stdout.
 

docs/usage/extract.rst.inc

@@ -118,8 +118,4 @@ 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``.
-
-    When parent directories are not extracted (because of using file/directory selection
-    or any other reason), borg can not restore parent directories' metadata, e.g. owner,
-    group, permission, etc.
+    so make sure you ``cd`` to the right place before calling ``borg extract``.

docs/usage/help.rst.inc

@@ -23,7 +23,9 @@ store all files as `some/path/.../file.ext` and ``borg create
 File patterns support these styles: fnmatch, shell, regular expressions,
 path prefixes and path full-matches. By default, fnmatch is used for
 ``--exclude`` patterns and shell-style is used for the experimental
-``--pattern`` option.
+``--pattern`` option. For commands that support patterns in their
+``PATH`` argument like (``borg list``), the default pattern is path
+prefix.
 
 Starting with Borg 1.2, for all but regular expression pattern matching
 styles, all paths are treated as relative, meaning that a leading path
@@ -69,15 +71,12 @@ Regular expressions, selector `re:`
     the re module <https://docs.python.org/3/library/re.html>`_.
 
 Path prefix, selector `pp:`
-    This pattern style matches either the whole path or an initial segment
-    of the path up to but not including a path separator. For consistency
-    with the `fn:` and `sh:` patterns, a path separator is added to the
-    end of the path before matching. For example, `pp:root/somedir`
-    matches `root/somedir` and everything therein. A leading path
-    separator is always removed. A trailing slash makes no difference.
+    This pattern style is useful to match whole sub-directories. The pattern
+    `pp:root/somedir` matches `root/somedir` and everything therein. A leading
+    path separator is always removed.
 
 Path full-match, selector `pf:`
-    This pattern style is (only) useful to match full (exact) paths.
+    This pattern style is (only) useful to match full paths.
     This is kind of a pseudo pattern as it can not have any variable or
     unspecified parts - the full path must be given. `pf:root/file.ext` matches
     `root/file.ext` only. A leading path separator is always removed.
@@ -139,8 +138,8 @@ Examples::
     /home/*/junk
     *.tmp
     fm:aa:something/*
-    re:^home/[^/]\.tmp/
-    sh:home/*/.thumbnails
+    re:^/home/[^/]+\.tmp/
+    sh:/home/*/.thumbnails
     # Example with spaces, no need to escape as it is processed by borg
     some file with spaces.txt
     EOF
@@ -167,12 +166,6 @@ Examples::
     a directory, it won't recurse into it and won't discover any potential matches for
     include rules below that directory.
 
-    .. note::
-
-        It's possible that a sub-directory/file is matched while parent directories are not.
-        In that case, parent directories are not backed up thus their user, group, permission,
-        etc. can not be restored.
-
     Note that the default pattern style for ``--pattern`` and ``--patterns-from`` is
     shell style (`sh:`), so those patterns behave similar to rsync include/exclude
     patterns. The pattern style can be set via the `P` prefix.

docs/usage/import-tar.rst.inc

@@ -0,0 +1,117 @@
+.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit!
+
+.. _borg_import-tar:
+
+borg import-tar
+---------------
+.. code-block:: none
+
+    borg [common options] import-tar [options] ARCHIVE TARFILE
+
+.. only:: html
+
+    .. class:: borg-options-table
+
+    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
+    | **positional arguments**                                                                                                                                                                                                                          |
+    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``ARCHIVE``                                       | name of archive to create (must be also a valid directory name)                                                                       |
+    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``TARFILE``                                       | input tar file. "-" to read from stdin instead.                                                                                       |
+    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
+    | **optional arguments**                                                                                                                                                                                                                            |
+    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--tar-filter``                                  | filter program to pipe data through                                                                                                   |
+    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``-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                                                                                   |
+    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--json``                                        | output stats as JSON (implies --stats)                                                                                                |
+    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                    |
+    |                                                                                                                                                                                                                                                   |
+    | :ref:`common_options`                                                                                                                                                                                                                             |
+    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
+    | **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.    |
+    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800)                                                                                |
+    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--chunker-params PARAMS``                       | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095 |
+    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details.                                      |
+    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
+
+    .. raw:: html
+
+        <script type='text/javascript'>
+        $(document).ready(function () {
+            $('.borg-options-table colgroup').remove();
+        })
+        </script>
+
+.. only:: latex
+
+    ARCHIVE
+        name of archive to create (must be also a valid directory name)
+    TARFILE
+        input tar file. "-" to read from stdin instead.
+
+
+    optional arguments
+        --tar-filter    filter program to pipe data through
+        -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
+        --json          output stats as JSON (implies --stats)
+
+
+    :ref:`common_options`
+        |
+
+    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.
+        -c SECONDS, --checkpoint-interval SECONDS     write checkpoint every SECONDS seconds (Default: 1800)
+        --chunker-params PARAMS                       specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095
+        -C COMPRESSION, --compression COMPRESSION     select compression algorithm, see the output of the "borg help compression" command for details.
+
+
+Description
+~~~~~~~~~~~
+
+This command creates a backup archive from a tarball.
+
+When giving '-' as path, Borg will read a tar stream from standard input.
+
+By default (--tar-filter=auto) Borg will detect whether the file is compressed
+based on its file extension and pipe the file through an appropriate filter:
+
+- .tar.gz or .tgz: gzip -d
+- .tar.bz2 or .tbz: bzip2 -d
+- .tar.xz or .txz: xz -d
+- .tar.zstd: zstd -d
+- .tar.lz4: lz4 -d
+
+Alternatively, a --tar-filter program may be explicitly specified. It should
+read compressed data from stdin and output an uncompressed tar stream on
+stdout.
+
+Most documentation of borg create applies. Note that this command does not
+support excluding files.
+
+import-tar is a lossy conversion:
+BSD flags, ACLs, extended attributes (xattrs), atime and ctime are not exported.
+Timestamp resolution is limited to whole seconds, not the nanosecond resolution
+otherwise supported by Borg.
+
+A ``--sparse`` option (as found in borg create) is not supported.
+
+import-tar reads POSIX.1-1988 (ustar), POSIX.1-2001 (pax), GNU tar, UNIX V7 tar
+and SunOS tar with extended attributes.

docs/usage/list.rst.inc

@@ -12,51 +12,51 @@ borg list
 
     .. class:: borg-options-table
 
-    +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                                                                                                                                                                                                               |
-    +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``REPOSITORY_OR_ARCHIVE``                     | repository or archive to list contents of                                                                                                                                                                                                                                |
-    +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``PATH``                                      | paths to list; patterns are supported                                                                                                                                                                                                                                    |
-    +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                                                                                                                                                 |
-    +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--consider-checkpoints``                    | Show checkpoint archives in the repository contents list (default: hidden).                                                                                                                                                                                              |
-    +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--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} {mtime} {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                                                                                                                                                                                               |
-    +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **positional arguments**                                                                                                                                                                                                                                                                                                                                                                       |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``REPOSITORY_OR_ARCHIVE``             | repository or archive to list contents of                                                                                                                                                                                                                                |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``PATH``                              | paths to list; patterns are supported                                                                                                                                                                                                                                    |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **optional arguments**                                                                                                                                                                                                                                                                                                                                                                         |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--consider-checkpoints``            | Show checkpoint archives in the repository contents list (default: hidden).                                                                                                                                                                                              |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--short``                           | only print file/directory names, nothing else                                                                                                                                                                                                                            |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--format FORMAT``                   | specify format for file or archive listing (default for files: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}"; for archives: "{archive:<36} {time} [{id}]{NL}")                                                                                          |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--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                                                                                                                                                                                               |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -77,7 +77,7 @@ borg list
     optional arguments
         --consider-checkpoints    Show checkpoint archives in the repository contents list (default: hidden).
         --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} {mtime} {path}{extra}{NL}")
+        --format FORMAT    specify format for file or archive listing (default for files: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}"; for archives: "{archive:<36} {time} [{id}]{NL}")
         --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.
 
@@ -109,17 +109,46 @@ See the "borg help patterns" command for more help on exclude patterns.
 
 .. man NOTES
 
-The following keys are available for ``--format``:
+The FORMAT specifier syntax
++++++++++++++++++++++++++++
+
+The ``--format`` option uses python's `format string syntax
+<https://docs.python.org/3.8/library/string.html#formatstrings>`_.
+
+Examples:
+::
+
+    $ borg list --format '{archive}{NL}' /path/to/repo
+    ArchiveFoo
+    ArchiveBar
+    ...
+
+    # {VAR:NUMBER} - pad to NUMBER columns.
+    # Strings are left-aligned, numbers are right-aligned.
+    # Note: time columns except ``isomtime``, ``isoctime`` and ``isoatime`` cannot be padded.
+    $ borg list --format '{archive:36} {time} [{id}]{NL}' /path/to/repo
+    ArchiveFoo                           Thu, 2021-12-09 10:22:28 [0b8e9a312bef3f2f6e2d0fc110c196827786c15eba0188738e81697a7fa3b274]
+    $ borg list --format '{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}' /path/to/repo::ArchiveFoo
+    -rw-rw-r-- user   user       1024 Thu, 2021-12-09 10:22:17 file-foo
+    ...
+
+    # {VAR:<NUMBER} - pad to NUMBER columns left-aligned.
+    # {VAR:>NUMBER} - pad to NUMBER columns right-aligned.
+    $ borg list --format '{mode} {user:>6} {group:>6} {size:<8} {mtime} {path}{extra}{NL}' /path/to/repo::ArchiveFoo
+    -rw-rw-r--   user   user 1024     Thu, 2021-12-09 10:22:17 file-foo
+    ...
+
+The following keys are always available:
 
 - NEWLINE: OS dependent line separator
 - NL: alias of NEWLINE
-- NUL: NUL character for creating print0 / xargs -0 like output, see barchive/bpath
+- NUL: NUL character for creating print0 / xargs -0 like output, see barchive and bpath keys below
 - SPACE
 - TAB
 - CR
 - LF
 
-Keys for listing repository archives:
+Keys available only when listing archives in a repository:
 
 - archive: archive name interpreted as text (might be missing non-text characters, see barchive)
 - name: alias of "archive"
@@ -131,12 +160,13 @@ Keys for listing repository archives:
 - start: time (start) of creation of the archive
 - time: alias of "start"
 - end: time (end) of creation of the archive
+- command_line: command line which was used to create the archive
 
 - hostname: hostname of host on which this archive was created
 - username: username of user who created this archive
 
 
-Keys for listing archive files:
+Keys available only when listing files in an archive:
 
 - type
 - mode
@@ -176,8 +206,6 @@ Keys for listing archive files:
 - sha3_384
 - sha3_512
 - sha512
-- shake_128
-- shake_256
 - xxh64: XXH64 checksum of this file (note: this is NOT a cryptographic hash!)
 
 - archiveid

docs/usage/mount.rst.inc

@@ -124,6 +124,23 @@ To allow a regular user to use fstab entries, add the ``user`` option:
 
 For FUSE configuration and mount options, see the mount.fuse(8) manual page.
 
+Borg's default behavior is to use the archived user and group names of each
+file and map them to the system's respective user and group ids.
+Alternatively, using ``numeric-ids`` will instead use the archived user and
+group ids without any mapping.
+
+The ``uid`` and ``gid`` mount options (implemented by Borg) can be used to
+override the user and group ids of all files (i.e., ``borg mount -o
+uid=1000,gid=1000``).
+
+The man page references ``user_id`` and ``group_id`` mount options
+(implemented by fuse) which specify the user and group id of the mount owner
+(aka, the user who does the mounting). It is set automatically by libfuse (or
+the filesystem if libfuse is not used). However, you should not specify these
+manually. Unlike the ``uid`` and ``gid`` mount options which affect all files,
+``user_id`` and ``group_id`` affect the user and group id of the mounted
+(base) directory.
+
 Additional mount options supported by borg:
 
 - versions: when used with a repository mount, this gives a merged, versioned

docs/usage/prune.rst.inc

@@ -103,7 +103,9 @@ any of the specified retention options.
 Important: Repository disk space is **not** freed until you run ``borg compact``.
 
 This command is normally used by automated backup scripts wanting to keep a
-certain number of historic backups.
+certain number of historic backups. This retention policy is commonly referred to as
+`GFS <https://en.wikipedia.org/wiki/Backup_rotation_scheme#Grandfather-father-son>`_
+(Grandfather-father-son) backup rotation scheme.
 
 Also, prune automatically removes checkpoint archives (incomplete archives left
 behind by interrupted backup runs) except if the checkpoint is the latest