Merge pull request #8484 from mrichtarsky/docs

Docs: Remove --bypass-lock, small changes regarding compression

docs/misc/asciinema/basic.json

@@ -251,7 +251,7 @@
 [14.369035, "o", "\r\r\n"]
 [14.369334, "o", "            [--debug-topic TOPIC] [-p] [--iec] [--log-json]"]
 [14.369527, "o", "\r\r\n"]
-[14.369709, "o", "            [--lock-wait SECONDS] [--bypass-lock] [--show-version] [--show-rc]"]
+[14.369709, "o", "            [--lock-wait SECONDS] [--show-version] [--show-rc]"]
 [14.36989, "o", "\r\r\n"]
 [14.370079, "o", "            [--umask M] [--remote-path PATH] [--remote-ratelimit RATE]"]
 [14.370256, "o", "\r\r\n"]
@@ -311,9 +311,6 @@
 [14.383122, "o", "                        lock (default: 1)."]
 [14.383368, "o", "\r"]
 [14.383442, "o", "\r\n"]
-[14.383674, "o", "  --bypass-lock         Bypass locking mechanism"]
-[14.383904, "o", "\r"]
-[14.38399, "o", "\r\n"]
 [14.384227, "o", "  --show-version        show/log the borg version"]
 [14.38446, "o", "\r"]
 [14.384533, "o", "\r\n"]

docs/quickstart.rst

@@ -292,35 +292,29 @@ Backup compression
 ------------------
 
 The default is lz4 (very fast, but low compression ratio), but other methods are
-supported for different situations.
+supported for different situations. Compression not only helps you save disk space,
+but will especially speed up remote backups since less data needs to be transferred.
 
-You can use zstd for a wide range from high speed (and relatively low
-compression) using N=1 to high compression (and lower speed) using N=22.
-
-zstd is a modern compression algorithm and might be preferable over zlib and
-lzma.::
+zstd is a modern compression algorithm which can be parametrized to anything between
+N=1 for highest speed (and relatively low compression) to N=22 for highest compression
+(and lower speed)::
 
     $ borg create --compression zstd,N arch ~
 
-Other options are:
-
-If you have a fast repo storage and you want minimum CPU usage, no compression::
+If you have a fast repo storage and you want minimum CPU usage you can disable
+compression::
 
     $ borg create --compression none arch ~
 
-If you have a less fast repo storage and you want a bit more compression (N=0..9,
-0 means no compression, 9 means high compression):
+You can also use zlib and lzma instead of zstd, although zstd usually provides the
+the best compression for a given resource consumption. Please see :ref:`borg_compression`
+for all options.
 
-::
+An interesting alternative is ``auto``, which first checks with lz4 whether a chunk is
+compressible (that check is very fast), and only if it is, compresses it with the
+specified algorithm::
 
-    $ borg create --compression zlib,N arch ~
-
-If you have a very slow repo storage and you want high compression (N=0..9, 0 means
-low compression, 9 means high compression):
-
-::
-
-    $ borg create --compression lzma,N arch ~
+    $ borg create --compression auto,zstd,7 arch ~
 
 You'll need to experiment a bit to find the best compression for your use case.
 Keep an eye on CPU load and throughput.

docs/usage/general.rst

@@ -31,20 +31,6 @@ All Borg commands share these options:
 
 .. include:: common-options.rst.inc
 
-Option ``--bypass-lock`` allows you to access the repository while bypassing
-borg's locking mechanism. This is necessary if your repository is on a read-only
-storage where you don't have write permissions or capabilities and therefore
-cannot create a lock. Examples are repositories stored on a Bluray disc or a
-read-only network storage. Avoid this option if you are able to use locks as
-that is the safer way; see the warning below.
-
-.. warning::
-
-    If you do use ``--bypass-lock``, you are responsible to ensure that no other
-    borg instances have write access to the repository. Otherwise, you might
-    experience errors and read broken data if changes to that repository are
-    being made at the same time.
-
 Option ``--help`` when used as a command works as expected on subcommands (e.g., ``borg help compact``).
 But it does not work when the help command is being used on sub-sub-commands (e.g., ``borg help key export``).
 The workaround for this to use the help command as a flag (e.g., ``borg key export --help``).

scripts/shell_completions/bash/borg

@@ -12,7 +12,7 @@ _borg()
     local cur="${COMP_WORDS[COMP_CWORD]}"
     local prev="${COMP_WORDS[COMP_CWORD-1]}"
     local prevprev="${COMP_WORDS[COMP_CWORD-2]}"
-    local common_opts="-h --help --critical --error --warning --info -v --verbose --debug --debug-topic -p --progress --iec --log-json --lock-wait --bypass-lock --show-version --show-rc --umask --remote-path --upload-ratelimit --upload-buffer --consider-part-files --debug-profile --rsh -r --repo"
+    local common_opts="-h --help --critical --error --warning --info -v --verbose --debug --debug-topic -p --progress --iec --log-json --lock-wait --show-version --show-rc --umask --remote-path --upload-ratelimit --upload-buffer --consider-part-files --debug-profile --rsh -r --repo"
     local opts="${common_opts}"
 
     # Commands

scripts/shell_completions/zsh/_borg

@@ -656,7 +656,6 @@ __borg_setup_common_options() {
     '(-p --progress)'{-p,--progress}'[show progress information]'
     '--log-json[Output one JSON object per log line instead of formatted text.]'
     '--lock-wait=[wait at most SECONDS for acquiring a repository/cache lock (default: 1)]: : _borg_guard_unsigned_number "SECONDS"'
-    '--bypass-lock[bypass locking mechanism]'
     '(- :)--show-version[show/log the borg version]'
     '--show-rc[show/log the return code (rc)]'
     '--umask=[set umask to M (local only, default: 0077)]:M'

src/borg/archiver/help_cmd.py

@@ -417,7 +417,8 @@ class HelpMixIn:
             The heuristic tries with lz4 whether the data is compressible.
             For incompressible data, it will not use compression (uses "none").
             For compressible data, it uses the given C[,L] compression - with C[,L]
-            being any valid compression specifier.
+            being any valid compression specifier. This can be helpful for media files
+            which often cannot be compressed much more.
 
         obfuscate,SPEC,C[,L]
             Use compressed-size obfuscation to make fingerprinting attacks based on