Repository: borgbackup/borg

Issue:
better document borg check --max-duration
Copied from the alpha testing ticket:

Regarding --max-duration:

It is mentioned in "borg check" with one sentence: "do only a partial repo check for max. SECONDS seconds (Default: unlimited)".

There is no further explaination why and when this option could be used. I assume that instead of one full long-running check Borg can run multiple partial checks that last --max-duration until the whole repo is checked. But this fact doesn't seem to be expressed with this clarity in the docs. It should be mentioned in borg check.



Discussion:
I could work on this issue; I'd add a little section that explains a check could run for many hours, so --max-duration would stop a check and next check would continue where it stopped.
You could also mention that if one did checks with --m-d and then does a check without --m-d, it will forget how far it got already and just do a full check.
In case you add an example, use `--max-duration=3600` to indicate a maybe practical testing duration (super short durations are rather bad and super long might be pointless - of course it depends on how long a full check would run).

The docs also could contain the idea that a 3.3% of total check time value done daily would mean approx 1 full check being done per month. Or 14% meaning approx. one full check per week.

Also document worthy: if a check is done with --max-duration, it can do way less checks than without, it is currently **only** doing the crc32 check on the segment file entries, nothing more. So it would likely find corruption in segment files, but e.g. not discrepancies between segment files and repo index files.


> Also document worthy: if a check is done with --max-duration, it can do way less checks than without, it is currently **only** doing the crc32 check on the segment file entries, nothing more.

So if a check with --m-d would check the whole repo (because it is small and checking finishes before timeout) this is still not the same as a full check without this option?
No, currently not. And although it might be possible to check for that, it would make the behavior even more complex and also the docs, so maybe we just don't do that.

I guess if people have small enough repos and no timing problem (like "the night only has 10h, not enough for backups + check"), they don't need to and won't use --m-d.
> I guess if people have small enough repos and no timing problem (like "the night only has 10h, not enough for backups + check"), they don't need to and won't use --m-d.

Here's what happened to me in the last few days: I'm running multiple backup jobs one after another using one script including the checks `repository` and `archive` for each. That fit into my time windows for the last few months, but didn't anymore two days ago. Reason was that I'm backing up to some NAS-like device hosted by my provider, which doesn't guarantee any performance. That seemed to have work most of the time and for some reason failed two days ago for whatever reason.

`--max-duration` sounded like a perfect solution for this problem: Either things work or they don't, but are continued the next days and most likely finish at some point again. While all backups run one after another using the same script, each individual backup is implemented using BORGMATIC with its individual config file. That way I could easily define either the same `--max-duration` for each backup or individually optimized ones depending on repo size or alike.

Though, I'm having trouble in understanding the docs about which checks are actually performed when using `--max-duration`. The following two sentences seem to contradict each other:

> Example: Assuming a full check took 7 hours, then running a daily check with –max-duration=3600 (1 hour) resulted in one full check per week.

> Attention: Partial checks can only do way less checking than a full check[...]

As you said here, with `max-duration` one doesn't ever get a full check at all. So the example should be rephrased to make more clear that different checks are executed at all. Additionally, the terms `full check` and `partial check` don't seem to be explained in the docs. E.g., is `full check` running `--verify-data` or ` repository` and `archives` without `--verify-data` already? In the former case I could easily use `--max-duration`, because I don't use that. But I'm using `repository` and `archives` and if `--max-duration` reduces some operation of those, it would be good to know which.

Thanks!

Resolving patch:
diff --git a/src/borg/archiver.py b/src/borg/archiver.py
--- a/src/borg/archiver.py
+++ b/src/borg/archiver.py
@@ -3362,15 +3362,18 @@ def define_borg_mount(parser):
         The ``--max-duration`` option can be used to split a long-running repository check
         into multiple partial checks. After the given number of seconds the check is
         interrupted. The next partial check will continue where the previous one stopped,
-        until the complete repository has been checked. Example: Assuming a full check took 7
+        until the complete repository has been checked. Example: Assuming a complete check took 7
         hours, then running a daily check with --max-duration=3600 (1 hour) resulted in one
-        full check per week.
-
-        Attention: Partial checks can only do way less checking than a full check (only the
-        CRC32 checks on segment file entries are done), and cannot be combined with the
-        ``--repair`` option. Partial checks may therefore be useful only with very large
-        repositories where a full check took too long. Doing a full repository check aborts a
-        partial check; the next partial check will restart from the beginning.
+        completed check per week.
+
+        Attention: A partial --repository-only check can only do way less checking than a full
+        --repository-only check: only the non-cryptographic checksum checks on segment file
+        entries are done, while a full --repository-only check would also do a repo index check.
+        A partial check cannot be combined with the ``--repair`` option. Partial checks
+        may therefore be useful only with very large repositories where a full check would take
+        too long.
+        Doing a full repository check aborts a partial check; the next partial check will restart
+        from the beginning.
 
         The ``--verify-data`` option will perform a full integrity verification (as opposed to
         checking the CRC32 of the segment) of data, which means reading the data from the


Test patch: