ran build_usage1.1.0b1

11 files changed, 89 insertions, 99 deletions

diff --git a/docs/usage/check.rst.inc b/docs/usage/check.rst.inc
index 17d6cf492..a142df986 100644
--- a/docs/usage/check.rst.inc
+++ b/docs/usage/check.rst.inc
@@ -81,7 +81,3 @@ which will detect (accidental) corruption. For encrypted repositories it is
 tamper-resistant as well, unless the attacker has access to the keys.
 
 It is also very slow.
-
---verify-data only verifies data used by the archives specified with --last,
---prefix or an explicitly named archive. If none of these are passed,
-all data in the repository is verified.
diff --git a/docs/usage/common-options.rst.inc b/docs/usage/common-options.rst.inc
index 0a3c3c3ed..29bada9d8 100644
--- a/docs/usage/common-options.rst.inc
+++ b/docs/usage/common-options.rst.inc
@@ -10,6 +10,8 @@
         | work on log level INFO
     ``--debug``
         | enable debug output, work on log level DEBUG
+    ``--debug-topic TOPIC``
+        | enable TOPIC debugging (can be specified multiple times). The logger path is borg.debug.<TOPIC> if TOPIC is not fully qualified.
     ``--lock-wait N``
         | wait for the lock, but max. N seconds (default: 1).
     ``--show-version``
@@ -21,4 +23,6 @@
     ``--umask M``
         | set umask to M (local and remote, default: 0077)
     ``--remote-path PATH``
-        | set remote path to executable (default: "borg")
\ No newline at end of file
+        | set remote path to executable (default: "borg")
+    ``--consider-part-files``
+        | treat part files like normal files (e.g. to list/extract them)
\ No newline at end of file
diff --git a/docs/usage/create.rst.inc b/docs/usage/create.rst.inc
index 6e176a52e..7b31c18cd 100644
--- a/docs/usage/create.rst.inc
+++ b/docs/usage/create.rst.inc
@@ -63,7 +63,8 @@ Archive options
     ``-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]
+        | auto,C[,L] == built-in heuristic (try with lz4 whether the data is
+        |               compressible) decides between none or C[,L] - with C[,L]
         |               being any valid compression algorithm (and optional level),
         | lz4 == lz4,
         | zlib == zlib (default level 6),
@@ -85,7 +86,7 @@ The archive name needs to be unique. It must not end in '.checkpoint' or
 checkpoints and treated in special ways.
 
 In the archive name, you may use the following format tags:
-{now}, {utcnow}, {fqdn}, {hostname}, {user}, {pid}, {uuid4}
+{now}, {utcnow}, {fqdn}, {hostname}, {user}, {pid}, {uuid4}, {borgversion}
 
 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
diff --git a/docs/usage/debug-dump-repo-objs.rst.inc b/docs/usage/debug-dump-repo-objs.rst.inc
index 4fcd45ae8..3910a126d 100644
--- a/docs/usage/debug-dump-repo-objs.rst.inc
+++ b/docs/usage/debug-dump-repo-objs.rst.inc
@@ -6,32 +6,15 @@ borg debug-dump-repo-objs
 -------------------------
 ::
 
-    usage: borg debug-dump-repo-objs [-h] [--critical] [--error] [--warning]
-                                     [--info] [--debug] [--lock-wait N]
-                                     [--show-rc] [--no-files-cache] [--umask M]
-                                     [--remote-path PATH]
-                                     REPOSITORY
-    
-    dump (decrypted, decompressed) repo objects
-    
-    positional arguments:
-      REPOSITORY            repo to dump
-    
-    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 debug-dump-repo-objs <options> REPOSITORY
+
+positional arguments
+    REPOSITORY
+        repo to dump
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 
diff --git a/docs/usage/debug-info.rst.inc b/docs/usage/debug-info.rst.inc
index 2f4f7237f..4812aaf45 100644
--- a/docs/usage/debug-info.rst.inc
+++ b/docs/usage/debug-info.rst.inc
@@ -6,27 +6,11 @@ borg debug-info
 ---------------
 ::
 
