Merge pull request #767 from enkore/feature-diff-docs

Update usage docs (diff and list)

borg/archiver.py

@@ -1212,6 +1212,15 @@ class Archiver:
             Both archives need to be in the same repository, and a repository location may only
             be specified for ARCHIVE1.
 
+            For archives created with Borg 1.1 or newer diff automatically detects whether
+            the archives are created with the same chunker params. If so, only chunk IDs
+            are compared, which is very fast.
+
+            For archives prior to Borg 1.1 chunk contents are compared by default.
+            If you did not create the archives with different chunker params,
+            pass --same-chunker-params.
+            Note that the chunker params changed from Borg 0.xx to 1.0.
+
             See the output of the "borg help patterns" command for more help on exclude patterns.
             """)
         subparser = subparsers.add_parser('diff', parents=[common_parser],
@@ -1289,7 +1298,7 @@ class Archiver:
 
         See the "borg help patterns" command for more help on exclude patterns.
 
-        The following keys are available for --format:
+        The following keys are available for --format when listing files:
 
         """) + ItemFormatter.keys_help()
         subparser = subparsers.add_parser('list', parents=[common_parser],
@@ -1316,7 +1325,7 @@ class Archiver:
                                type=location_validator(),
                                help='repository/archive to list contents of')
         subparser.add_argument('paths', metavar='PATH', nargs='*', type=str,
-                               help='paths to extract; patterns are supported')
+                               help='paths to list; patterns are supported')
 
         mount_epilog = textwrap.dedent("""
         This command mounts an archive as a FUSE filesystem. This can be useful for

borg/helpers.py

@@ -1128,16 +1128,27 @@ class ItemFormatter:
         'NL': os.linesep,
     }
     KEY_DESCRIPTIONS = {
-        'NEWLINE': 'OS dependent line separator',
-        'NL': 'alias of NEWLINE',
-        'NUL': 'NUL character for creating print0 / xargs -0 like ouput, see bpath',
-        'csize': 'compressed size',
         'bpath': 'verbatim POSIX path, can contain any character except NUL',
         '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'),
+        ('size', 'csize', 'num_chunks', 'unique_chunks'),
+        ('mtime', 'ctime', 'atime', 'isomtime', 'isoctime', 'isoatime'),
+        tuple(sorted(hashlib.algorithms_guaranteed)),
+        ('archiveid', 'archivename', 'extra'),
+        ('NEWLINE', 'NL', 'NUL', 'SPACE', 'TAB', 'CR', 'LF'),
+    )
 
     @classmethod
     def available_keys(cls):
@@ -1152,16 +1163,21 @@ class ItemFormatter:
         keys = []
         keys.extend(formatter.call_keys.keys())
         keys.extend(formatter.get_item_data(fake_item).keys())
-        return sorted(keys, key=lambda s: (s.isupper(), s))
+        return keys
 
     @classmethod
     def keys_help(cls):
         help = []
-        for key in cls.available_keys():
-            text = " - " + key
-            if key in cls.KEY_DESCRIPTIONS:
-                text += ": " + cls.KEY_DESCRIPTIONS[key]
-            help.append(text)
+        keys = cls.available_keys()
+        for group in cls.KEY_GROUPS:
+            for key in group:
+                keys.remove(key)
+                text = " - " + key
+                if key in cls.KEY_DESCRIPTIONS:
+                    text += ": " + cls.KEY_DESCRIPTIONS[key]
+                help.append(text)
+            help.append("")
+        assert not keys, str(keys)
         return "\n".join(help)
 
     def __init__(self, archive, format):

docs/usage.rst

@@ -374,6 +374,52 @@ Examples
     ...
 
 
+
+.. include:: usage/diff.rst.inc
+
+Examples
+~~~~~~~~
+::
+
+    $ borg init testrepo
+    $ mkdir testdir
+    $ cd testdir
+    $ echo asdf > file1
+    $ dd if=/dev/urandom bs=1M count=4 > file2
+    $ touch file3
+    $ borg create ../testrepo::archive1 .
+
+    $ chmod a+x file1
+    $ echo "something" >> file2
+    $ borg create ../testrepo::archive2 .
+
+    $ rm file3
+    $ touch file4
+    $ borg create ../testrepo::archive3 .
+
+    $ cd ..
+    $ borg diff testrepo::archive1 archive2
+    file1 different mode
+             archive1 -rw-r--r--
+             archive2 -rwxr-xr-x
+    file2 different contents
+             +28 B, -31 B, 4.19 MB, 4.19 MB
+
+    $ borg diff testrepo::archive2 archive3
+    file3 different contents
+             +0 B, -0 B, 0 B, <deleted>
+
+    $ borg diff testrepo::archive1 archive3
+    file1 different mode
+             archive1 -rw-r--r--
+             archive3 -rwxr-xr-x
+    file2 different contents
+             +28 B, -31 B, 4.19 MB, 4.19 MB
+    file3 different contents
+             +0 B, -0 B, 0 B, <deleted>
+    file4 different contents
+             +0 B, -0 B, <deleted>, 0 B
+
 .. include:: usage/delete.rst.inc
 
 Examples

docs/usage/diff.rst.inc

@@ -48,4 +48,13 @@ This command finds differences in files (contents, user, group, mode) between ar
 Both archives need to be in the same repository, and a repository location may only
 be specified for ARCHIVE1.
 
+For archives created with Borg 1.1 or newer diff automatically detects whether
+the archives are created with the same chunker params. If so, only chunk IDs
+are compared, which is very fast.
+
+For archives prior to Borg 1.1 chunk contents are compared by default.
+If you did not create the archives with different chunker params,
+pass --same-chunker-params.
+Note that the chunker params changed from Borg 0.xx to 1.0.
+
 See the output of the "borg help patterns" command for more help on exclude patterns.

docs/usage/list.rst.inc

@@ -6,15 +6,16 @@ borg list
 
     usage: borg list [-h] [-v] [--debug] [--lock-wait N] [--show-version]
                      [--show-rc] [--no-files-cache] [--umask M]
-                     [--remote-path PATH] [--short] [--list-format LISTFORMAT]
-                     [-P PREFIX]
-                     [REPOSITORY_OR_ARCHIVE]
+                     [--remote-path PATH] [--short] [--format FORMAT] [-P PREFIX]
+                     [-e PATTERN] [--exclude-from EXCLUDEFILE]
+                     [REPOSITORY_OR_ARCHIVE] [PATH [PATH ...]]
     
     List archive or repository contents
     
     positional arguments:
       REPOSITORY_OR_ARCHIVE
                             repository/archive to list contents of
+      PATH                  paths to list; patterns are supported
     
     optional arguments:
       -h, --help            show this help message and exit
@@ -30,15 +31,64 @@ borg list
       --umask M             set umask to M (local and remote, default: 0077)
       --remote-path PATH    set remote path to executable (default: "borg")
       --short               only print file/directory names, nothing else
-      --list-format LISTFORMAT
-                            specify format for archive file listing (default:
-                            "{mode} {user:6} {group:6} {size:8d} {isomtime}
-                            {path}{extra}{NEWLINE}") Special "{formatkeys}" exists
-                            to list available keys
+      --format FORMAT, --list-format FORMAT
+                            specify format for file listing (default: "{mode}
+                            {user:6} {group:6} {size:8d} {isomtime}
+                            {path}{extra}{NL}")
       -P PREFIX, --prefix PREFIX
                             only consider archive names starting with this prefix
+      -e PATTERN, --exclude PATTERN
+                            exclude paths matching PATTERN
+      --exclude-from EXCLUDEFILE
+                            read exclude patterns from EXCLUDEFILE, one per line
     
 Description
 ~~~~~~~~~~~
 
 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:
+
+ - type
+ - mode
+ - uid
+ - gid
+ - user
+ - group
+ - path: path interpreted as text (might be missing non-text characters, see bpath)
+ - bpath: verbatim POSIX path, can contain any character except NUL
+ - source: link target for links (identical to linktarget)
+ - linktarget
+
+ - size
+ - csize: compressed size
+ - num_chunks: number of chunks in this file
+ - unique_chunks: number of unique chunks in this file
+
+ - mtime
+ - ctime
+ - atime
+ - isomtime
+ - isoctime
+ - isoatime
+
+ - md5
+ - sha1
+ - sha224
+ - sha256
+ - sha384
+ - sha512
+
+ - 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