ran build_usage

had merge conflicts in the usage files, decided to just recreate them afterwards.

docs/usage/check.rst.inc

@@ -23,16 +23,22 @@ optional arguments
         | attempt to repair any inconsistencies found
     ``--save-space``
         | work slower, but using less space
-    ``--last N``
-        | only check last N archives (Default: all)
-    ``-P``, ``--prefix``
-        | only consider archive names starting with this prefix
     ``-p``, ``--progress``
         | show progress display while checking
 
 `Common options`_
     |
 
+filters
+    ``-P``, ``--prefix``
+        | only consider archive names starting with this prefix
+    ``--sort-by``
+        | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+    ``--first N``
+        | consider first N archives after other filters were applied
+    ``--last N``
+        | consider last N archives after other filters were applied
+
 Description
 ~~~~~~~~~~~
 

docs/usage/create.rst.inc

@@ -46,6 +46,10 @@ Filesystem options
         | stay in same file system, do not cross mount points
     ``--numeric-owner``
         | only store numeric user and group identifiers
+    ``--noatime``
+        | do not store atime into archive
+    ``--noctime``
+        | do not store ctime into archive
     ``--ignore-inode``
         | ignore inode data in the file metadata cache used to detect unchanged files.
     ``--read-special``
@@ -76,8 +80,8 @@ The archive name needs to be unique. It must not end in '.checkpoint' or
 '.checkpoint.N' (with N being a number), because these names are used for
 checkpoints and treated in special ways.
 
-In the archive name, you may use the following format tags:
-{now}, {utcnow}, {fqdn}, {hostname}, {user}, {pid}, {uuid4}, {borgversion}
+In the archive name, you may use the following placeholders:
+{now}, {utcnow}, {fqdn}, {hostname}, {user} and some others.
 
 To speed up pulling backups over sshfs and similar network file systems which do
 not provide correct inode information the --ignore-inode flag can be used. This

docs/usage/diff.rst.inc

@@ -6,15 +6,15 @@ borg diff
 ---------
 ::
 
-    borg diff <options> ARCHIVE1 ARCHIVE2 PATH
+    borg diff <options> REPO_ARCHIVE1 ARCHIVE2 PATH
 
 positional arguments
-    ARCHIVE1
-        archive
+    REPO_ARCHIVE1
+        repository location and ARCHIVE1 name
     ARCHIVE2
-        archive to compare with ARCHIVE1 (no repository location)
+        ARCHIVE2 name (no repository location allowed)
     PATH
-        paths to compare; patterns are supported
+        paths of items inside the archives to compare; patterns are supported
 
 optional arguments
     ``-e PATTERN``, ``--exclude PATTERN``
@@ -34,10 +34,11 @@ optional arguments
 Description
 ~~~~~~~~~~~
 
-This command finds differences in files (contents, user, group, mode) between archives.
+This command finds differences (file contents, user/group/mode) between archives.
 
-Both archives need to be in the same repository, and a repository location may only
-be specified for ARCHIVE1.
+A repository location and an archive name must be specified for REPO_ARCHIVE1.
+ARCHIVE2 is just another archive name in same repository (no repository location
+allowed).
 
 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

docs/usage/help.rst.inc

@@ -130,19 +130,19 @@ placeholders:
 
 {borgversion}
 
-     The version of borg, e.g.: 1.0.8rc1
+    The version of borg, e.g.: 1.0.8rc1
 
- {borgmajor}
+{borgmajor}
 
-     The version of borg, only the major version, e.g.: 1
+    The version of borg, only the major version, e.g.: 1
 
- {borgminor}
+{borgminor}
 
-     The version of borg, only major and minor version, e.g.: 1.0
+    The version of borg, only major and minor version, e.g.: 1.0
 
- {borgpatch}
+{borgpatch}
 
-     The version of borg, only major, minor and patch version, e.g.: 1.0.8
+    The version of borg, only major, minor and patch version, e.g.: 1.0.8
 
 Examples::
 

docs/usage/init.rst.inc

@@ -66,5 +66,18 @@ a different keyboard layout.
 You can change your passphrase for existing repos at any time, it won't affect
 the encryption/decryption key or other secrets.
 
