From 78c7aabbb679935ca3e8001ad8f281b6ad347fdd Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Sun, 8 Sep 2024 17:18:53 +0200 Subject: [PATCH] docs: fix usage docs and references for repo-* commands --- docs/faq.rst | 2 +- docs/internals/data-structures.rst | 2 +- docs/internals/frontends.rst | 4 ++-- docs/internals/security.rst | 2 +- docs/quickstart.rst | 2 +- docs/usage.rst | 12 ++++++------ docs/usage/general.rst | 2 +- docs/usage/prune.rst.inc | 2 +- .../usage/{rcompress.rst => repo-compress.rst} | 2 +- ...rcompress.rst.inc => repo-compress.rst.inc} | 14 +++++++------- docs/usage/{rcreate.rst => repo-create.rst} | 4 ++-- .../{rcreate.rst.inc => repo-create.rst.inc} | 14 +++++++------- docs/usage/{rdelete.rst => repo-delete.rst} | 2 +- .../{rdelete.rst.inc => repo-delete.rst.inc} | 8 ++++---- docs/usage/{rinfo.rst => repo-info.rst} | 2 +- .../usage/{rinfo.rst.inc => repo-info.rst.inc} | 8 ++++---- docs/usage/{rlist.rst => repo-list.rst} | 2 +- .../usage/{rlist.rst.inc => repo-list.rst.inc} | 12 ++++++------ docs/usage/repo-space.rst | 1 + .../{rspace.rst.inc => repo-space.rst.inc} | 18 +++++++++--------- docs/usage/rspace.rst | 1 - docs/usage/transfer.rst.inc | 4 ++-- 22 files changed, 60 insertions(+), 60 deletions(-) rename docs/usage/{rcompress.rst => repo-compress.rst} (86%) rename docs/usage/{rcompress.rst.inc => repo-compress.rst.inc} (93%) rename docs/usage/{rcreate.rst => repo-create.rst} (94%) rename docs/usage/{rcreate.rst.inc => repo-create.rst.inc} (97%) rename docs/usage/{rdelete.rst => repo-delete.rst} (93%) rename docs/usage/{rdelete.rst.inc => repo-delete.rst.inc} (97%) rename docs/usage/{rinfo.rst => repo-info.rst} (94%) rename docs/usage/{rinfo.rst.inc => repo-info.rst.inc} (93%) rename docs/usage/{rlist.rst => repo-list.rst} (91%) rename docs/usage/{rlist.rst.inc => repo-list.rst.inc} (98%) create mode 100644 docs/usage/repo-space.rst rename docs/usage/{rspace.rst.inc => repo-space.rst.inc} (91%) delete mode 100644 docs/usage/rspace.rst diff --git a/docs/faq.rst b/docs/faq.rst index 26bb99909..ee6476bb4 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -33,7 +33,7 @@ Can I back up to multiple, swapped backup targets? -------------------------------------------------- It is possible to swap your backup disks if each backup medium is assigned its -own repository by creating a new one with :ref:`borg_rcreate`. +own repository by creating a new one with :ref:`borg_repo-create`. Can I copy or synchronize my repo to another location? ------------------------------------------------------ diff --git a/docs/internals/data-structures.rst b/docs/internals/data-structures.rst index 45de9ee34..df80a57e7 100644 --- a/docs/internals/data-structures.rst +++ b/docs/internals/data-structures.rst @@ -67,7 +67,7 @@ byte-strings of fixed length (256bit, 32 bytes), computed like this:: key = id = id_hash(plaintext_data) # plain = not encrypted, not compressed, not obfuscated -The id_hash function depends on the :ref:`encryption mode `. +The id_hash function depends on the :ref:`encryption mode `. As the id / key is used for deduplication, id_hash must be a cryptographically strong hash or MAC. diff --git a/docs/internals/frontends.rst b/docs/internals/frontends.rst index 08e2f4f4a..8b9b7faa3 100644 --- a/docs/internals/frontends.rst +++ b/docs/internals/frontends.rst @@ -255,7 +255,7 @@ Passphrase prompts should be handled differently. Use the environment variables and *BORG_NEW_PASSPHRASE* (see :ref:`env_vars` for reference) to pass passphrases to Borg, don't use the interactive passphrase prompts. -When setting a new passphrase (:ref:`borg_rcreate`, :ref:`borg_key_change-passphrase`) normally +When setting a new passphrase (:ref:`borg_repo-create`, :ref:`borg_key_change-passphrase`) normally Borg prompts whether it should display the passphrase. This can be suppressed by setting the environment variable *BORG_DISPLAY_PASSPHRASE* to *no*. @@ -299,7 +299,7 @@ last_modified The *encryption* key, if present, contains: mode - Textual encryption mode name (same as :ref:`borg_rcreate` ``--encryption`` names) + Textual encryption mode name (same as :ref:`borg_repo-create` ``--encryption`` names) keyfile Path to the local key file used for access. Depending on *mode* this key may be absent. diff --git a/docs/internals/security.rst b/docs/internals/security.rst index aada49e3f..40b27d797 100644 --- a/docs/internals/security.rst +++ b/docs/internals/security.rst @@ -123,7 +123,7 @@ Supported: borg 2.0+ Encryption with these modes is based on AEAD ciphers (authenticated encryption with associated data) and session keys. -Depending on the chosen mode (see :ref:`borg_rcreate`) different AEAD ciphers are used: +Depending on the chosen mode (see :ref:`borg_repo-create`) different AEAD ciphers are used: - AES-256-OCB - super fast, single-pass algorithm IF you have hw accelerated AES. - chacha20-poly1305 - very fast, purely software based AEAD cipher. diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 6aaef7d1a..88f867c22 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -335,7 +335,7 @@ You can choose the repository encryption mode at repository creation time:: $ borg repo-create --encryption=MODE For a list of available encryption MODEs and their descriptions, please refer -to :ref:`borg_rcreate`. +to :ref:`borg_repo-create`. If you use encryption, all data is encrypted on the client before being written to the repository. diff --git a/docs/usage.rst b/docs/usage.rst index d88f968ea..7b6cbbb10 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -36,12 +36,12 @@ Usage .. toctree:: usage/general - usage/rcreate - usage/rspace - usage/rlist - usage/rinfo - usage/rcompress - usage/rdelete + usage/repo-create + usage/repo-space + usage/repo-list + usage/repo-info + usage/repo-compress + usage/repo-delete usage/serve usage/version usage/compact diff --git a/docs/usage/general.rst b/docs/usage/general.rst index 16be87f62..630a13342 100644 --- a/docs/usage/general.rst +++ b/docs/usage/general.rst @@ -7,7 +7,7 @@ The following sections will describe each command in detail. Commands, options, parameters, paths and such are ``set in fixed-width``. Option values are `underlined`. Borg has few options accepting a fixed set -of values (e.g. ``--encryption`` of :ref:`borg_rcreate`). +of values (e.g. ``--encryption`` of :ref:`borg_repo-create`). .. container:: experimental diff --git a/docs/usage/prune.rst.inc b/docs/usage/prune.rst.inc index dfa46e1cc..e3f85eaa1 100644 --- a/docs/usage/prune.rst.inc +++ b/docs/usage/prune.rst.inc @@ -150,4 +150,4 @@ backup archive in the same second). You can influence how the ``--list`` output is formatted by using the ``--short`` option (less wide output) or by giving a custom format using ``--format`` (see -the ``borg rlist`` description for more details about the format string). \ No newline at end of file +the ``borg repo-list`` description for more details about the format string). \ No newline at end of file diff --git a/docs/usage/rcompress.rst b/docs/usage/repo-compress.rst similarity index 86% rename from docs/usage/rcompress.rst rename to docs/usage/repo-compress.rst index 1d02b28e7..aff6adc30 100644 --- a/docs/usage/rcompress.rst +++ b/docs/usage/repo-compress.rst @@ -1,4 +1,4 @@ -.. include:: rcompress.rst.inc +.. include:: repo-compress.rst.inc Examples ~~~~~~~~ diff --git a/docs/usage/rcompress.rst.inc b/docs/usage/repo-compress.rst.inc similarity index 93% rename from docs/usage/rcompress.rst.inc rename to docs/usage/repo-compress.rst.inc index 9d3861895..786e8c25c 100644 --- a/docs/usage/rcompress.rst.inc +++ b/docs/usage/repo-compress.rst.inc @@ -1,12 +1,12 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! -.. _borg_rcompress: +.. _borg_repo-compress: -borg rcompress --------------- +borg repo-compress +------------------ .. code-block:: none - borg [common options] rcompress [options] + borg [common options] repo-compress [options] .. only:: html @@ -60,10 +60,10 @@ type/level - if no compression gives a shorter output, that might be chosen. 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 repo-compress`` 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`` +Both ``--progress`` and ``--stats`` are recommended when ``borg repo-compress`` is used interactively. -You do **not** need to run ``borg compact`` after ``borg rcompress``. \ No newline at end of file +You do **not** need to run ``borg compact`` after ``borg repo-compress``. \ No newline at end of file diff --git a/docs/usage/rcreate.rst b/docs/usage/repo-create.rst similarity index 94% rename from docs/usage/rcreate.rst rename to docs/usage/repo-create.rst index 5b6d5fa1d..87fc1c24f 100644 --- a/docs/usage/rcreate.rst +++ b/docs/usage/repo-create.rst @@ -1,6 +1,6 @@ -.. _borg-rcreate: +.. _borg_repo_create: -.. include:: rcreate.rst.inc +.. include:: repo-create.rst.inc Examples ~~~~~~~~ diff --git a/docs/usage/rcreate.rst.inc b/docs/usage/repo-create.rst.inc similarity index 97% rename from docs/usage/rcreate.rst.inc rename to docs/usage/repo-create.rst.inc index b61acd497..a251c2439 100644 --- a/docs/usage/rcreate.rst.inc +++ b/docs/usage/repo-create.rst.inc @@ -1,12 +1,12 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! -.. _borg_rcreate: +.. _borg_repo-create: -borg rcreate ------------- +borg repo-create +---------------- .. code-block:: none - borg [common options] rcreate [options] + borg [common options] repo-create [options] .. only:: html @@ -75,7 +75,7 @@ tips will come below): :: - borg rcreate --encryption repokey-aes-ocb + borg repo-create --encryption repokey-aes-ocb Borg will: @@ -166,7 +166,7 @@ there is an emergency workaround, see ``BORG_WORKAROUNDS=authenticated_no_key`` Creating a related repository +++++++++++++++++++++++++++++ -You can use ``borg rcreate --other-repo ORIG_REPO ...`` to create a related repository +You can use ``borg repo-create --other-repo ORIG_REPO ...`` to create a related repository that uses the same secret key material as the given other/original repository. By default, only the ID key and chunker secret will be the same (these are important @@ -181,7 +181,7 @@ Creating related repositories is useful e.g. if you want to use ``borg transfer` Creating a related repository for data migration from borg 1.2 or 1.4 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -You can use ``borg rcreate --other-repo ORIG_REPO --from-borg1 ...`` to create a related +You can use ``borg repo-create --other-repo ORIG_REPO --from-borg1 ...`` to create a related repository that uses the same secret key material as the given other/original repository. Then use ``borg transfer --other-repo ORIG_REPO --from-borg1 ...`` to transfer the archives. \ No newline at end of file diff --git a/docs/usage/rdelete.rst b/docs/usage/repo-delete.rst similarity index 93% rename from docs/usage/rdelete.rst rename to docs/usage/repo-delete.rst index c0c233738..92be6be9a 100644 --- a/docs/usage/rdelete.rst +++ b/docs/usage/repo-delete.rst @@ -1,4 +1,4 @@ -.. include:: rdelete.rst.inc +.. include:: repo-delete.rst.inc Examples ~~~~~~~~ diff --git a/docs/usage/rdelete.rst.inc b/docs/usage/repo-delete.rst.inc similarity index 97% rename from docs/usage/rdelete.rst.inc rename to docs/usage/repo-delete.rst.inc index 18d9bbc01..724911bb7 100644 --- a/docs/usage/rdelete.rst.inc +++ b/docs/usage/repo-delete.rst.inc @@ -1,12 +1,12 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! -.. _borg_rdelete: +.. _borg_repo-delete: -borg rdelete ------------- +borg repo-delete +---------------- .. code-block:: none - borg [common options] rdelete [options] + borg [common options] repo-delete [options] .. only:: html diff --git a/docs/usage/rinfo.rst b/docs/usage/repo-info.rst similarity index 94% rename from docs/usage/rinfo.rst rename to docs/usage/repo-info.rst index 7fa0726f4..00a158930 100644 --- a/docs/usage/rinfo.rst +++ b/docs/usage/repo-info.rst @@ -1,4 +1,4 @@ -.. include:: rinfo.rst.inc +.. include:: repo-info.rst.inc Examples ~~~~~~~~ diff --git a/docs/usage/rinfo.rst.inc b/docs/usage/repo-info.rst.inc similarity index 93% rename from docs/usage/rinfo.rst.inc rename to docs/usage/repo-info.rst.inc index 098a7c7ea..32dc16d93 100644 --- a/docs/usage/rinfo.rst.inc +++ b/docs/usage/repo-info.rst.inc @@ -1,12 +1,12 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! -.. _borg_rinfo: +.. _borg_repo-info: -borg rinfo ----------- +borg repo-info +-------------- .. code-block:: none - borg [common options] rinfo [options] + borg [common options] repo-info [options] .. only:: html diff --git a/docs/usage/rlist.rst b/docs/usage/repo-list.rst similarity index 91% rename from docs/usage/rlist.rst rename to docs/usage/repo-list.rst index 7df1f1401..00f925908 100644 --- a/docs/usage/rlist.rst +++ b/docs/usage/repo-list.rst @@ -1,4 +1,4 @@ -.. include:: rlist.rst.inc +.. include:: repo-list.rst.inc Examples ~~~~~~~~ diff --git a/docs/usage/rlist.rst.inc b/docs/usage/repo-list.rst.inc similarity index 98% rename from docs/usage/rlist.rst.inc rename to docs/usage/repo-list.rst.inc index d96d1df71..c8fe41f51 100644 --- a/docs/usage/rlist.rst.inc +++ b/docs/usage/repo-list.rst.inc @@ -1,12 +1,12 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! -.. _borg_rlist: +.. _borg_repo-list: -borg rlist ----------- +borg repo-list +-------------- .. code-block:: none - borg [common options] rlist [options] + borg [common options] repo-list [options] .. only:: html @@ -92,7 +92,7 @@ The ``--format`` option uses python's `format string syntax Examples: :: - $ borg rlist --format '{archive}{NL}' + $ borg repo-list --format '{archive}{NL}' ArchiveFoo ArchiveBar ... @@ -100,7 +100,7 @@ Examples: # {VAR:NUMBER} - pad to NUMBER columns. # Strings are left-aligned, numbers are right-aligned. # Note: time columns except ``isomtime``, ``isoctime`` and ``isoatime`` cannot be padded. - $ borg rlist --format '{archive:36} {time} [{id}]{NL}' /path/to/repo + $ borg repo-list --format '{archive:36} {time} [{id}]{NL}' /path/to/repo ArchiveFoo Thu, 2021-12-09 10:22:28 [0b8e9...3b274] ... diff --git a/docs/usage/repo-space.rst b/docs/usage/repo-space.rst new file mode 100644 index 000000000..ceba77572 --- /dev/null +++ b/docs/usage/repo-space.rst @@ -0,0 +1 @@ +.. include:: repo-space.rst.inc diff --git a/docs/usage/rspace.rst.inc b/docs/usage/repo-space.rst.inc similarity index 91% rename from docs/usage/rspace.rst.inc rename to docs/usage/repo-space.rst.inc index 28e8ce62a..e139c6610 100644 --- a/docs/usage/rspace.rst.inc +++ b/docs/usage/repo-space.rst.inc @@ -1,12 +1,12 @@ .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit! -.. _borg_rspace: +.. _borg_repo-space: -borg rspace ------------ +borg repo-space +--------------- .. code-block:: none - borg [common options] rspace [options] + borg [common options] repo-space [options] .. only:: html @@ -62,19 +62,19 @@ situation again at a later time. Examples:: # Create a new repository: - $ borg rcreate ... + $ borg repo-create ... # Reserve approx. 1GB of space for emergencies: - $ borg rspace --reserve 1G + $ borg repo-space --reserve 1G # Check amount of reserved space in the repository: - $ borg rspace + $ borg repo-space # EMERGENCY! Free all reserved space to get things back to normal: - $ borg rspace --free + $ borg repo-space --free $ borg prune ... $ borg delete ... $ borg compact -v # only this actually frees space of deleted archives - $ borg rspace --reserve 1G # reserve space again for next time + $ borg repo-space --reserve 1G # reserve space again for next time Reserved space is always rounded up to use full reservation blocks of 64MiB. \ No newline at end of file diff --git a/docs/usage/rspace.rst b/docs/usage/rspace.rst deleted file mode 100644 index 0913340fd..000000000 --- a/docs/usage/rspace.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: rspace.rst.inc diff --git a/docs/usage/transfer.rst.inc b/docs/usage/transfer.rst.inc index 5b6d45335..ff2b90f24 100644 --- a/docs/usage/transfer.rst.inc +++ b/docs/usage/transfer.rst.inc @@ -112,7 +112,7 @@ Transfer borg2 archives into a related other borg2 repository:: # create a related DST_REPO (reusing key material from SRC_REPO), so that # chunking and chunk id generation will work in the same way as before. - borg --repo=DST_REPO rcreate --encryption=DST_ENC --other-repo=SRC_REPO + borg --repo=DST_REPO repo-create --encryption=DST_ENC --other-repo=SRC_REPO # transfer archives from SRC_REPO to DST_REPO borg --repo=DST_REPO transfer --other-repo=SRC_REPO --dry-run # check what it would do @@ -126,7 +126,7 @@ Data migration / upgrade from borg 1.x To migrate your borg 1.x archives into a related, new borg2 repository, usage is quite similar to the above, but you need the ``--from-borg1`` option:: - borg --repo=DST_REPO rcreate --encryption=DST_ENC --other-repo=SRC_REPO --from-borg1 + borg --repo=DST_REPO repocreate --encryption=DST_ENC --other-repo=SRC_REPO --from-borg1 # to continue using lz4 compression as you did in SRC_REPO: borg --repo=DST_REPO transfer --other-repo=SRC_REPO --from-borg1 \