Update docs to explain restore hooks feature and add a migration guide

Author: Romain de Laage

docs/markdown/_toc.md

@@ -45,6 +45,7 @@
 >
 > [0.x → 1.0](/migration/0.x_1.0)
 > [1.4 → 1.5](/migration/1.4_1.5)
+> [1.7 → 1.8](/migration/1.7_1.8)
 
 [Examples](/examples)
 [Docker](/docker)

docs/markdown/config.md

@@ -55,10 +55,11 @@ version: 2
 
 extras:
   hooks: &foo
-    before:
-      - echo "Hello"
-    after:
-      - echo "kthxbye"
+    backup:
+      before:
+        - echo "Hello"
+      after:
+        - echo "kthxbye"
   policies: &bar
     keep-daily: 14
     keep-weekly: 52

docs/markdown/examples.md

@@ -22,12 +22,13 @@ autorestic exec -b my-backend -- unlock
 extras:
   healthchecks: &healthchecks
     hooks:
-      before:
-        - 'curl -m 10 --retry 5 -X POST -H "Content-Type: text/plain" --data "Starting backup for location: ${AUTORESTIC_LOCATION}" https://<healthchecks-url>/ping/<uid>/start'
-      failure:
-        - 'curl -m 10 --retry 5 -X POST -H "Content-Type: text/plain" --data "Backup failed for location: ${AUTORESTIC_LOCATION}" https://<healthchecks-url>/ping/<uid>/fail'
-      success:
-        - 'curl -m 10 --retry 5 -X POST -H "Content-Type: text/plain" --data "Backup successful for location: ${AUTORESTIC_LOCATION}" https://<healthchecks-url>/ping/<uid>'
+      backup:
+        before:
+          - 'curl -m 10 --retry 5 -X POST -H "Content-Type: text/plain" --data "Starting backup for location: ${AUTORESTIC_LOCATION}" https://<healthchecks-url>/ping/<uid>/start'
+        failure:
+          - 'curl -m 10 --retry 5 -X POST -H "Content-Type: text/plain" --data "Backup failed for location: ${AUTORESTIC_LOCATION}" https://<healthchecks-url>/ping/<uid>/fail'
+        success:
+          - 'curl -m 10 --retry 5 -X POST -H "Content-Type: text/plain" --data "Backup successful for location: ${AUTORESTIC_LOCATION}" https://<healthchecks-url>/ping/<uid>'
 
 locations:
   something:

docs/markdown/location/hooks.md

@@ -1,8 +1,8 @@
 # Hooks
 
-If you want to perform some commands before and/or after a backup, you can use hooks.
+If you want to perform some commands before and/or after a backup or restore, you can use hooks.
 
-They consist of a list of commands that will be executed in the same directory as the target `from`.
+They consist of a list of commands that will be executed in the same directory as the config file or in the `dir` directory if configured.
 
 The following hooks groups are supported, none are required:
 
@@ -17,16 +17,27 @@ locations:
     from: /data
     to: my-backend
     hooks:
-      before:
-        - echo "One"
-        - echo "Two"
-        - echo "Three"
-      after:
-        - echo "Byte"
-      failure:
-        - echo "Something went wrong"
-      success:
-        - echo "Well done!"
+      backup:
+        before:
+          - echo "One"
+          - echo "Two"
+          - echo "Three"
+        after:
+          - echo "Byte"
+        failure:
+          - echo "Something went wrong"
+        success:
+          - echo "Well done!"
+      restore:
+        dir: /var/www/html
+        before:
+          - echo "Let's restore this backup!"
+        after:
+          - echo "Finished to restore"
+        failure:
+          - echo "A problem has been encountered :("
+        success:
+          - echo "Successfully restored!"
 ```
 
 ## Flowchart

docs/markdown/migration/1.7_1.8.md

@@ -0,0 +1,45 @@
+# Migration from `1.7` to `1.8`
+
+## Config files
+
+- The config version have been changed
+- You can now configure restore hooks
+
+See detailed instructions below.
+
+## Config Version
+
+The version field of the config file has been changed from `2` to `3`.
+
+## Hooks
+
+Since `1.8` both backup and restore hooks are possible.
+For this reason, backup hooks have been moved one layer deeper, you have to move them in a `backup` object.
+
+Before:
+
+```yaml
+locations:
+  l1:
+    # ...
+    from: /foo/bar
+    hooks:
+      before:
+        - pwd
+```
+
+After:
+
+```yaml
+locations:
+  l1:
+    # ...
+    from: /foo/bar
+    hooks:
+      backup:
+        before:
+          - pwd
+      restore:
+        after:
+          - echo "My super restore hook"
+```

docs/markdown/migration/index.md

@@ -2,3 +2,4 @@
 
 - [From 0.x to 1.0](/migration/0.x_1.0)
 - [From 1.4 to 1.5](/migration/1.4_1.5)
+- [From 1.7 to 1.8](/migration/1.7_1.8)