add docu, examples and tests

rustic-rs · Sep 2, 2024 · 50d670e · 50d670e
1 parent 36282a1
commit 50d670e
Show file tree

Hide file tree

Showing 5 changed files with 87 additions and 5 deletions.
diff --git a/config/README.md b/config/README.md
@@ -65,6 +65,17 @@ If you want to contribute your own configuration, please
 | progress-interval | The interval at which progress indicators are shown.                              | "100ms"       | "1m"                     | RUSTIC_PROGRESS_INTERVAL |
 | use-profile       | Profile or array of profiles to use. Allows to recursely use other profiles.      | Empty array   | "other" , ["2nd", "3rd"] | RUSTIC_USE_PROFILE       |
 
+### Global Hooks
+
+These external commands are before and after each commands, respectively.
+
+| Attribute   | Description                                      | Default Value | Example Value                 | Environment Variable |
+| ----------- | ------------------------------------------------ | ------------- | ----------------------------- | -------------------- |
+| run-before  | Run the given command before execution           | not set       | "echo test", ["echo", "test"] |                      |
+| run-after   | Run the given command after successful execution | not set       | "echo test", ["echo", "test"] |                      |
+| run-failed  | Run the given command after failed execution     | not set       | "echo test", ["echo", "test"] |                      |
+| run-finally | Run the given command after every execution      | not set       | "echo test", ["echo", "test"] |                      |
+
 ### Global Options - env variables
 
 All given environment variables are set before processing. This is handy to
@@ -147,11 +158,26 @@ can be overwritten in the source-specifc configuration, see below.
 | time                  | Set the time saved in the snapshot.                                                     | Not set               |               |
 | with-atime            | If true, includes file access time (atime) in the backup.                               | false                 |               |
 
+### Backup Hooks
+
+These external commands are before and after each backup, respectively. Note
+that global hooks are run additionaly.
+
+| Attribute   | Description                                      | Default Value | Example Value                 | Environment Variable |
+| ----------- | ------------------------------------------------ | ------------- | ----------------------------- | -------------------- |
+| run-before  | Run the given command before execution           | not set       | "echo test", ["echo", "test"] |                      |
+| run-after   | Run the given command after successful execution | not set       | "echo test", ["echo", "test"] |                      |
+| run-failed  | Run the given command after failed execution     | not set       | "echo test", ["echo", "test"] |                      |
+| run-finally | Run the given command after every execution      | not set       | "echo test", ["echo", "test"] |                      |
+
 ### Backup Sources
 
 **Note**: All of the backup options mentioned before can also be used as
 source-specific option and then only apply to this source.
 
+Source-specific hooks are called when backup up the defined source, additionally
+to global and backup hooks. only apply
+
 | Attribute | Description                          | Default Value | Example Value               |
 | --------- | ------------------------------------ | ------------- | --------------------------- |
 | source    | Source directory or file to back up. | Not set       | "/dir" , ["/dir1", "/dir2"] |

diff --git a/config/full-one.toml b/config/full-one.toml
@@ -19,6 +19,13 @@ progress-interval = "100ms"
 dry-run = false
 check-index = false
 
+# Global hooks: The given commands are called for every command
+[global.hooks]
+run-before = "echo before" # Default: not set
+run-after = "echo after" # Run after if successful, default: not set
+run-failed = "echo failed" # Default: not set
+run-finally = "echo finally" # Always run after, default: not set
+
 # Global env variables: These are set by rustic before calling a subcommand, e.g. rclone or commands
 # defined in the repository options.
 [global.env]
@@ -111,12 +118,26 @@ no-scan = false
 quiet = false
 skip-identical-parent = false
 
+# Backup hooks: The given commands are called for the `backup` command
+[backup.hooks]
+run-before = "echo before" # Default: not set
+run-after = "echo after" # Run after if successful, default: not set
+run-failed = "echo failed" # Default: not set
+run-finally = "echo finally" # Always run after, default: not set
+
 # Backup options for specific sources - all above options are also available here and replace them for the given source
 [[backup.sources]]
 source = "/path/to/source1"
 label = "label" # Default: not set
 # .. and so on. see [backup]
 
