From abb0a20d4f2539e25a0277b7a1c6bc2426888fc1 Mon Sep 17 00:00:00 2001
From: Marian Beermann <public@enkore.de>
Date: Wed, 1 Mar 2017 16:58:06 +0100
Subject: [PATCH] list: files->items, clarifications

---
 docs/internals/frontends.rst   | 15 ++++++---------
 src/borg/helpers.py            |  4 +++-
 src/borg/testsuite/archiver.py | 12 ++++++------
 3 files changed, 15 insertions(+), 16 deletions(-)

diff --git a/docs/internals/frontends.rst b/docs/internals/frontends.rst
index 0553cd000..df6d50329 100644
--- a/docs/internals/frontends.rst
+++ b/docs/internals/frontends.rst
@@ -42,7 +42,7 @@ archive_progress
 
 progress_message
     A message-based progress information with no concrete progress information, just a message
-    saying what is currently worked on.
+    saying what is currently being worked on.
 
     operation
         unique, opaque integer ID of the operation
@@ -209,7 +209,7 @@ array under the *archives* key, while :ref:`borg_create` returns a single archiv
 Both formats contain a *name* key with the archive name, the *id* key with the hexadecimal archive ID,
 and the *start* key with the start timestamp.
 
-info and create further have:
+*borg info* and *borg create* further have:
 
 end
     End timestamp
@@ -250,11 +250,8 @@ Example of a simple archive listing (``borg list --last 1 --json``)::
     {
         "archives": [
             {
-                "archive": "2017-02-27T21:21:51",
-                "barchive": "2017-02-27T21:21:51",
                 "id": "80cd07219ad725b3c5f665c1dcf119435c4dee1647a560ecac30f8d40221a46a",
-                "name": "2017-02-27T21:21:51",
-                "time": "Mon, 2017-02-27 21:21:52",
+                "name": "host-system-backup-2017-02-27",
                 "start": "Mon, 2017-02-27 21:21:52"
             }
         ],
@@ -287,7 +284,7 @@ The same archive with more information (``borg info --last 1 --json``)::
                 "limits": {
                     "max_archive_size": 0.0001330855110409714
                 },
-                "name": "2017-02-27T21:21:51",
+                "name": "host-system-backup-2017-02-27",
                 "start": "Mon, 2017-02-27 21:21:52",
                 "stats": {
                     "compressed_size": 1880961894,
@@ -322,7 +319,7 @@ The same archive with more information (``borg info --last 1 --json``)::
 .. rubric:: File listings
 
 Listing the contents of an archive can produce *a lot* of JSON. Each item (file, directory, ...) is described
-by one object in the *files* array of the :ref:`borg_list` output. Refer to the *borg list* documentation for
+by one object in the *items* array of the :ref:`borg_list` output. Refer to the *borg list* documentation for
 the available keys and their meaning.
 
 Example (excerpt)::
@@ -336,7 +333,7 @@ Example (excerpt)::
             "last_modified": "Mon, 2017-02-27 21:21:58",
             "location": "/home/user/repository"
         },
-        "files": [
+        "items": [
             {
                 "type": "d",
                 "mode": "drwxr-xr-x",
diff --git a/src/borg/helpers.py b/src/borg/helpers.py
index 9f5de739d..db9fc92db 100644
--- a/src/borg/helpers.py
+++ b/src/borg/helpers.py
@@ -1617,11 +1617,13 @@ class ArchiveFormatter(BaseFormatter):
 
     def get_item_data(self, archive):
         return {
+            # *name* is the key used by borg-info for the archive name, this makes the formats more compatible
             'name': remove_surrogates(archive.name),
             'barchive': archive.name,
             'archive': remove_surrogates(archive.name),
             'id': bin_to_hex(archive.id),
             'time': format_time(to_localtime(archive.ts)),
+            # *start* is the key used by borg-info for this timestamp, this makes the formats more compatible
             'start': format_time(to_localtime(archive.ts)),
         }
 
@@ -1726,7 +1728,7 @@ class ItemFormatter(BaseFormatter):
         begin = json_dump(basic_json_data(self.archive.manifest))
         begin, _, _ = begin.rpartition('\n}')  # remove last closing brace, we want to extend the object
         begin += ',\n'
-        begin += '    "files": [\n'
+        begin += '    "items": [\n'
         return begin
 
     def end(self):
diff --git a/src/borg/testsuite/archiver.py b/src/borg/testsuite/archiver.py
index 6793e0de9..b59b2cb50 100644
--- a/src/borg/testsuite/archiver.py
+++ b/src/borg/testsuite/archiver.py
@@ -1535,17 +1535,17 @@ class ArchiverTestCase(ArchiverTestCaseBase):
 
         list_archive = json.loads(self.cmd('list', '--json', self.repository_location + '::test'))
         assert list_repo['repository'] == list_archive['repository']
-        files = list_archive['files']
-        assert len(files) == 2
-        file1 = files[1]
+        items = list_archive['items']
+        assert len(items) == 2
+        file1 = items[1]
         assert file1['path'] == 'input/file1'
         assert file1['size'] == 81920
 
         list_archive = json.loads(self.cmd('list', '--json', '--format={sha256}', self.repository_location + '::test'))
         assert list_repo['repository'] == list_archive['repository']
-        files = list_archive['files']
-        assert len(files) == 2
-        file1 = files[1]
+        items = list_archive['items']
+        assert len(items) == 2
+        file1 = items[1]
         assert file1['path'] == 'input/file1'
         assert file1['sha256'] == 'b2915eb69f260d8d3c25249195f2c8f4f716ea82ec760ae929732c0262442b2b'