Update usage docs

borg/archiver.py

@@ -1212,6 +1212,11 @@ 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 only chunks IDs
+            are compared, which is very fast. For archives prior to Borg 1.1 chunk contents must be
+            compared, unless you are sure they were created with the same 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 +1294,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 +1321,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

docs/usage.rst

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

docs/usage/diff.rst.inc

@@ -48,4 +48,9 @@ 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 only chunks IDs
+are compared, which is very fast. For archives prior to Borg 1.1 chunk contents must be
+compared, unless you are sure they were created with the same 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,59 @@ 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:
+
+ - archiveid
+ - archivename
+ - atime
+ - bpath: verbatim POSIX path, can contain any character except NUL
+ - csize: compressed size
+ - ctime
+ - extra
+ - gid
+ - group
+ - isoatime
+ - isoctime
+ - isomtime
+ - linktarget
+ - md5
+ - mode
+ - mtime
+ - num_chunks: number of chunks in this file
+ - path: path interpreted as text (might be missing non-text characters, see bpath)
+ - sha1
+ - sha224
+ - sha256
+ - sha384
+ - sha512
+ - size
+ - source: link target for links (identical to linktarget)
+ - type
+ - uid
+ - unique_chunks: number of unique chunks in this file
+ - user
+ - CR
+ - LF
+ - NEWLINE: OS dependent line separator
+ - NL: alias of NEWLINE
+ - NUL: NUL character for creating print0 / xargs -0 like ouput, see bpath
+ - SPACE
+ - TAB