-When encrypting, AES-CTR-256 is used for encryption, and HMAC-SHA256 for
-authentication. Hardware acceleration will be used automatically.
+Encryption modes
+++++++++++++++++
+
+repokey and keyfile use AES-CTR-256 for encryption and HMAC-SHA256 for
+authentication in an encrypt-then-MAC (EtM) construction. The chunk ID hash
+is HMAC-SHA256 as well (with a separate key).
+
+repokey-blake2 and keyfile-blake2 use the same authenticated encryption, but
+use a keyed BLAKE2b-256 hash for the chunk ID hash.
+
+"authenticated" mode uses no encryption, but authenticates repository contents
+through the same keyed BLAKE2b-256 hash as the other blake2 modes.
+The key is stored like repokey.
+
+Hardware acceleration will be used automatically.

docs/usage/mount.rst.inc

@@ -23,6 +23,16 @@ optional arguments
 `Common options`_
     |
 
+filters
+    ``-P``, ``--prefix``
+        | only consider archive names starting with this prefix
+    ``--sort-by``
+        | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+    ``--first N``
+        | consider first N archives after other filters were applied
+    ``--last N``
+        | consider last N archives after other filters were applied
+
 Description
 ~~~~~~~~~~~
 

docs/usage/prune.rst.inc

@@ -61,6 +61,8 @@ If a prefix is set with -P, then only archives that start with the prefix are
 considered for deletion and only those archives count towards the totals
 specified by the rules.
 Otherwise, *all* archives in the repository are candidates for deletion!
+There is no automatic distinction between archives representing different
+contents. These need to be distinguished by specifying matching prefixes.
 
 If you have multiple sequences of archives with different data sets (e.g.
 from different machines) in one shared repository, use one prune call per

docs/usage/recreate.rst.inc

@@ -44,24 +44,18 @@ Exclusion options
 Archive options
     ``--target TARGET``
         | create a new archive with the name ARCHIVE, do not replace existing archive (only applies for a single archive)
+    ``-c SECONDS``, ``--checkpoint-interval SECONDS``
+        | write checkpoint every SECONDS seconds (Default: 1800)
     ``--comment COMMENT``
         | add a comment text to the archive
     ``--timestamp yyyy-mm-ddThh:mm:ss``
         | manually specify the archive creation date/time (UTC). alternatively, give a reference file/directory.
     ``-C COMPRESSION``, ``--compression COMPRESSION``
-        | select compression algorithm (and level):
-        | none == no compression (default),
-        | auto,C[,L] == built-in heuristic decides between none or C[,L] - with C[,L]
-        |               being any valid compression algorithm (and optional level),
-        | lz4 == lz4,
-        | zlib == zlib (default level 6),
-        | zlib,0 .. zlib,9 == zlib (with level 0..9),
-        | lzma == lzma (default level 6),
-        | lzma,0 .. lzma,9 == lzma (with level 0..9).
+        | select compression algorithm, see the output of the "borg help compression" command for details.
     ``--always-recompress``
-        | always recompress chunks, don't skip chunks already compressed with the samealgorithm.
+        | always recompress chunks, don't skip chunks already compressed with the same algorithm.
     ``--compression-from COMPRESSIONCONFIG``
-        | read compression patterns from COMPRESSIONCONFIG, one per line
+        | read compression patterns from COMPRESSIONCONFIG, see the output of the "borg help compression" command for details.
     ``--chunker-params CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,HASH_WINDOW_SIZE``
         | specify the chunker parameters (or "default").
 

docs/usage/umount.rst.inc

@@ -6,31 +6,15 @@ borg umount
 -----------
 ::
 
-    usage: borg umount [-h] [--critical] [--error] [--warning] [--info] [--debug]
-                       [--lock-wait N] [--show-rc] [--no-files-cache] [--umask M]
-                       [--remote-path PATH]
-                       MOUNTPOINT
-    
-    un-mount the FUSE filesystem
-    
-    positional arguments:
-      MOUNTPOINT            mountpoint of the filesystem to umount
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-    
+    borg umount <options> MOUNTPOINT
+
+positional arguments
+    MOUNTPOINT
+        mountpoint of the filesystem to umount
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~