-    usage: borg debug-info [-h] [--critical] [--error] [--warning] [--info]
-                           [--debug] [--lock-wait N] [--show-rc]
-                           [--no-files-cache] [--umask M] [--remote-path PATH]
-    
-    display system information for debugging / bug reports
-    
-    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 debug-info <options>
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 
diff --git a/docs/usage/extract.rst.inc b/docs/usage/extract.rst.inc
index c68eaa768..682eaa3a9 100644
--- a/docs/usage/extract.rst.inc
+++ b/docs/usage/extract.rst.inc
@@ -15,6 +15,8 @@ positional arguments
         paths to extract; patterns are supported
 
 optional arguments
+    ``-p``, ``--progress``
+        | show progress while extracting (may be slower)
     ``--list``
         | output verbose list of items (files, dirs, ...)
     ``-n``, ``--dry-run``
diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc
index 4d7c776a7..b079dd2d6 100644
--- a/docs/usage/help.rst.inc
+++ b/docs/usage/help.rst.inc
@@ -1,43 +1,5 @@
 .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit!
 
-.. _borg_placeholders:
-
-borg help placeholders
-~~~~~~~~~~~~~~~~~~~~~~
-
-
-Repository (or Archive) URLs and --prefix values support these placeholders:
-
-{hostname}
-
-    The (short) hostname of the machine.
-
-{fqdn}
-
-    The full name of the machine.
-
-{now}
-
-    The current local date and time.
-
-{utcnow}
-
-    The current UTC date and time.
-
-{user}
-
-    The user name (or UID, if no name is available) of the user running borg.
-
-{pid}
-
-    The current process ID.
-
-Examples::
-
-    borg create /path/to/repo::{hostname}-{user}-{utcnow} ...
-    borg create /path/to/repo::{hostname}-{now:%Y-%m-%d_%H:%M:%S} ...
-    borg prune --prefix '{hostname}-' ...
-
 .. _borg_patterns:
 
 borg help patterns
@@ -131,3 +93,46 @@ Examples::
     EOF
     $ borg create --exclude-from exclude.txt backup /
 
+.. _borg_placeholders:
+
+borg help placeholders
+~~~~~~~~~~~~~~~~~~~~~~
+
+
+ Repository (or Archive) URLs, --prefix and --remote-path values support these
+ placeholders:
+
+ {hostname}
+
+     The (short) hostname of the machine.
+
+ {fqdn}
+
+     The full name of the machine.
+
+ {now}
+
+     The current local date and time.
+
+ {utcnow}
+
+     The current UTC date and time.
+
+ {user}
+
+     The user name (or UID, if no name is available) of the user running borg.
+
+ {pid}
+
+     The current process ID.
+
+ {borgversion}
+
+     The version of borg.
+
+Examples::
+
+     borg create /path/to/repo::{hostname}-{user}-{utcnow} ...
+     borg create /path/to/repo::{hostname}-{now:%Y-%m-%d_%H:%M:%S} ...
+     borg prune --prefix '{hostname}-' ...
+
diff --git a/docs/usage/info.rst.inc b/docs/usage/info.rst.inc
index e9e5f8935..e4a27e7b5 100644
--- a/docs/usage/info.rst.inc
+++ b/docs/usage/info.rst.inc
@@ -6,11 +6,11 @@ borg info
 ---------
 ::
 
-    borg info <options> ARCHIVE
+    borg info <options> REPOSITORY_OR_ARCHIVE
 
 positional arguments
-    ARCHIVE
-        archive to display information about
+    REPOSITORY_OR_ARCHIVE
+        archive or repository to display information about
 
 `Common options`_
     |
