Add documentation for listing repository archives

docs/usage/list.rst.inc

@@ -35,8 +35,22 @@ This command lists the contents of a repository or an archive.
 
 See the "borg help patterns" command for more help on exclude patterns.
 
-The following keys are available for --format when listing files:
+The following keys are available for --format:
+ - NEWLINE: OS dependent line separator
+ - NL: alias of NEWLINE
+ - NUL: NUL character for creating print0 / xargs -0 like output, see barchive/bpath
+ - SPACE
+ - TAB
+ - CR
+ - LF
 
+-- Keys for listing repository archives:
+ - 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
+ - id: internal ID of the archive
+
+-- Keys for listing archive files:
  - type
  - mode
  - uid
@@ -47,6 +61,7 @@ The following keys are available for --format when listing files:
  - bpath: verbatim POSIX path, can contain any character except NUL
  - source: link target for links (identical to linktarget)
  - linktarget
+ - flags
 
  - size
  - csize: compressed size
@@ -70,11 +85,3 @@ The following keys are available for --format when listing files:
  - archiveid
  - archivename
  - extra: prepends {source} with " -> " for soft links and " link to " for hard links
-
- - NEWLINE: OS dependent line separator
- - NL: alias of NEWLINE
- - NUL: NUL character for creating print0 / xargs -0 like ouput, see bpath
- - SPACE
- - TAB
- - CR
- - LF

src/borg/archiver.py

@@ -29,7 +29,7 @@ from .constants import *  # NOQA
 from .helpers import EXIT_SUCCESS, EXIT_WARNING, EXIT_ERROR
 from .helpers import Error, NoManifestError
 from .helpers import location_validator, archivename_validator, ChunkerParams, CompressionSpec
-from .helpers import ItemFormatter, ArchiveFormatter, format_time, format_file_size, format_archive
+from .helpers import BaseFormatter, ItemFormatter, ArchiveFormatter, format_time, format_file_size, format_archive
 from .helpers import safe_encode, remove_surrogates, bin_to_hex
 from .helpers import prune_within, prune_split
 from .helpers import to_localtime, timestamp
@@ -1625,8 +1625,13 @@ class Archiver:
 
         See the "borg help patterns" command for more help on exclude patterns.
 
-        The following keys are available for --format when listing files:
+        The following keys are available for --format:
+        """) + BaseFormatter.keys_help() + textwrap.dedent("""
 
+        -- Keys for listing repository archives:
+        """) + ArchiveFormatter.keys_help() + textwrap.dedent("""
+
+        -- Keys for listing archive files:
         """) + ItemFormatter.keys_help()
         subparser = subparsers.add_parser('list', parents=[common_parser], add_help=False,
                                           description=self.do_list.__doc__,

src/borg/helpers.py

@@ -1150,6 +1150,16 @@ class BaseFormatter:
     def format_item(self, item):
         return self.format.format_map(self.get_item_data(item))
 
+    @staticmethod
+    def keys_help():
+        return " - NEWLINE: OS dependent line separator\n" \
+               " - NL: alias of NEWLINE\n" \
+               " - NUL: NUL character for creating print0 / xargs -0 like output, see barchive/bpath\n" \
+               " - SPACE\n" \
+               " - TAB\n" \
+               " - CR\n" \
+               " - LF"
+
 
 class ArchiveFormatter(BaseFormatter):
 
@@ -1164,6 +1174,13 @@ class ArchiveFormatter(BaseFormatter):
             'time': format_time(to_localtime(archive.ts)),
         }
 
+    @staticmethod
+    def keys_help():
+        return " - archive: archive name interpreted as text (might be missing non-text characters, see barchive)\n" \
+               " - barchive: verbatim archive name, can contain any character except NUL\n" \
+               " - time: time of creation of the archive\n" \
+               " - id: internal ID of the archive"
+
 
 class ItemFormatter(BaseFormatter):
     KEY_DESCRIPTIONS = {
@@ -1171,14 +1188,9 @@ class ItemFormatter(BaseFormatter):
         'path': 'path interpreted as text (might be missing non-text characters, see bpath)',
         'source': 'link target for links (identical to linktarget)',
         'extra': 'prepends {source} with " -> " for soft links and " link to " for hard links',
-
         'csize': 'compressed size',
         'num_chunks': 'number of chunks in this file',
         'unique_chunks': 'number of unique chunks in this file',
-
-        'NEWLINE': 'OS dependent line separator',
-        'NL': 'alias of NEWLINE',
-        'NUL': 'NUL character for creating print0 / xargs -0 like ouput, see bpath',
     }
     KEY_GROUPS = (
         ('type', 'mode', 'uid', 'gid', 'user', 'group', 'path', 'bpath', 'source', 'linktarget', 'flags'),
@@ -1186,7 +1198,6 @@ class ItemFormatter(BaseFormatter):
         ('mtime', 'ctime', 'atime', 'isomtime', 'isoctime', 'isoatime'),
         tuple(sorted(hashlib.algorithms_guaranteed)),
         ('archiveid', 'archivename', 'extra'),
-        ('NEWLINE', 'NL', 'NUL', 'SPACE', 'TAB', 'CR', 'LF'),
     )
 
     @classmethod
@@ -1206,6 +1217,9 @@ class ItemFormatter(BaseFormatter):
     def keys_help(cls):
         help = []
         keys = cls.available_keys()
+        for key in cls.FIXED_KEYS:
+            keys.remove(key)
+
         for group in cls.KEY_GROUPS:
             for key in group:
                 keys.remove(key)