From 6658112f8c77dd7952d71cb9e7ceee85338bbb28 Mon Sep 17 00:00:00 2001 From: Abogical Date: Tue, 21 Jun 2016 16:18:19 +0300 Subject: [PATCH] Add documentation for listing repository archives --- docs/usage/list.rst.inc | 25 ++++++++++++++++--------- src/borg/archiver.py | 9 +++++++-- src/borg/helpers.py | 26 ++++++++++++++++++++------ 3 files changed, 43 insertions(+), 17 deletions(-) diff --git a/docs/usage/list.rst.inc b/docs/usage/list.rst.inc index 23827ea81..4917c269f 100644 --- a/docs/usage/list.rst.inc +++ b/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 diff --git a/src/borg/archiver.py b/src/borg/archiver.py index 4cf79e991..04b75d631 100644 --- a/src/borg/archiver.py +++ b/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__, diff --git a/src/borg/helpers.py b/src/borg/helpers.py index 2173add59..a62ca54fb 100644 --- a/src/borg/helpers.py +++ b/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)