diff --git a/NEWS b/NEWS index f577e9c6..e34c1e52 100644 --- a/NEWS +++ b/NEWS @@ -1,4 +1,7 @@ 2.0.4.dev0 + * #1073: Clarify the documentation about when an "after: error" command hook runs and how it + differs from other hooks: + https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/ * #1075: Fix an incorrect warning about Borg placeholders being unsupported in a command hook. 2.0.3 diff --git a/docs/how-to/add-preparation-and-cleanup-steps-to-backups.md b/docs/how-to/add-preparation-and-cleanup-steps-to-backups.md index 505ab0cd..8b44123b 100644 --- a/docs/how-to/add-preparation-and-cleanup-steps-to-backups.md +++ b/docs/how-to/add-preparation-and-cleanup-steps-to-backups.md @@ -74,10 +74,6 @@ commands: - echo "After successful create!" ``` -Additionally, when command hooks run, they respect the `working_directory` -option if it is configured, meaning that the hook commands are run in that -directory. - Each command in the `commands:` list has the following options: * `before` or `after`: Name for the point in borgmatic's execution that the commands should be run before or after, one of: @@ -92,6 +88,9 @@ Each command in the `commands:` list has the following options: * `fail`: An error occurred. * `run`: List of one or more shell commands or scripts to run when this command hook is triggered. +When command hooks run, they respect the `working_directory` option if it is +configured, meaning that the hook commands are run in that directory. + ### Order of execution @@ -113,11 +112,20 @@ borgmatic for the `create` and `prune` actions. Here's the order of execution: * Run `after: action` hooks for `prune`. * Run `after: repository` hooks (for the first repository). * Run `after: configuration` hooks (from the first configuration file). + * Run `after: error` hooks (if an error occurs). * Run `after: everything` hooks (from all configuration files). This same order of execution extends to multiple repositories and/or configuration files. +Based on the above, you can see the difference between, say, an `after: action` +hook with `states: [fail]` and an `after: error` hook. The `after: action hook` +runs immediately after the create action fails for a particular repository—so +before any subsequent actions for that repository or other repositories even +have a chance to run. Whereas the `after: error` hook doesn't run until all +actions for—and repositories in—a configuration file have had a chance to +execute. + ### Deprecated command hooks