+# Source-specific hooks: The given commands when backing up the defined source
+[backup.sources.hooks]
+run-before = "echo before" # Default: not set
+run-after = "echo after" # Run after if successful, default: not set
+run-failed = "echo failed" # Default: not set
+run-finally = "echo finally" # Always run after, default: not set
+
 # forget options
 [forget]
 prune = false

diff --git a/config/full.toml b/config/full.toml
@@ -16,6 +16,13 @@ progress-interval = "100ms"
 dry-run = false
 check-index = false
 
+# Global hooks: The given commands are called for every command
+[global.hooks]
+run-before = ["echo", "before"] # Default: not set
+run-after = ["echo", "after"] # Run after if successful, default: not set
+run-failed = ["echo", "failed"] # Default: not set
+run-finally = ["echo", "finally"] # Always run after, default: not set
+
 # Global env variables: These are set by rustic before calling a subcommand, e.g. rclone or commands
 # defined in the repository options.
 [global.env]
@@ -108,12 +115,26 @@ no-scan = false
 quiet = false
 skip-identical-parent = false
 
+# Backup hooks: The given commands are called for the `backup` command
+[backup.hooks]
+run-before = ["echo", "before"] # Default: not set
+run-after = ["echo", "after"] # Run after if successful, default: not set
+run-failed = ["echo", "failed"] # Default: not set
+run-finally = ["echo", "finally"] # Always run after, default: not set
+
 # Backup options for specific sources - all above options are also available here and replace them for the given source
 [[backup.sources]]
 source = "/path/to/source1"
 label = "label" # Default: not set
 # .. and so on. see [backup]
 
+# Source-specific hooks: The given commands when backing up the defined source
+[backup.sources.hooks]
+run-before = ["echo", "before"] # Default: not set
+run-after = ["echo", "after"] # Run after if successful, default: not set
+run-failed = ["echo", "failed"] # Default: not set
+run-finally = ["echo", "finally"] # Always run after, default: not set
+
 [[backup.sources]]
 source = [
   "/path/to/source2",

diff --git a/tests/show-config-fixtures/empty.txt → tests/show-config-fixtures/empty.toml b/tests/show-config-fixtures/empty.txt → tests/show-config-fixtures/empty.toml
@@ -4,6 +4,12 @@ dry-run = false
 check-index = false
 no-progress = false
 
+[global.hooks]
+run-before = ""
+run-after = ""
+run-failed = ""
+run-finally = ""
+
 [global.env]
 
 [repository]
@@ -50,6 +56,12 @@ delete-never = false
 sources = []
 source = []
 
+[backup.hooks]
+run-before = ""
+run-after = ""
+run-failed = ""
+run-finally = ""
+
 [copy]
 targets = []
 

diff --git a/tests/show-config.rs b/tests/show-config.rs
@@ -35,13 +35,15 @@ fn cmd_runner() -> CmdRunner {
     LAZY_RUNNER.clone()
 }
 
-fn fixtures_dir() -> PathBuf {
-    ["tests", "show-config-fixtures"].iter().collect()
+fn fixture() -> PathBuf {
+    ["tests", "show-config-fixtures", "empty.toml"]
+        .iter()
+        .collect()
 }
 
 #[test]
 fn show_config_passes() -> TestResult<()> {
-    let fixture_path = fixtures_dir().join("empty.txt");
+    let fixture_file = fixture();
     let mut file = get_temp_file()?;
 
     {
@@ -56,8 +58,8 @@ fn show_config_passes() -> TestResult<()> {
         cmd.wait()?.expect_success();
     }
 
-    if files_differ(fixture_path, file.path())? {
-        panic!("generated completions for bash shell differ, breaking change!");
+    if files_differ(fixture_file, file.path())? {
+        panic!("generated empty.toml differs, breaking change!");
     }
 
     Ok(())