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,49 @@
+# Migration from `1.7` to `1.8`
+
+## ⚠️ Important notes
+
+The way snapshots are referenced in the `restore` and `prune` commands has been changed. Before they were referenced by the path. Now every backup is tagged and those tags are then referenced in the cli. This means that when running restore and forget commands old backups are not taken into account anymore.
+
+## 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)