From 411f6f3222c6ce16e06ed25d6508fef1cdd44b23 Mon Sep 17 00:00:00 2001 From: Martin Richtarsky Date: Tue, 22 Oct 2024 08:25:43 +0200 Subject: [PATCH 1/2] docs: Remove --bypass-lock --- docs/misc/asciinema/basic.json | 5 +---- docs/usage/general.rst | 14 -------------- scripts/shell_completions/bash/borg | 2 +- scripts/shell_completions/zsh/_borg | 1 - 4 files changed, 2 insertions(+), 20 deletions(-) diff --git a/docs/misc/asciinema/basic.json b/docs/misc/asciinema/basic.json index e6ae2e18b..1c280a0e4 100644 --- a/docs/misc/asciinema/basic.json +++ b/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"] diff --git a/docs/usage/general.rst b/docs/usage/general.rst index 630a13342..8d9e559f1 100644 --- a/docs/usage/general.rst +++ b/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``). diff --git a/scripts/shell_completions/bash/borg b/scripts/shell_completions/bash/borg index 255bae353..db17fd9af 100644 --- a/scripts/shell_completions/bash/borg +++ b/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 diff --git a/scripts/shell_completions/zsh/_borg b/scripts/shell_completions/zsh/_borg index 8d9a70399..d38883fc7 100644 --- a/scripts/shell_completions/zsh/_borg +++ b/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' From f656f6b1f24272c7eedf052984126c86e76eac73 Mon Sep 17 00:00:00 2001 From: Martin Richtarsky Date: Tue, 22 Oct 2024 08:26:14 +0200 Subject: [PATCH 2/2] docs: Small changes regarding compression - Mention zstd as the best general choice when not using lz4 (as often acknowledged by public benchmarks) - Mention 'auto' more prominently as a good heuristic to improve speed while retaining good compression - Link to compression options --- docs/quickstart.rst | 34 ++++++++++++++-------------------- src/borg/archiver/help_cmd.py | 3 ++- 2 files changed, 16 insertions(+), 21 deletions(-) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 47c493fc0..f66ea7601 100644 --- a/docs/quickstart.rst +++ b/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. diff --git a/src/borg/archiver/help_cmd.py b/src/borg/archiver/help_cmd.py index 82adc9b85..5f3b1d0b2 100644 --- a/src/borg/archiver/help_cmd.py +++ b/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