From e53570bdd1fee590596377b8911828572659d25b Mon Sep 17 00:00:00 2001 From: simonsan <14062932+simonsan@users.noreply.github.com> Date: Sat, 5 Oct 2024 03:21:01 +0200 Subject: [PATCH 1/7] docs: add hooks intro Signed-off-by: simonsan <14062932+simonsan@users.noreply.github.com> --- src/SUMMARY.md | 1 + src/commands/misc/hooks.md | 91 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 92 insertions(+) create mode 100644 src/commands/misc/hooks.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 0f67a00..b7bd9cb 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -9,6 +9,7 @@ - [Nightly Builds](./nightly_builds.md) - [Completions](./commands/misc/completions.md) - [Getting Started](./getting_started.md) +- [Hooks](./commands/misc/hooks.md) - [Preparing a new repository](./commands/init/intro.md) - [Configuration File](./commands/init/configuration_file.md) - [Local Backend](./commands/init/local.md) diff --git a/src/commands/misc/hooks.md b/src/commands/misc/hooks.md new file mode 100644 index 0000000..64211ba --- /dev/null +++ b/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 = [] +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, world!'"] +``` + +In this example, the command `echo 'Hello, world!'` is executed before any +command is executed. + +If you want to run multiple commands, you can add them to the list: + +```toml +[global.hooks] +run-before = ["sh -c 'echo Hello, world!'"] +run-after = ["sh -c 'echo Goodbye, world!'"] +``` + +In this example, the command `echo 'Hello, world!'` is executed before any +command is executed, and the command `echo 'Goodbye, world!'` is executed after +any command is executed. + +You can use that, e.g. to send a notification when a backup has finished: + +```toml +[backup.hooks] +run-after = ["notify-send 'Backup finished'"] +``` + +You can also use the `--json` option to get the output of the command in JSON +format. This can be useful if you want to parse the output of a command in a +script. From de48f3bc5876957fa7b9d7be9f7f6662077a4e54 Mon Sep 17 00:00:00 2001 From: simonsan <14062932+simonsan@users.noreply.github.com> Date: Sat, 5 Oct 2024 03:22:30 +0200 Subject: [PATCH 2/7] move hooks into 'working with repositories' Signed-off-by: simonsan <14062932+simonsan@users.noreply.github.com> --- src/SUMMARY.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index b7bd9cb..2e9af8e 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -9,7 +9,6 @@ - [Nightly Builds](./nightly_builds.md) - [Completions](./commands/misc/completions.md) - [Getting Started](./getting_started.md) -- [Hooks](./commands/misc/hooks.md) - [Preparing a new repository](./commands/init/intro.md) - [Configuration File](./commands/init/configuration_file.md) - [Local Backend](./commands/init/local.md) @@ -37,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) From 1b60b8a37c8d229e394de3596a404e9649841596 Mon Sep 17 00:00:00 2001 From: simonsan <14062932+simonsan@users.noreply.github.com> Date: Sat, 5 Oct 2024 04:31:15 +0200 Subject: [PATCH 3/7] Update hooks.md --- src/commands/misc/hooks.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/commands/misc/hooks.md b/src/commands/misc/hooks.md index 64211ba..7db221e 100644 --- a/src/commands/misc/hooks.md +++ b/src/commands/misc/hooks.md @@ -86,6 +86,6 @@ You can use that, e.g. to send a notification when a backup has finished: run-after = ["notify-send 'Backup finished'"] ``` -You can also use the `--json` option to get the output of the command in JSON -format. This can be useful if you want to parse the output of a command in a -script. +You can also use the `--json` option to get the output of a rustic command in +JSON format. This can be useful if you want to parse the output and use it in +a script. From 8f1a83a2f0bd336daa3e412718a5c933b656eebc Mon Sep 17 00:00:00 2001 From: simonsan <14062932+simonsan@users.noreply.github.com> Date: Sat, 5 Oct 2024 04:59:08 +0200 Subject: [PATCH 4/7] Update src/commands/misc/hooks.md --- src/commands/misc/hooks.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/commands/misc/hooks.md b/src/commands/misc/hooks.md index 7db221e..fa5c788 100644 --- a/src/commands/misc/hooks.md +++ b/src/commands/misc/hooks.md @@ -87,5 +87,5 @@ run-after = ["notify-send 'Backup finished'"] ``` You can also use the `--json` option to get the output of a rustic command in -JSON format. This can be useful if you want to parse the output and use it in -a script. +JSON format. This can be useful if you want to parse the output and use it in a +script. From 6d91e56a0392196fc659edd82678beb039203028 Mon Sep 17 00:00:00 2001 From: simonsan <14062932+simonsan@users.noreply.github.com> Date: Sun, 6 Oct 2024 21:52:18 +0200 Subject: [PATCH 5/7] apply suggestions from review Signed-off-by: simonsan <14062932+simonsan@users.noreply.github.com> --- src/commands/misc/hooks.md | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/src/commands/misc/hooks.md b/src/commands/misc/hooks.md index fa5c788..7787913 100644 --- a/src/commands/misc/hooks.md +++ b/src/commands/misc/hooks.md @@ -46,7 +46,12 @@ run-finally = [] [[backup.snapshots]] sources = [] -hooks = { run-before = [], run-after = [], run-failed = [], run-finally = [] } + +[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 @@ -61,11 +66,16 @@ For example: ```toml [global.hooks] -run-before = ["sh -c 'echo Hello, world!'"] +run-before = [ + "sh -c 'echo Hello > test.out'", + "sh -c 'echo World >> test.out'", +] ``` -In this example, the command `echo 'Hello, world!'` is executed before any -command is executed. +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. The commands in a hook are executed in order. If you want to run multiple commands, you can add them to the list: @@ -75,15 +85,15 @@ run-before = ["sh -c 'echo Hello, world!'"] run-after = ["sh -c 'echo Goodbye, world!'"] ``` -In this example, the command `echo 'Hello, world!'` is executed before any -command is executed, and the command `echo 'Goodbye, world!'` is executed after -any command is executed. +In this example, the command `echo 'Hello, world!'` is executed globally before +any command is executed, and the command `echo 'Goodbye, world!'` is executed +globally after any command is executed. You can use that, e.g. to send a notification when a backup has finished: ```toml [backup.hooks] -run-after = ["notify-send 'Backup finished'"] +run-after = ["notify-send 'Backup finished successfully!'"] ``` You can also use the `--json` option to get the output of a rustic command in From ff136e40f03ea7bfd996aed2704e1b5e89293905 Mon Sep 17 00:00:00 2001 From: simonsan <14062932+simonsan@users.noreply.github.com> Date: Sun, 6 Oct 2024 21:59:01 +0200 Subject: [PATCH 6/7] apply suggestions from review Signed-off-by: simonsan <14062932+simonsan@users.noreply.github.com> --- src/commands/misc/hooks.md | 29 +++++++++-------------------- 1 file changed, 9 insertions(+), 20 deletions(-) diff --git a/src/commands/misc/hooks.md b/src/commands/misc/hooks.md index 7787913..bc548f0 100644 --- a/src/commands/misc/hooks.md +++ b/src/commands/misc/hooks.md @@ -67,35 +67,24 @@ For example: ```toml [global.hooks] run-before = [ - "sh -c 'echo Hello > test.out'", - "sh -c 'echo World >> test.out'", + "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. The commands in a hook are executed in order. +writes `Hello,` to a file called `test.out`, and the second command appends +`World!` to the same file. The commands in a hook are executed in order. -If you want to run multiple commands, you can add them to the list: +After any 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`. -```toml -[global.hooks] -run-before = ["sh -c 'echo Hello, world!'"] -run-after = ["sh -c 'echo Goodbye, world!'"] -``` - -In this example, the command `echo 'Hello, world!'` is executed globally before -any command is executed, and the command `echo 'Goodbye, world!'` is executed -globally after any command is executed. - -You can use that, e.g. to send a notification when a backup has finished: +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!'"] ``` - -You can also use the `--json` option to get the output of a rustic command in -JSON format. This can be useful if you want to parse the output and use it in a -script. From d2608e4d1cc0f664fb1a8db0a8779aaac4380361 Mon Sep 17 00:00:00 2001 From: simonsan <14062932+simonsan@users.noreply.github.com> Date: Sun, 6 Oct 2024 22:00:49 +0200 Subject: [PATCH 7/7] fix explanations Signed-off-by: simonsan <14062932+simonsan@users.noreply.github.com> --- src/commands/misc/hooks.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/commands/misc/hooks.md b/src/commands/misc/hooks.md index bc548f0..57c698b 100644 --- a/src/commands/misc/hooks.md +++ b/src/commands/misc/hooks.md @@ -76,11 +76,12 @@ 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. The commands in a hook are executed in order. +`World!` to the same file on a new line. The commands within the list of a hook +are executed in order. -After any 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`. +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: