mirror of
https://github.com/borgmatic-collective/borgmatic.git
synced 2026-08-06 08:13:01 +02:00
Additional documentation reference refactoring (#942).
This commit is contained in:
Dan Helfman
@@ -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.
|
||||
|
||||
|
||||
<a id="caveats-and-details"></a>
|
||||
|
||||
|
||||
## 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.
|
||||
* <span class="minilink minilink-addedin">New in version 1.9.0</span> 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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -26,7 +26,7 @@ arguments:
|
||||
* verbosity
|
||||
|
||||
|
||||
### borg action
|
||||
## borg action
|
||||
|
||||
<span class="minilink minilink-addedin">New in version 1.5.15</span> 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:
|
||||
|
||||
|
||||
@@ -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.
|
||||
* <span class="minilink minilink-addedin">New in version 1.9.0</span> 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
|
||||
|
||||
@@ -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.
|
||||
|
||||
+1
-1
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: Search documentation
|
||||
title: Search the documentation
|
||||
eleventyExcludeFromCollections: true
|
||||
---
|
||||
<link href="/borgmatic/pagefind/pagefind-ui.css" rel="stylesheet">
|
||||
|
||||
Reference in New Issue
Block a user