From c7053f820281a400b85eea69d13b8637f89f83a5 Mon Sep 17 00:00:00 2001 From: Dan Helfman Date: Mon, 13 Oct 2025 18:14:39 -0700 Subject: [PATCH] Additional documentation reference refactoring (#942). --- ...movable-drive-or-an-intermittent-server.md | 38 +++----------- docs/how-to/develop-on-borgmatic.md | 34 ++----------- docs/how-to/run-arbitrary-borg-commands.md | 13 ++--- docs/reference/configuration/command-hooks.md | 49 +++++++++++++++++++ docs/reference/source-code.md | 31 ++++++++++++ docs/search.md | 2 +- 6 files changed, 97 insertions(+), 70 deletions(-) diff --git a/docs/how-to/backup-to-a-removable-drive-or-an-intermittent-server.md b/docs/how-to/backup-to-a-removable-drive-or-an-intermittent-server.md index 8c601b25..f3def262 100644 --- a/docs/how-to/backup-to-a-removable-drive-or-an-intermittent-server.md +++ b/docs/how-to/backup-to-a-removable-drive-or-an-intermittent-server.md @@ -23,6 +23,9 @@ or an offline server or a low battery—and exit gracefully? That's where the concept of "soft failure" come in. + + + ## Soft failure command hooks This feature leverages [borgmatic command @@ -32,7 +35,7 @@ test in the form of a borgmatic command hook to see if backups should proceed or not. The way the test works is that if any of your hook commands return a special -exit status of 75, that indicates to borgmatic that it's a temporary failure, +exit status of 75, that indicates to borgmatic that it's a temporary failure and borgmatic should skip all subsequent actions for the current repository. If you return any status besides 75, then it's a standard success or error. @@ -114,33 +117,6 @@ commands: Writing the battery script is left as an exercise to the reader. - -## Caveats and details - -There are some caveats you should be aware of with this feature. - - * You'll generally want to put a soft failure command in a `before` command - hook, so as to gate whether the backup action occurs. While a soft failure is - also supported in an `after` command hook, returning a soft failure there - won't prevent any actions from occurring, because they've already occurred! - Similarly, you can return a soft failure from an `error` command hook, but at - that point it's too late to prevent the error. - * Returning a soft failure does prevent further commands in the same hook from - executing. So, like a standard error, it is an "early out." Unlike a standard - error, borgmatic does not display it in angry red text or consider it a - failure. - * New in version 1.9.0 Soft - failures in `action` or `before_*` command hooks only skip the current - repository rather than all repositories in a configuration file. - * If you're writing a soft failure script that you want to vary based on the - current repository, for instance so you can have multiple repositories in a - single configuration file, have a look at [command hook variable - interpolation](https://torsion.org/borgmatic/how-to/add-preparation-and-cleanup-steps-to-backups/#variable-interpolation). - And there's always still the option of putting anything that you don't want - soft-failed (like always-online cloud backups) in separate configuration - files from your soft-failing repositories. - * The soft failure doesn't have to test anything related to a repository. You - can even perform a test that individual source directories are mounted and - available. Use your imagination! - * Soft failures are not currently implemented for `everything`, - `before_everything`, or `after_everything` command hooks. +See the [soft failure +documentation](https://torsion.org/borgmatic/reference/configuration/command-hooks/#soft-failure) +for additional details. diff --git a/docs/how-to/develop-on-borgmatic.md b/docs/how-to/develop-on-borgmatic.md index 442ff32e..a79c4269 100644 --- a/docs/how-to/develop-on-borgmatic.md +++ b/docs/how-to/develop-on-borgmatic.md @@ -111,6 +111,10 @@ them: tox -e spell ``` +See the [code style +documentation](https://torsion.org/borgmatic/reference/source-code/#code-style) +for more specifics about borgmatic's own code style. + ### End-to-end tests @@ -155,36 +159,6 @@ Then you'll be able to run end-to-end tests as per normal, and the test script will automatically use your non-root Podman socket instead of a Docker socket. -## Code style - -When writing code for borgmatic, start with [PEP -8](https://www.python.org/dev/peps/pep-0008/). But then, apply the following -deviations from it: - - * For strings, prefer single quotes over double quotes. - * Limit all lines to a maximum of 100 characters. - * Use trailing commas within multiline values or argument lists. - * For multiline constructs, put opening and closing delimiters on lines - separate from their contents. - * Within multiline constructs, use standard four-space indentation. Don't align - indentation with an opening delimiter. - * In general, spell out words in variable names instead of shortening them. - So, think `index` instead of `idx`. There are some notable exceptions to - this though (like `config`). - * Favor blank lines around logical code groupings, `if` statements, - `return`s, etc. Readability is more important than packing code tightly. - * Import fully qualified Python modules instead of importing individual - functions, classes, or constants. E.g., do `import os.path` instead of - `from os import path`. (Some exceptions to this are made in tests.) - * Only use classes and OOP as a last resort, such as when integrating with - Python libraries that require it. - * Prefer functional code where it makes sense, e.g. when constructing a - command (to subsequently execute imperatively). - -Since borgmatic uses Ruff for code lining and formatting, many other code style -requirements are also enforced when running automated tests. - - ## Continuous integration Each commit to diff --git a/docs/how-to/run-arbitrary-borg-commands.md b/docs/how-to/run-arbitrary-borg-commands.md index 22b05619..dcf5faeb 100644 --- a/docs/how-to/run-arbitrary-borg-commands.md +++ b/docs/how-to/run-arbitrary-borg-commands.md @@ -26,7 +26,7 @@ arguments: * verbosity -### borg action +## borg action New in version 1.5.15 The way you run Borg with borgmatic is via the `borg` action. Here's a simple example: @@ -43,13 +43,10 @@ be preferred though for most uses.) You can also specify Borg options for relevant commands. For instance: ```bash -borgmatic borg repo-list --short +borgmatic borg list --short ``` -(No borgmatic `repo-list` action? Try `rlist` or `list` instead or upgrade -borgmatic!) - -This runs Borg's `repo-list` command once on each configured borgmatic +This runs Borg's `list` command once on each configured borgmatic repository. What if you only want to run Borg on a single configured borgmatic repository @@ -76,7 +73,7 @@ the right place (which didn't always work). So your command-line in these older versions didn't support the `::` -### Specifying an archive +## Specifying an archive For borg commands that expect an archive name, you have a few approaches. Here's one: @@ -117,7 +114,7 @@ borgmatic borg --archive latest list '$ARCHIVE' borgmatic borg list your-actual-archive-name ``` -### Limitations +## Limitations borgmatic's `borg` action is not without limitations: diff --git a/docs/reference/configuration/command-hooks.md b/docs/reference/configuration/command-hooks.md index 1bcaae7b..b1303cbd 100644 --- a/docs/reference/configuration/command-hooks.md +++ b/docs/reference/configuration/command-hooks.md @@ -161,6 +161,55 @@ Note that you can also interpolate [arbitrary environment variables](https://torsion.org/borgmatic/reference/configuration/environment-variables/). +## Soft failure + +If any of your hook commands return a special exit status of 75, that indicates +to borgmatic that it's a temporary failure and borgmatic should skip all +subsequent actions for the current repository. + +If you return any status besides 75, then it's a standard success or error. +(Zero is success; anything else other than 75 is an error). + +Example of a soft failure command: + +```yaml +commands: + - before: repository + run: + - findmnt /mnt/removable > /dev/null || exit 75 +``` + +### Caveats and details + +There are some caveats you should be aware of with this feature. + + * You'll generally want to put a soft failure command in a `before` command + hook, so as to gate whether the backup action occurs. While a soft failure is + also supported in an `after` command hook, returning a soft failure there + won't prevent any actions from occurring, because they've already occurred! + Similarly, you can return a soft failure from an `error` command hook, but at + that point it's too late to prevent the error. + * Returning a soft failure does prevent further commands in the same hook from + executing. So, like a standard error, it is an "early out." Unlike a standard + error, borgmatic does not display it in angry red text or consider it a + failure. + * New in version 1.9.0 Soft + failures in `action` or `before_*` command hooks only skip the current + repository rather than all repositories in a configuration file. + * If you're writing a soft failure script that you want to vary based on the + current repository, for instance so you can have multiple repositories in a + single configuration file, have a look at [variable + interpolation](#variable-interpolation) above. + And there's always still the option of putting anything that you don't want + soft-failed (like always-online cloud backups) in separate configuration + files from your soft-failing repositories. + * The soft failure doesn't have to test anything related to a repository. You + can even perform a test that individual source directories are mounted and + available. Use your imagination! + * Soft failures are not currently implemented for `everything`, + `before_everything`, or `after_everything` command hooks. + + ## Full configuration ```yaml diff --git a/docs/reference/source-code.md b/docs/reference/source-code.md index b4312e59..a627bc36 100644 --- a/docs/reference/source-code.md +++ b/docs/reference/source-code.md @@ -26,3 +26,34 @@ started. Starting at the top level, we have: So, broadly speaking, the control flow goes: `commands` → `config` followed by `commands` → `actions` → `borg` and `hooks`. + + +## Code style + +When writing code for borgmatic, start with [PEP +8](https://www.python.org/dev/peps/pep-0008/). But then, apply the following +deviations from it: + + * For strings, prefer single quotes over double quotes. + * Limit all lines to a maximum of 100 characters. + * Use trailing commas within multiline values or argument lists. + * For multiline constructs, put opening and closing delimiters on lines + separate from their contents. + * Within multiline constructs, use standard four-space indentation. Don't align + indentation with an opening delimiter. + * In general, spell out words in variable names instead of shortening them. + So, think `index` instead of `idx`. There are some notable exceptions to + this though (like `config`). + * Favor blank lines around logical code groupings, `if` statements, + `return`s, etc. Readability is more important than packing code tightly. + * Import fully qualified Python modules instead of importing individual + functions, classes, or constants. E.g., do `import os.path` instead of + `from os import path`. (Some exceptions to this are made in tests.) + * Only use classes and OOP as a last resort, such as when integrating with + Python libraries that require it. + * Prefer functional code where it makes sense, e.g. when constructing a + command (to subsequently execute imperatively). + +Since borgmatic uses [Ruff](https://docs.astral.sh/ruff/) for code lining and +formatting, many other code style requirements are also enforced when running +automated tests. diff --git a/docs/search.md b/docs/search.md index 3d476a38..8a4183a9 100644 --- a/docs/search.md +++ b/docs/search.md @@ -1,5 +1,5 @@ --- -title: Search documentation +title: Search the documentation eleventyExcludeFromCollections: true ---