@@ -18,8 +18,10 @@ positional arguments
 Description
 ~~~~~~~~~~~
 
-This command displays some detailed information about the specified archive.
+This command displays detailed information about the specified archive or repository.
 
-The "This archive" line refers exclusively to this archive:
-"Deduplicated size" is the size of the unique chunks stored only for this
-archive. Non-unique / common chunks show up under "All archives".
+The "This archive" line refers exclusively to the given archive:
+"Deduplicated size" is the size of the unique chunks stored only for the
+given archive.
+
+The "All archives" line shows global statistics (all chunks).
diff --git a/docs/usage/init.rst.inc b/docs/usage/init.rst.inc
index b2c84131c..7b9894974 100644
--- a/docs/usage/init.rst.inc
+++ b/docs/usage/init.rst.inc
@@ -15,6 +15,8 @@ positional arguments
 optional arguments
     ``-e``, ``--encryption``
         | select encryption key mode (default: "repokey")
+    ``-a``, ``--append-only``
+        | create an append-only mode repository
 
 `Common options`_
     |
diff --git a/docs/usage/mount.rst.inc b/docs/usage/mount.rst.inc
index cac84a437..a9f3668e2 100644
--- a/docs/usage/mount.rst.inc
+++ b/docs/usage/mount.rst.inc
@@ -41,6 +41,8 @@ To allow a regular user to use fstab entries, add the ``user`` option:
 For mount options, see the fuse(8) manual page. Additional mount options
 supported by borg:
 
+- versions: when used with a repository mount, this gives a merged, versioned
+  view of the files in the archives. EXPERIMENTAL, layout may change in future.
 - allow_damaged_files: by default damaged files (where missing chunks were
   replaced with runs of zeros by borg check --repair) are not readable and
   return EIO (I/O error). Set this option to read such files.
diff --git a/docs/usage/recreate.rst.inc b/docs/usage/recreate.rst.inc
index f4134b0a8..56a6e07fa 100644
--- a/docs/usage/recreate.rst.inc
+++ b/docs/usage/recreate.rst.inc
@@ -42,6 +42,8 @@ Exclusion options
         | keep tag files of excluded caches/directories
 
 Archive options
+    ``--target TARGET``
+        | create a new archive with the name ARCHIVE, do not replace existing archive (only applies for a single archive)
     ``--comment COMMENT``
         | add a comment text to the archive
     ``--timestamp yyyy-mm-ddThh:mm:ss``
@@ -56,6 +58,8 @@ Archive options
         | zlib,0 .. zlib,9 == zlib (with level 0..9),
         | lzma == lzma (default level 6),
         | lzma,0 .. lzma,9 == lzma (with level 0..9).
+    ``--always-recompress``
+        | always recompress chunks, don't skip chunks already compressed with the samealgorithm.
     ``--compression-from COMPRESSIONCONFIG``
         | read compression patterns from COMPRESSIONCONFIG, one per line
     ``--chunker-params CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,HASH_WINDOW_SIZE``
@@ -70,6 +74,9 @@ Recreate the contents of existing archives.
 as in "borg create". If PATHs are specified the resulting archive
 will only contain files from these PATHs.
 
+Note that all paths in an archive are relative, therefore absolute patterns/paths
+will *not* match (--exclude, --exclude-from, --compression-from, PATHs).
+
 --compression: all chunks seen will be stored using the given method.
 Due to how Borg stores compressed size information this might display
 incorrect information for archives that were not recreated at the same time.
@@ -98,6 +105,8 @@ The archive being recreated is only removed after the operation completes. The
 archive that is built during the operation exists at the same time at
 "<ARCHIVE>.recreate". The new archive will have a different archive ID.
 
+With --target the original archive is not replaced, instead a new archive is created.
+
 When rechunking space usage can be substantial, expect at least the entire
 deduplicated size of the archives using the previous chunker params.
 When recompressing approximately 1 % of the repository size or 512 MB