docs: Add hooks documentation (#94)

This pull request adds documentation for hooks in the `rustic`
repository. Hooks allow for the execution of custom scripts or commands
before or after certain commands, such as backup or restore. The
documentation provides an overview of the different types of hooks and
their configuration options. It also includes examples of how to use
hooks and run shell commands within hooks.

---------

Signed-off-by: simonsan <[email protected]>
Co-authored-by: aawsome <[email protected]>

src/SUMMARY.md

@@ -36,6 +36,7 @@
   - [Checking Integrity and Consistency](./commands/misc/check.md)
   - [Managing Repository Keys](./commands/misc/key.md)
   - [Upgrading the Repository Format Version](./commands/misc/upgrading_repository_format.md)
+  - [Hooks](./commands/misc/hooks.md)
 - [Restoring data from backups](./commands/restore/intro.md)
   - [Using mount](./commands/restore/using_mount.md)
   - [Printing files to StdOut](./commands/restore/printing_stdout.md)

src/commands/misc/hooks.md

@@ -0,0 +1,91 @@
+# Hooks
+
+`rustic` supports hooks that are executed before and after certain commands.
+This allows you to run custom scripts or commands before or after a backup,
+restore, or other commands.
+
+## Overview
+
+`rustic` supports the following hooks (in order):
+
+- `run-before` is executed either on a global level, before accessing the
+  repository, or before a specific command (e.g. backup).
+- `run-after` is executed either on a global level, after accessing the
+  repository, or after a specific command (e.g. backup).
+- `run-failed` is executed if a command before has failed.
+- `run-finally` is executed after all other hooks of the same type have been
+  executed, regardless of whether they succeeded or failed.
+
+## Configuration
+
+**Important**: For always up-to-date information, please make sure to check the
+in-repository documentation for the config files available
+[here](https://github.com/rustic-rs/rustic/blob/main/config/README.md).
+
+Hooks are configured in the profile configuration file. Here is an example of a
+configuration file with all possible hooks:
+
+```toml
+[global.hooks]
+run-before = []
+run-after = []
+run-failed = []
+run-finally = []
+
+[repository.hooks]
+run-before = []
+run-after = []
+run-failed = []
+run-finally = []
+
+[backup.hooks]
+run-before = []
+run-after = []
+run-failed = []
+run-finally = []
+
+[[backup.snapshots]]
+sources = []
+
+[backup.snapshots.hooks]
+run-before = []
+run-after = []
+run-failed = []
+run-finally = []
+```
+
+Each hook is a list of commands that are executed in order. If you want to run a
+script or command, you can add it to the list.
+
+Hooks are also not executed in a shell, so you can't use shell features like
+pipes or redirects. If you need to use shell features, you can run a shell
+command that executes the desired command. Within the shell command, you can use
+shell features.
+
+For example:
+
+```toml
+[global.hooks]
+run-before = [
+  "sh -c  'echo Hello, > test.out'",
+  "sh -c  'echo World! >> test.out'",
+]
+run-after = ["sh -c 'echo Goodbye, world! >> test.out'"]
+```
+
+In this example, the `run-before` hook is executed globally before any command
+is executed. Within the hook, two commands are executed. The first command
+writes `Hello,` to a file called `test.out`, and the second command appends
+`World!` to the same file on a new line. The commands within the list of a hook
+are executed in order.
+
+So, after any other command is executed globally, the `run-after` hook is
+executed. In this case, the command `echo 'Goodbye, world!'` is executed, and
+the output is appended to the file `test.out` in a new line.
+
+You can use hooks, e.g. to send a notification when a backup has finished:
+
+```toml
+[backup.hooks]
+run-after = ["notify-send 'Backup finished successfully!'"]
+```