From 5d8d21df4d9260f42bb0f986a78ced6d871c2dd5 Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sun, 2 Oct 2022 15:39:10 +0200 Subject: [PATCH] rcompress docs / examples / markup fixes --- docs/usage/rcompress.rst | 12 +++++ docs/usage/rcompress.rst.inc | 78 ++++++++++++++++++++++++++++++ src/borg/archiver/help_cmd.py | 1 + src/borg/archiver/rcompress_cmd.py | 2 +- 4 files changed, 92 insertions(+), 1 deletion(-) create mode 100644 docs/usage/rcompress.rst create mode 100644 docs/usage/rcompress.rst.inc diff --git a/docs/usage/rcompress.rst b/docs/usage/rcompress.rst new file mode 100644 index 00000000..044f065a --- /dev/null +++ b/docs/usage/rcompress.rst @@ -0,0 +1,12 @@ +.. include:: rcompress.rst.inc + +Examples +~~~~~~~~ + +:: + + # recompress repo contents + $ borg rcompress --progress --compression=zstd,3 + + # recompress and obfuscate repo contents + $ borg rcompress --progress --compression=obfuscate,1,zstd,3 diff --git a/docs/usage/rcompress.rst.inc b/docs/usage/rcompress.rst.inc new file mode 100644 index 00000000..702536b8 --- /dev/null +++ b/docs/usage/rcompress.rst.inc @@ -0,0 +1,78 @@ +.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! + +.. _borg_rcompress: + +borg rcompress +-------------- +.. code-block:: none + + borg [common options] rcompress [options] + +.. only:: html + + .. class:: borg-options-table + + +-------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | **optional arguments** | + +-------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. | + +-------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | | ``-s``, ``--stats`` | print statistics | + +-------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) | + +-------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ + | .. class:: borg-common-opt-ref | + | | + | :ref:`common_options` | + +-------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+ + + .. raw:: html + + + +.. only:: latex + + + + optional arguments + -C COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details. + -s, --stats print statistics + -c SECONDS, --checkpoint-interval SECONDS write checkpoint every SECONDS seconds (Default: 1800) + + + :ref:`common_options` + | + +Description +~~~~~~~~~~~ + +Repository (re-)compression (and/or re-obfuscation). + +Reads all chunks in the repository (in on-disk order, this is important for +compaction) and recompresses them if they are not already using the compression +type/level and obfuscation level given via ``--compression``. + +If the outcome of the chunk processing indicates a change in compression +type/level or obfuscation level, the processed chunk is written to the repository. +Please note that the outcome might not always be the desired compression +type/level - if no compression gives a shorter output, that might be chosen. + +Every ``--checkpoint-interval``, progress is committed to the repository and +the repository is compacted (this is to keep temporary repo space usage in bounds). +A lower checkpoint interval means lower temporary repo space usage, but also +slower progress due to higher overhead (and vice versa). + +Please note that this command can not work in low (or zero) free disk space +conditions. + +If the ``borg rcompress``process receives a SIGINT signal (Ctrl-C), the repo +will be committed and compacted and borg will terminate cleanly afterwards. + +Both ``--progress`` and ``--stats`` are recommended when ``borg rcompress`` +is used interactively. + +You do **not** need to run ``borg compact`` after ``borg rcompress``. \ No newline at end of file diff --git a/src/borg/archiver/help_cmd.py b/src/borg/archiver/help_cmd.py index 0970d140..aace6c20 100644 --- a/src/borg/archiver/help_cmd.py +++ b/src/borg/archiver/help_cmd.py @@ -262,6 +262,7 @@ class HelpMixIn: This is very powerful, but can also get rather complicated. Examples:: + # id: style borg delete --match-archives 'id:archive-with-crap' borg delete -a 'id:archive-with-crap' # same, using short option diff --git a/src/borg/archiver/rcompress_cmd.py b/src/borg/archiver/rcompress_cmd.py index ff43193c..adc14a6f 100644 --- a/src/borg/archiver/rcompress_cmd.py +++ b/src/borg/archiver/rcompress_cmd.py @@ -203,7 +203,7 @@ class RCompressMixIn: Please note that this command can not work in low (or zero) free disk space conditions. - If the ``borg rcompress``process receives a SIGINT signal (Ctrl-C), the repo + If the ``borg rcompress`` process receives a SIGINT signal (Ctrl-C), the repo will be committed and compacted and borg will terminate cleanly afterwards. Both ``--progress`` and ``--stats`` are recommended when ``borg rcompress``