ran build_usage

docs/usage/create.rst.inc

@@ -72,8 +72,6 @@ Archive options
         | specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: 19,23,21,4095
     ``-C COMPRESSION``, ``--compression COMPRESSION``
         | select compression algorithm, see the output of the "borg help compression" command for details.
-    ``--compression-from COMPRESSIONCONFIG``
-        | read compression patterns from COMPRESSIONCONFIG, see the output of the "borg help compression" command for details.
 
 Description
 ~~~~~~~~~~~

docs/usage/help.rst.inc

@@ -196,6 +196,10 @@ placeholders:
 
     The version of borg, only major, minor and patch version, e.g.: 1.0.8
 
+If literal curly braces need to be used, double them for escaping::
+
+    borg create /path/to/repo::{{literal_text}}
+
 Examples::
 
     borg create /path/to/repo::{hostname}-{user}-{utcnow} ...
@@ -245,43 +249,13 @@ auto,C[,L]
     For compressible data, it uses the given C[,L] compression - with C[,L]
     being any valid compression specifier.
 
-The decision about which compression to use is done by borg like this:
-
-1. find a compression specifier (per file):
-   match the path/filename against all patterns in all --compression-from
-   files (if any). If a pattern matches, use the compression spec given for
-   that pattern. If no pattern matches (and also if you do not give any
-   --compression-from option), default to the compression spec given by
-   --compression. See docs/misc/compression.conf for an example config.
-
-2. if the found compression spec is not "auto", the decision is taken:
-   use the found compression spec.
-
-3. if the found compression spec is "auto", test compressibility of each
-   chunk using lz4.
-   If it is compressible, use the C,[L] compression spec given within the
-   "auto" specifier. If it is not compressible, use no compression.
-
 Examples::
 
     borg create --compression lz4 REPO::ARCHIVE data
     borg create --compression zlib REPO::ARCHIVE data
     borg create --compression zlib,1 REPO::ARCHIVE data
     borg create --compression auto,lzma,6 REPO::ARCHIVE data
-    borg create --compression-from compression.conf --compression auto,lzma ...
-
-compression.conf has entries like::
-
-    # example config file for --compression-from option
-    #
-    # Format of non-comment / non-empty lines:
-    # <compression-spec>:<path/filename pattern>
-    # compression-spec is same format as for --compression option
-    # path/filename pattern is same format as for --exclude option
-    none:*.gz
-    none:*.zip
-    none:*.mp3
-    none:*.ogg
+    borg create --compression auto,lzma ...
 
 General remarks:
 

docs/usage/recreate.rst.inc

@@ -56,10 +56,8 @@ Archive options
         | manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). alternatively, give a reference file/directory.
     ``-C COMPRESSION``, ``--compression COMPRESSION``
         | 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 same algorithm.
-    ``--compression-from COMPRESSIONCONFIG``
-        | read compression patterns from COMPRESSIONCONFIG, see the output of the "borg help compression" command for details.
+    ``--recompress``
+        | recompress data chunks according to --compression if "if-different". When "always", chunks that are already compressed that way are not skipped, but compressed again. Only the algorithm is considered for "if-different", not the compression level (if any).
     ``--chunker-params PARAMS``
         | specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or "default" to use the current defaults. default: 19,23,21,4095
 
@@ -75,9 +73,9 @@ have the exact same semantics 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).
+will *not* match (--exclude, --exclude-from, PATHs).
 
---compression: all chunks seen will be stored using the given method.
+--recompress allows to change the compression of existing data in archives.
 Due to how Borg stores compressed size information this might display
 incorrect information for archives that were not recreated at the same time.
 There is no risk of data loss by this.

docs/usage/upgrade.rst.inc

@@ -33,7 +33,20 @@ optional arguments
 Description
 ~~~~~~~~~~~
 
-Upgrade an existing Borg repository.
+Upgrade an existing, local Borg repository.
+
+When you do not need borg upgrade
++++++++++++++++++++++++++++++++++
+
+Not every change requires that you run ``borg upgrade``.
+
+You do **not** need to run it when:
+
+- moving your repository to a different place
+- upgrading to another point release (like 1.0.x to 1.0.y),
+  except when noted otherwise in the changelog
+- upgrading from 1.0.x to 1.1.x,
+  except when noted otherwise in the changelog
 
 Borg 1.x.y upgrades
 +++++++++++++++++++
@@ -65,8 +78,13 @@ helps with converting Borg 0.xx to 1.0.
 
 Currently, only LOCAL repositories can be upgraded (issue #465).
 
-It will change the magic strings in the repository's segments
-to match the new Borg magic strings. The keyfiles found in
+Please note that ``borg create`` (since 1.0.0) uses bigger chunks by
+default than old borg or attic did, so the new chunks won't deduplicate
+with the old chunks in the upgraded repository.
+See ``--chunker-params`` option of ``borg create`` and ``borg recreate``.
+
+``borg upgrade`` will change the magic strings in the repository's
+segments to match the new Borg magic strings. The keyfiles found in
 $ATTIC_KEYS_DIR or ~/.attic/keys/ will also be converted and
 copied to $BORG_KEYS_DIR or ~/.config/borg/keys.