From c7d637ec39c1e9affd5406fb60677824daeb73e9 Mon Sep 17 00:00:00 2001 From: "Leo R. Lundgren" Date: Fri, 25 Mar 2022 21:40:07 +0100 Subject: [PATCH] check: Adjust help and documentation for check --read-data-subset --- changelog/unreleased/issue-3490 | 11 +++++---- cmd/restic/cmd_check.go | 8 +++---- doc/045_working_with_repos.rst | 40 ++++++++++++++++----------------- 3 files changed, 29 insertions(+), 30 deletions(-) diff --git a/changelog/unreleased/issue-3490 b/changelog/unreleased/issue-3490 index e5ce23d1d..6880c8835 100644 --- a/changelog/unreleased/issue-3490 +++ b/changelog/unreleased/issue-3490 @@ -1,9 +1,8 @@ -Enhancement: Support for specifying file size in `check --read-data-subset` +Enhancement: Support random subset by size in `check --read-data-subset` -To check a subset of repository files, the `check --read-data-subset` command -used to support two ways to select a subset - A specific range of pack files, -or random percentage of pack files. We have added a third method to select pack -files - By specifying file size. This new option is available with the 'restic check' command. +The `--read-data-subset` option of the `check` command now supports a third way +of specifying the subset to check, namely `nS` where `n` is a size in bytes with +suffix `S` as k/K, m/M, g/G or t/T. https://github.com/restic/restic/issues/3490 -https://github.com/restic/restic/pull/3548 \ No newline at end of file +https://github.com/restic/restic/pull/3548 diff --git a/cmd/restic/cmd_check.go b/cmd/restic/cmd_check.go index 6d50dc96b..fa71bdba8 100644 --- a/cmd/restic/cmd_check.go +++ b/cmd/restic/cmd_check.go @@ -56,7 +56,7 @@ func init() { f := cmdCheck.Flags() f.BoolVar(&checkOptions.ReadData, "read-data", false, "read all data blobs") - f.StringVar(&checkOptions.ReadDataSubset, "read-data-subset", "", "read a `subset` of data packs, specified as 'n/t' for specific subset or either 'x%' or 'x.y%' for random subset") + f.StringVar(&checkOptions.ReadDataSubset, "read-data-subset", "", "read a `subset` of data packs, specified as 'n/t' for specific part, or either 'x%' or 'x.y%' or a size in bytes with suffixes k/K, m/M, g/G, t/T for a random subset") f.BoolVar(&checkOptions.CheckUnused, "check-unused", false, "find unused blobs") f.BoolVar(&checkOptions.WithCache, "with-cache", false, "use the cache") } @@ -67,7 +67,7 @@ func checkFlags(opts CheckOptions) error { } if opts.ReadDataSubset != "" { dataSubset, err := stringToIntSlice(opts.ReadDataSubset) - argumentError := errors.Fatal("check flag --read-data-subset must have two positive integer values or a percentage or a file size, e.g. --read-data-subset=1/2 or --read-data-subset=2.5%% or --read-data-subset=10G") + argumentError := errors.Fatal("check flag --read-data-subset has invalid value, please see documentation") if err == nil { if len(dataSubset) != 2 { return argumentError @@ -86,7 +86,7 @@ func checkFlags(opts CheckOptions) error { if percentage <= 0.0 || percentage > 100.0 { return errors.Fatal( - "check flag --read-data-subset=n% n must be above 0.0% and at most 100.0%") + "check flag --read-data-subset=x% x must be above 0.0% and at most 100.0%") } } else { @@ -96,7 +96,7 @@ func checkFlags(opts CheckOptions) error { } if fileSize <= 0.0 { return errors.Fatal( - "check flag --read-data-subset=n n must be above 0.0") + "check flag --read-data-subset=n n must be above 0") } } diff --git a/doc/045_working_with_repos.rst b/doc/045_working_with_repos.rst index b21d198b9..8ba154f30 100644 --- a/doc/045_working_with_repos.rst +++ b/doc/045_working_with_repos.rst @@ -248,12 +248,12 @@ integrity of the pack files in the repository, use the ``--read-data`` flag: repository, beware that it might incur higher bandwidth costs than usual and also that it takes more time than the default ``check``. -Alternatively, use the ``--read-data-subset`` parameter to check only a -subset of the repository pack files at a time. It supports three ways to select a -subset. One selects a specific range of pack files, the second selects a random -percentage of pack files, and the third selects pack files of the specified size. +Alternatively, use the ``--read-data-subset`` parameter to check only a subset +of the repository pack files at a time. It supports three ways to select a +subset. One selects a specific part of pack files, the second and third +selects a random subset of the pack files by the given percentage or size. -Use ``--read-data-subset=n/t`` to check only a subset of the repository pack +Use ``--read-data-subset=n/t`` to check a specific part of the repository pack files at a time. The parameter takes two values, ``n`` and ``t``. When the check command runs, all pack files in the repository are logically divided in ``t`` (roughly equal) groups, and only files that belong to group number ``n`` are @@ -268,33 +268,33 @@ over 5 separate invocations: $ restic -r /srv/restic-repo check --read-data-subset=4/5 $ restic -r /srv/restic-repo check --read-data-subset=5/5 -Use ``--read-data-subset=n%`` to check a randomly choosen subset of the -repository pack files. It takes one parameter, ``n``, the percentage of pack -files to check as an integer or floating point number. This will not guarantee -to cover all available pack files after sufficient runs, but it is easy to -automate checking a small subset of data after each backup. For a floating point -value the following command may be used: +Use ``--read-data-subset=x%`` to check a randomly choosen subset of the +repository pack files. It takes one parameter, ``x``, the percentage of +pack files to check as an integer or floating point number. This will not +guarantee to cover all available pack files after sufficient runs, but it is +easy to automate checking a small subset of data after each backup. For a +floating point value the following command may be used: .. code-block:: console $ restic -r /srv/restic-repo check --read-data-subset=2.5% -When checking bigger subsets you most likely specify the percentage as an -integer: +When checking bigger subsets you most likely want to specify the percentage +as an integer: .. code-block:: console $ restic -r /srv/restic-repo check --read-data-subset=10% -Use ``--read-data-subset=NS`` to check a randomly chosen subset of the repository pack files. -It takes one parameter, ``NS``, where 'N' is a whole number representing file size and 'S' is the unit -of file size (B/K/M/G/T) of pack files to check. Behind the scenes, the specified size will be converted -to percentage of the total repository size. The behaviour of the check command following this conversion -will be the same as the percentage option above. For a file size value the following command may be used: +Use ``--read-data-subset=nS`` to check a randomly chosen subset of the +repository pack files. It takes one parameter, ``nS``, where 'n' is a whole +number representing file size and 'S' is the unit of file size (K/M/G/T) of +pack files to check. Behind the scenes, the specified size will be converted +to percentage of the total repository size. The behaviour of the check command +following this conversion will be the same as the percentage option above. For +a file size value the following command may be used: .. code-block:: console $ restic -r /srv/restic-repo check --read-data-subset=50M $ restic -r /srv/restic-repo check --read-data-subset=10G - -