From a22f31dbb0058f234c1f3c74a8f4ce7933c8d712 Mon Sep 17 00:00:00 2001
From: Fontrodona Nicolas <nicolas.fontrodona@ens-lyon.fr>
Date: Tue, 14 Feb 2023 16:32:55 +0100
Subject: [PATCH] slides/slides.qmd slides/style.css: update

---
 slides/slides.qmd | 318 +++++++++++++++++++++++++++++++++++++++++++++-
 slides/style.css  |   7 +
 2 files changed, 323 insertions(+), 2 deletions(-)

diff --git a/slides/slides.qmd b/slides/slides.qmd
index 3bcb7c2..0f6c836 100644
--- a/slides/slides.qmd
+++ b/slides/slides.qmd
@@ -949,7 +949,6 @@ A global configuration file can also be defined by gblk automatically at `~/.gbl
 
 ## gblk configuration file - Pruning options
 
-**gblk pruning options (1/4)**
 
 To *add or update* settings for pruning in the local or global configuration file you can use the command:
 
@@ -1012,4 +1011,319 @@ $ gblk config show
 keep_within = '7d'
 $ gblk config rm keep-within # 'gblk config rm keep_within' also works
 $ gblk config show
-```
\ No newline at end of file
+No local pruning options defined
+```
+
+Use `gblk config show --global` to see the globally defined pruning options
+
+## gblk configuration file - Pruning options {.unnumbered .unlisted}
+
+To prune your results archives using the options defined in the global or local configuration you can use the following command:
+
+```sh
+gblk config prune [OPTION]
+```
+
+::: {.callout-important }
+If no options are defined, an error will be thrown:
+
+```sh
+$ gblk config prune --dry-run --list
+error: No global and local options defined for pruning!
+```
+:::
+
+
+You can see what option you can add to your command with
+
+```sh
+$ gblk config prune --help
+```
+<p><p>
+
+
+## gblk configuration file - Pruning options {.unnumbered .unlisted}
+
+::: {.callout-note}
+If both local and global pruning options are defined, only the *local settings are used*
+:::
+
+Example:
+
+```bash
+gblk config add keep-within '2d'
+gblk config add keep-weekly 3 --global
+gblk config prune --dry-run --list
+```
+```console
+Keeping archive (rule: within #1):       248a2... Tue, 2023-02-14 09:39:10 [ef885...]
+Keeping archive (rule: within #2):       964fe... Mon, 2023-02-13 09:12:50 [fef70...]
+Would prune:                             df0eb... Fri, 2023-02-10 16:15:56 [c9409...]
+```
+```bash
+gblk config rm keep-within
+gblk config prune --dry-run --list
+```
+```console
+Keeping archive (rule: weekly #1):       248a2... Tue, 2023-02-14 09:39:10 [ef885...]
+Would prune:                             964fe... Mon, 2023-02-13 09:12:50 [fef70...]
+Keeping archive (rule: weekly #2):       df0eb... Fri, 2023-02-10 16:15:56 [c9409...]
+```
+<p><p>
+
+## Sharing gblk repositories
+
+
+When you produce some results for a particular project, you may want to *share them with others* who are working with you. With gblk you can share your `.borg` repository with others or update it with chnages done by others.
+
+::: {.callout-note}
+The choice of sharing the complete archive folder `.borg` was made to always benefits from borg's deduplication
+:::
+
+::: {.callout-warning}
+The way of *duplicating and storing an archive folder* is not the way *borg was intended to be used*. Indeed the replacement of a borg repository by an older one *is considered suspicious* and **borg blocks the executions of its commands for this archive**. See [this page](https://borgbackup.readthedocs.io/en/stable/faq.html?highlight=attack#this-is-either-an-attack-or-unsafe-warning) for details.
+:::
+
+## gblk configuration file - Remotes
+
+To share your archived results, you can use *remotes* like in git.
+
+Remotes can be defined *globally* or *locally*:
+
+- *local* remotes are only defined for a given project
+- *global* remotes are available for any gblk projects. Useful if  to store your gblk results on a same location.
+
+::: {.callout-note}
+If a *global* remote have the same name as a *local* remote, only the local remote can be used for this project.
+
+- *local* remotes are defined in the file `.borg/.gblkconfig`
+- *global* remotes are defined in the file `~/.gblkconfig`
+:::
+
+## gblk configuration file - Remotes {.unnumbered .unlisted}
+
+A remote is defined by a:
+
+- A *name*: used to identify the remotes
+- A *path*: the path pointed by the remote
+
+    - Can be defined as `[USER@]HOSTNAME:PATH`
+    - Host defined in `ssh config file` can be used
+    - The *path* must point to an existing directory
+
+## gblk configuration file - Remotes {.unnumbered .unlisted}
+
+**Add a new remote**
+
+To *add a new local remote* you can use the following command:
+
+```sh
+gblk remote add KEY VALUE
+```
+
+- `KEY`: The name of the remote
+- `VALUE`: The URL it points to.
+
+To define a globally defined remote you can enter the following command:
+
+```sh
+gblk remote add KEY VALUE --global
+```
+::: {.callout-note}
+This command can also be used to uptade the value of an existing commands
+:::
+
+## gblk configuration file - Remotes {.unnumbered .unlisted}
+
+**Remove a remote**
+
+To remove a remote named `KEY` you can use this command
+
+```sh
+gblk remote rm KEY
+```
+
+You can add the flag `--global` at the end of the previous command to remove a globally defined remote.
+
+```sh
+gblk remote rm KEY --global
+```
+<p><p>
+
+## gblk configuration file - Remotes {.unnumbered .unlisted}
+
+**Displaying remotes**
+
+
+```sh
+gblk remote show
+```
+
+It will display *locally* and *globally* defined remotes.
+
+::: {.callout-note}
+Only unmasked `globally` remotes are displayed (e.g the global remotes that don't share a name with any local remotes).
+:::
+
+
+::: {.callout-tip}
+
+## Example
+
+
+```sh
+gblk remote add psmn psmn:/home/user/test_folder_local
+gblk remote add psmn psmn:/home/user/test_folder_global --global
+gblk remote add psmn2 psmn:/home/user/test_folder_global2 --global
+gblk remote show
+```
+```console
+psmn: psmn:/home/user/test_folder_local
+psmn2: psmn:/home/user/test_folder_global2      (global)
+```
+
+You can see that *globally* defined remotes are tagged with `(global)`.
+:::
+
+## gblk clone
+
+Can be used after a `git clone` command.
+
+If a gblk archive folder is available for the project, then you can execute the following command:
+
+```sh
+gblk clone [HOSTNAME:]PATH [--compression] [--hooks]
+```
+- [HOSTNAME:]: Optional, can be defined as `USER@HOSTNAME`. Hosts defined in `ssh config file` can be used
+- `PATH`: path of a gblk archive folder. The `PATH` must point to a folder with this structure (corresponding to a borg remote archive):
+
+```sh
+PATH
+├──  archive_list
+├──  config
+├──  data
+└──  README
+```
+::: {.callout-important}
+clone must be used with a *path* and *not a remote name*.
+:::
+
+## gblk clone {.unnumbered .unlisted}
+
+Here are the steps that the clone command execute:
+
+1. Checks if `.borg` folder already exists.
+2. Checks if the remote directory already exists and contains `data`, `config` and `archive_file` inside.
+3. Copies with rsync the remote directory into `.borg`
+4. Creates the local config file `.borg/.gblkconfig` using the name of the archive
+5. Add a local remote called `origin` into the local config file
+6. Creates a `.gitignore` and a `results/.gitignore`
+
+:::: {.columns}
+::: {.column width="50%"}
+```sh
+# .gitignore
+.borg
+.tmp
+.mount
+```
+:::
+
+::: {.column width="50%"}
+```sh
+# results/.gitignore
+*
+!.gitignore
+
+
+```
+:::
+::::
+
+7. Create hooks if needed
+
+## gblk push
+
+To copy the content of the `.borg` folder into another location you can use the `push` command like this:
+
+```sh
+gblkt push KEY
+```
+
+Where `KEY` is the name of a *global* or *local* remote. **Path are not supported!**.
+
+::: {.callout-warning}
+The push command might deletes old archives inside the remote archive folder folder !
+:::
+
+
+## gblk push {.unnumbered .unlisted}
+
+::: {.callout layout="minimal"}
+Here are the steps that the push command execute:
+
+1. Checks if the *remote folder* (defined by the remote) exists
+2. Checks if the *remote archive folder* (folder that will contains the archives) exits. It corresponds to the *path* of the remote and the name of the folder containing the `.borg` folder.
+3. If it doesn't exists:
+   - go to step 5
+4. If it exists:
+   - Checks if the borg id is the same between the remote and the local borg archive. Stops the command if not.
+   - gblk uses the `archive_list` file on the *remote archive folder* to compare it with the current archive list saved and show to the users the differences between the remote and the local archive lists.
+   - Then it asks the user whether or not to continue the push.
+5. Copies with rsync the content of the current `.borg` folder into the *remote archive folder*
+:::
+
+## gblk pull
+
+The pull commands allow to replace the content of your `.borg` archive into a remote folder.
+
+It can be used with the following command:
+
+```sh
+gblk  pull KEY
+```
+
+Where `KEY` is the name of a *global* or *local* remote. **Path are not supported!**.
+
+::: {.callout-note}
+The pull commands saves the inital content of the `.borg` folder inside the `.tmp` directory. **Remember to delete it if the pull is sucessful
+:::
+
+
+## gblk pull {.unnumbered .unlisted}
+
+
+::: {.callout layout="minimal"}
+
+Here are the steps that the pull command execute:
+
+1. Checks if the *remote folder* (defined by the remote) exists
+2. Checks if the *remote archive folder* (folder that will contains the archives) exits. If it doesn't, stops the pull.
+3. Checks if the borg id is the same between the remote and the local borg archive folder. Stops the pull if not.
+4. gblk uses the `archive_list` file on the *remote archive folder* to compare it with the current archive list saved and show to the users the differences between the remote and the local archive lists.
+5. Asks the user whether or not to continue the pull
+6. Saves and clean `.borg` folder. The content of the old `.borg` folder is saved inside the `.tmp` folder and can be recovered with the `gblk restore` command if something goes wrong afterward.
+7. Copies with rsync the content of the *remote archive folder* into the current `.borg` folder.
+8. Removes borg manifest timestamp and the cache associated to the current project archive folder.
+:::
+
+## gblk restore
+
+This command can be used to restore your 'old' `.borg` folder the way it was before the last pull command. It can help to recover from an error that occured during the pull.
+
+To restore your old `.borg` folder, enter the command
+
+```sh
+gblk restore
+```
+<p><p>
+
+## gblk clean
+
+
+After a `pull` or after using `gblk mount` with the `--diff` flag, temporary files are stored inside the `.tmp` directory. You can remove those with the command:
+
+```sh
+gblk clean
+```
+<p><p>
\ No newline at end of file
diff --git a/slides/style.css b/slides/style.css
index d058bd5..d54f119 100644
--- a/slides/style.css
+++ b/slides/style.css
@@ -96,4 +96,11 @@
     height: 1.2rem;
     background-size: 1.2rem, 1.2rem;
     margin-top: 0.7rem;
+}
+
+.reveal nav ul {
+    font-size: 1.1em;
+    columns: 2;
+    -webkit-columns: 2;
+    -moz-columns: 2;
 }
\ No newline at end of file
-- 
GitLab