ran build_usage

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.

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")
+        | set remote path to executable (default: "borg")
+    ``--consider-part-files``
+        | treat part files like normal files (e.g. to list/extract them)

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

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
 ~~~~~~~~~~~
 

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
 ~~~~~~~~~~~
 

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``

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}-' ...
+

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).

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`_
     |

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.

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