borgmatic/docs/reference/configuration/command-hooks.md

title, eleventyNavigation

title	eleventyNavigation
Command hooks	key parent 🪝 Command hooks ⚙️ Configuration

New in version 2.0.0 Command hooks are configured via a list of commands: in your borgmatic configuration file. For example:

commands:
    - before: action
      when: [create]
      run:
          - echo "Before create!"
    - after: action
      when:
          - create
          - prune
      run:
          - echo "After create or prune!"
    - after: error
      run:
          - echo "Something went wrong!"

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:
  • action runs before or after each action for each repository. This replaces the deprecated before_create, after_prune, etc.
  • repository runs before or after all actions for each repository. This replaces the deprecated before_actions and after_actions.
  • configuration runs before or after all actions and repositories in the current configuration file.
  • everything runs before or after all configuration files. Errors here do not trigger error hooks or the fail state in monitoring hooks. This replaces the deprecated before_everything and after_everything.
  • error runs after an error occurs—and it's only available for after. This replaces the deprecated on_error hook.
• when: Only trigger the hook when borgmatic is run with particular actions (create, prune, etc.) listed here. Defaults to running for all actions.
• states: New in version 2.0.3 Only trigger the hook if borgmatic encounters one of the states (execution results) listed here. This state is evaluated only for the scope of the configured action, repository, etc., rather than for the entire borgmatic run. Only available for after hooks. Defaults to running the hook for all states. One or more of:
  • finish: No errors occurred.
  • 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.

New in version 2.0.4If the exact same everything command hook is present in multiple configuration files, borgmatic only runs it once.

borgmatic's --repository flag does not impact which command hooks get run. But you can use the --config flag to limit the configuration files (and thus command hooks) used.

Order of execution

Here's a way of visualizing how all of these command hooks slot into borgmatic's execution.

Let's say you've got a borgmatic configuration file with a configured repository. And suppose you configure several command hooks and then run borgmatic for the create and prune actions. Here's the order of execution:

• Run before: everything hooks (from all configuration files).
  • Run before: configuration hooks (from the first configuration file).
    • Run before: repository hooks (for the first repository).
      • Run before: action hooks for create.
      • Actually run the create action (e.g. borg create).
      • Run after: action hooks for create.
      • Run before: action hooks for prune.
      • Actually run the prune action (e.g. borg prune).
      • 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.

And if there are multiple hooks defined for a particular step (e.g. before: action for create), then those hooks are run in the order they're defined in configuration.

Variable interpolation

The command action hooks support interpolating particular runtime variables into the commands that are run. Here's are a couple examples that assume you provide separate shell scripts:

commands:
    - after: action
      when: [prune]
      run:
          - record-prune.sh {configuration_filename} {repository}
    - after: error
      when: [create]
      run:
          - send-text-message.sh {configuration_filename} {repository}

In this example, when the hook is triggered, borgmatic interpolates runtime values into each hook command: the borgmatic configuration filename and the paths of the current Borg repository.

Here's the full set of supported variables you can use here:

• configuration_filename: borgmatic configuration filename in which the hook was defined
• log_file New in version 1.7.12: path of the borgmatic log file, only set when the --log-file flag is used
• repository: path of the current repository as configured in the current borgmatic configuration file, if applicable to the current hook
• repository_label New in version 1.8.12: label of the current repository as configured in the current borgmatic configuration file, if applicable to the current hook
• error: the error message itself, only applies to error hooks
• output: output of the command that failed, only applies to error hooks (may be blank if an error occurred without running a command)

Not all command hooks support all variables. For instance, the everything and configuration hooks don't support repository variables because those hooks don't run in the context of a single repository. But the deprecated command hooks (before_backup, on_error, etc.) do generally support variable interpolation.

borgmatic automatically escapes these interpolated values to prevent shell injection attacks. One implication is that you shouldn't wrap the interpolated values in your own quotes, as that will interfere with the quoting performed by borgmatic and result in your command receiving incorrect arguments. For instance, this won't work:

commands:
    - after: error
      run:
          # Don't do this! It won't work, as the {error} value is already quoted.
          - send-text-message.sh "Uh oh: {error}"

Do this instead:

commands:
    - after: error
      run:
          - send-text-message.sh {error}

Note that you can also interpolate arbitrary environment variables.

Full configuration

{% include borgmatic/commands.yaml %}